vinta-ui-composer-prototype-mode

The platform runtime module a design system's interactive components read to decide inert-vs-navigating in a shared prototype (spec UC-4). It owns only the context shape — PrototypeModeProvider, usePrototypeMode, and the value types — never a router.

Why this is a platform module, not part of a design system

A design system's interactive components (the reference DS's Link) must read prototype mode from a module the platform controls at runtime, so that the /p/* viewer's PrototypeModeProvider and the DS component's usePrototypeMode() share one context instance. This is the same singleton problem as react, and it has the same fix: the platform bundles the DS with this specifier marked external, then shims it to the host app's own copy at runtime (@vinta-ui-composer/puck-config/runtime-import). If a DS inlined its own createContext() instead, the host's provider could never reach it — clicks would be dead.

Because it is platform-owned, it lives here — not inside @vinta-ui-composer/design-system (the reference DS consumes it exactly the way an external DS must, via a peerDependency + the bare specifier).

How an external design system consumes it (CONTRACT.md §8)

Declare it as a peerDependency (never a regular dependency — the platform provides it at runtime, like react):

{
  "peerDependencies": {
    "vinta-ui-composer-prototype-mode": "^0.1.0"
  }
}

and import the bare specifier — never a relative path or a bundled-in copy:

import { usePrototypeMode } from "vinta-ui-composer-prototype-mode";

See packages/design-system/src/components/link.tsx for the reference implementation and packages/design-system/CONTRACT.md §8 for the full rule.

Publishing

Publishing this package to the npm registry so external design systems can resolve the peer at install time is a user-owned release step — it is intentionally not performed here. The workspace-private status is fine for now; the structural boundary (a platform module, separate from any DS) is what this package establishes.