proto-plugin 0.1.0 → 0.1.2

package/AGENTS.md

@@ -26,6 +26,47 @@ Host prototypes import framework from `prototype` and UI from `@/components/ui`.
 
 ---
 
+## Viewport layout vs responsive UI
+
+The review toolbar **Layout** toggle (desktop / mobile) only changes the **preview frame** — it sets `#prototype-viewport` dimensions and `data-prototype-viewport-layout` for shell chrome (device frame, footer behavior). It must **not** drive product UI differences inside prototype content.
+
+**Host prototype content** must respond to **viewport width** only:
+
+- Tailwind breakpoints (`sm:`, `md:`, …) or container queries for CSS
+- `matchMedia` / resize observers when JS must branch
+
+**Do not use** for layout or component swaps inside `src/prototypes/`:
+
+- `prototype-desktop:` / `prototype-mobile:` variants (deprecated; do not reintroduce)
+- `usePrototypeMobileViewportFrame()` / `usePrototypeViewportFrame()` for UI branching
+- `review.viewportLayout` or `data-prototype-viewport-layout` in prototype components
+
+The mobile preview frame is 390×844px; the desktop frame fills the preview stage. Breakpoints apply to the **content viewport width** — the same surface users see in production.
+
+---
+
+## Tool theme vs prototype preview content
+
+The gallery/review **light/dark mode toggle** only changes **tool chrome** (sidebar, header, gallery nav, modals). It must **never** change colors, typography, or tokens inside prototype preview content (`#prototype-viewport` / `[data-prototype-screenshot]`).
+
+**Tool theme** is scoped to `[data-prototype-root]` via `--tool-chrome-*` and `data-prototype-comment-theme`. Tool UI uses those tokens (or Tailwind utilities whose `--color-*` values resolve from `[data-prototype-root]`).
+
+**Prototype preview content** uses fixed **product** tokens from the synced source app. Host `globals.css` defines `--product-*` names and maps them to shadcn tokens inside `[data-prototype-screenshot]` only. Package CSS resets all semantic and `--color-*` tokens on `[data-prototype-screenshot]` so tool theme cannot cascade in.
+
+**Do not use** for styling inside `src/prototypes/`:
+
+- `usePrototypeToolTheme()` / `useLightTheme` / `commentTheme`
+- `data-prototype-comment-theme` on prototype components
+- `--tool-chrome-*` tokens in prototype JSX or CSS
+
+**Do not** in package or host CSS:
+
+- Bridge shadcn tokens (`--background`, `--foreground`, `--card`, …) to `--tool-chrome-*` on `[data-prototype-root]`
+- Map host `@theme inline` `--color-*` to `var(--background)` — use self-referential `var(--color-*)` for tool chrome; product tokens belong in `[data-prototype-screenshot]` only
+- Put product token values on `:root` without the `--product-*` prefix (tool theme would override them)
+
+---
+
 ## Relationship to source app (host apps)
 
 Host apps replicate product UI from the **source application** (linked read-only via `SOURCE_PATH` and `pnpm link-source`) **exactly** — standalone code, no runtime imports from the source monorepo.
@@ -66,7 +107,7 @@ The sync/link scripts are host-agnostic — package code names nothing host-spec
 
 Default to **mock data only**.
 
-Reference prototype: `example-feature` — `src/prototypes/example-feature/` (or any registered slug in your host app).
+Reference prototype: `booking-flow` — `src/prototypes/booking-flow/` (or any registered slug in your host app).
 
 ---
 
@@ -79,8 +120,8 @@ Shareable UI at `/prototypes/[slug]`. Registered in `prototype.config.ts`.
 ### Rules (mandatory)
 
 1. **Register** the slug in `prototype.config.ts` and add a screenshot under `public/prototypes/screenshots/`.
-2. **Create** `src/prototypes/<slug>/component-ids.ts` — every component target id (see `example-feature/component-ids.ts`).
-3. **Wire comments** with `usePrototypeComments` on the page (see `example-feature/index.tsx`).
+2. **Create** `src/prototypes/<slug>/component-ids.ts` — every component target id (see `booking-flow/component-ids.ts`).
+3. **Wire comments** with `usePrototypeComments(liveState, onRestore)` on the page (see `booking-flow/index.tsx`).
 4. **Wrap the root JSX of every React component** in `PrototypeComponent` from `prototype`.
 5. **On-page prototype controls** (state pickers, variant tabs, preview toggles) must use `PrototypeControl` or `PrototypeControlGroup`, not plain `PrototypeComponent`.
 6. **Use ids from the registry only** — dev mode logs an error for unregistered ids.
@@ -88,9 +129,58 @@ Shareable UI at `/prototypes/[slug]`. Registered in `prototype.config.ts`.
   - File's main export: kebab-case filename (`settings-section.tsx` → `settings-section`; `index.tsx` → `page`).
   - Other functions in the same file: `{filename}.{function-kebab}`.
   - Dynamic list items: add a prefix to `dynamicPrefixes` in `component-ids.ts`.
-8. **Scroll container:** `PrototypeComponent` with `id="scroll-container"` on the main `overflow-y-auto` wrapper.
+8. **Scroll container:** `PrototypeComponent` with `id="scroll-container"` — see **Prototype viewport fill** below.
 9. **Do not** use `data-testid` for comment anchoring.
 
+### Prototype viewport fill (avoid offset / clipping)
+
+There are **two** common offset bugs — do not confuse them:
+
+| Symptom | Cause | Fix |
+|--------|--------|-----|
+| Prototype preview pinned to top-left; empty space + clipping on right/bottom | Missing `h-full` fill chain inside `#prototype-viewport` | Use layout constants below on every nested wrapper |
+| Gallery / sidebar with black gaps + white bar at bottom of window | Site shell height mismatch (`h-full` parent + `h-svh` child, or body bg showing through) | Do **not** change gallery shell height classes ad hoc — parent route wrapper owns `h-svh`; `[data-prototype-root]` fills with `h-full flex-1` |
+
+The preview shell (`#prototype-viewport`) only auto-sizes **direct** children of `.viewportPage` (`width/height: 100%`, column flex). Every nested layer must repeat the fill chain or content shrinks to the top-left and clips on the opposite edge.
+
+**Use the exported constants** (do not hand-roll variants):
+
+```tsx
+import {
+  PROTOTYPE_PAGE_CLASS,
+  PROTOTYPE_SCROLL_CONTAINER_CLASS,
+  PROTOTYPE_VIEW_SHELL_CLASS,
+} from "prototype";
+```
+
+**Required page shell** (match `home-page` / `proto-partner-page`):
+
+```tsx
+<PrototypeComponent
+  id="scroll-container"
+  className={cn(PROTOTYPE_SCROLL_CONTAINER_CLASS, "…")}
+>
+  <PrototypeComponent id="page" className={cn(PROTOTYPE_PAGE_CLASS, "…")}>
+```
+
+**Every step/view root** (including `AnimatePresence` / motion wrappers):
+
+```tsx
+className={cn(PROTOTYPE_VIEW_SHELL_CLASS, "…")}
+```
+
+Put `overflow-y-auto` on the **view** that scrolls, not on `scroll-container`, unless the entire page is one scroll surface.
+
+**Centered embed/card layouts** (public booking pages): outer view = `w-full flex-1`; inner content = `mx-auto w-full max-w-*`. Use top padding (`py-10`) for embed pages — avoid `justify-center` on a `flex-1` wrapper when content can exceed viewport height (mobile stack); it vertically centers overflow and hides content off-screen.
+
+**Motion:** Prefer opacity-only cross-fades on page-level wrappers. Avoid horizontal `translateX` on wrappers that lack explicit `w-full` — `#prototype-viewport` uses `transform: translateZ(0)`, and transform + shrink-wrapped children produces the common top-left / clipped-right offset bug.
+
+**Post-build layout check (mandatory before finishing):**
+
+1. Open `/` — sidebar flush to content, no black gutter, no white strip at bottom of window.
+2. Open the prototype at desktop width — main surface fills the preview frame, not hugging a corner.
+3. Toggle mobile preview — tall stacked pages still scroll; nothing hidden off-screen from `justify-center`.
+
 ### Examples
 
 ```tsx
@@ -106,14 +196,27 @@ export function SettingsSection(props: SettingsSectionProps) {
 ```
 
 ```tsx
-import { PrototypeControl } from "prototype";
-
-export function PrototypePreviewStateSelect(...) {
-  return (
-    <PrototypeControl id="prototype-preview-state-select" className="flex items-center gap-2">
-      ...
-    </PrototypeControl>
-  );
+import { ControlsPanelSelect } from "@prototype/components/platform-ui/controls-panel-select";
+import { usePrototypeReviewOptional } from "@prototype/lib/prototypes/prototype-review-context";
+import { useLayoutEffect } from "react";
+
+export function PrototypePreviewStateSelect({ stateId, onStateChange, options }) {
+  const setTweaksContent = usePrototypeReviewOptional()?.setTweaksContent;
+
+  useLayoutEffect(() => {
+    if (!setTweaksContent) return;
+    setTweaksContent(
+      <ControlsPanelSelect
+        appearance="menuList"
+        value={stateId}
+        onValueChange={onStateChange}
+        options={options}
+      />,
+    );
+    return () => setTweaksContent(null);
+  }, [onStateChange, options, setTweaksContent, stateId]);
+
+  return null;
 }
 ```
 
@@ -124,15 +227,115 @@ export function PrototypePreviewStateSelect(...) {
 3. Add `component-ids.ts` — exhaustive static id list + `dynamicPrefixes`.
 4. Register in `prototype.config.ts` with `componentRegistry`.
 5. Wrap every UI component in `PrototypeComponent` / `PrototypeControl`.
-6. Call `usePrototypeComments(liveState, onRestore)` on the page.
-7. Run `pnpm verify:prototype-ids`.
-8. Capture screenshot; share via `pnpm share-prototype <slug>`.
+6. Define **`liveState`** and wire `usePrototypeComments(liveState, onRestore)` — see **Live state & preview states**.
+7. **Enumerate preview modes** from the brief and source (tabs, empty/loading/error, filters, modals, view toggles, wizard steps) and add the full preview-state stack in the **same change** as the UI:
+   - `*-preview-states.ts` (`definePreviewStateRegistry`, `createLiveStateForPreview`)
+   - `*-preview-state-select.tsx` (`ControlsPanelSelect` with `appearance="menuList"` via `setTweaksContent` — not a floating pill on the page)
+   - `*-state-canvas-config.tsx`
+   - `state-map-page.tsx` + `stateMapComponent` in `prototype.config.ts`
+   - `review.setStateCanvasConfig(...)` in `index.tsx`
+8. Run `pnpm verify:prototype-ids` and `pnpm verify:prototype-preview-states`.
+9. Capture screenshot; share via `pnpm share-prototype <slug>`.
+
+---
+
+## Live state & preview states (mandatory)
+
+Prototype state is a first-class tool feature — comments, share links, the review **State** map, and PR split cards all read from the same snapshot. **Do not invent parallel state systems.** Use the plugin's live-state + preview-state registry pattern on every prototype that has reviewable UI modes.
+
+### Do this proactively
+
+When **building or modifying** a prototype, treat preview states as part of the feature — not a follow-up:
+
+1. **Read existing state first** — `index.tsx`, any `*-preview-states.ts`, design-exploration configs, and `pr-split-config.ts` before changing UI.
+2. **Define a typed `TLiveState`** — one JSON-serializable object holding every field a reviewer needs to reproduce the view (step/screen, modal open, form values, toggles, selected tab, etc.).
+3. **One `liveState` on the page** — `useState<TLiveState>(createDefaultLiveState)` (or hydrate from `readPersistedPrototypeLiveState`). Derive rendered UI from `liveState`; route interactions through setters that update it.
+4. **Wire comments** — `usePrototypeComments(liveState, onRestore)` where `onRestore` calls `setLiveState(restored)`. This powers annotation restore and `shareState` links. Do **not** roll custom `?step=` / `?view=` query params.
+5. **Preview states are part of the feature, not a follow-up** — for feature pages, add or update a single `definePreviewStateRegistry` in `*-preview-states.ts` (see below). Every distinct tab, empty/loading/error branch, filter mode, modal, view toggle, or wizard step reviewers should jump to gets a registry entry **in the same change** as the UI. Only skip the registry for truly static single-view pages with no reviewable modes.
+6. **Wire the state picker into the review toolbar** — `*-preview-state-select.tsx` calls `review.setTweaksContent(...)` with `ControlsPanelSelect` using `appearance="menuList"` and `pickerOptions` from the registry. Do **not** render a floating `miniPill` select on the prototype surface (see `booking-flow-preview-state-select.tsx`).
+7. **Wire the state map** — `*-state-canvas-config.tsx` builds `PrototypeStateCanvasConfig` from the same registry. In `index.tsx`, call `review.setStateCanvasConfig(...)` in an effect; depend on stable review callbacks, not the whole `review` object. Add a `stateMapComponent` on the prototype in `prototype.config.ts` (see `booking-flow/state-map-page.tsx`) so `/prototypes/<slug>/states` renders the map instead of the default empty page.
+8. **Verify** — run `pnpm verify:prototype-preview-states` whenever a `*-preview-states.ts` file exists.
+
+Optional: `usePersistPrototypeLiveState(slug, liveState)` keeps reviewer position across reloads.
+
+### Architecture
+
+
+| Piece | Location | Purpose |
+| ----- | -------- | ------- |
+| `TLiveState` + `liveState` | page `index.tsx` | Single snapshot of all preview-relevant UI |
+| `usePrototypeComments` | page | Freeze/restore `liveState` for comments & share links |
+| `*-preview-states.ts` | `_components/` | `definePreviewStateRegistry` — picker, map nodes, `edges`, sections |
+| `*-preview-state-select.tsx` | `_components/` | On-page / sidebar step picker (`PrototypeControl`) |
+| `*-state-canvas-config.tsx` | `_components/` | Wireframes + registry data for the review **State** panel |
+
+
+Reference: `src/prototypes/booking-flow/` (`index.tsx`, `booking-flow-preview-states.ts`, `booking-flow-preview-state-select.tsx`, `booking-flow-state-canvas-config.tsx`).
+
+### Page wiring (minimal)
+
+```tsx
+const [liveState, setLiveState] = useState<TLiveState>(createDefaultLiveState);
+
+const onRestore = useCallback((restored: TLiveState) => {
+  setLiveState(restored);
+}, []);
+
+usePrototypeComments(liveState, onRestore);
+
+const setStateCanvasConfig = review?.setStateCanvasConfig;
+useEffect(() => {
+  if (!setStateCanvasConfig) return;
+  setStateCanvasConfig(
+    buildMyStateCanvasConfig(setStep),
+  );
+  return () => setStateCanvasConfig(null);
+}, [setStateCanvasConfig, setStep]);
+```
+
+### When to add a preview-state registry entry
+
+Add (or update) a registry state when you introduce:
+
+- A new screen, step, wizard stage, or primary tab reviewers should open directly
+- A modal, drawer, or overlay branch worth reviewing on its own
+- Empty, loading, or error branches that are distinct preview modes
+
+Skip registry entries for hover, focus, or other non-shareable micro-interactions.
+
+### Simple prototypes without steps
+
+If there are no navigable preview modes, `liveState` may be `{}` or hold only a few toggles — still call `usePrototypeComments`. Design explorations register separately via variant sets; do not fold exploration variants into ad-hoc `useState` without also exposing them through the exploration config.
+
+Multi-route prototypes (e.g. `proto-partner-page`) may use Next routes for real page boundaries; in-prototype step/modal switching within a page still belongs in `liveState`.
+
+### Anti-patterns
+
+- Multiple independent `useState` hooks for step/modal/view **without** aggregating into `liveState`
+- Custom URL query params for preview mode — share links use `usePrototypeComments` + encoded `shareState`
+- Hand-rolled `<select>` / tabs for preview modes outside `ControlsPanelSelect` + the registry
+- Floating `ControlsPanelSelect` with `appearance="miniPill"` on the prototype surface — states belong in the review toolbar **States** menu via `appearance="menuList"` and `setTweaksContent`
+- Duplicating picker labels or state ids outside `definePreviewStateRegistry`
+- Adding UI steps or modal branches **without** updating the registry, picker, and state map in the same change
+- Separate state maps or pickers that are not imported from the single `*-preview-states.ts` file
+- Passing `liveState` or the current preview mode into the state map config — the map is a **stateless** navigation surface, not a mirror of the active state
+- Tracking `activeStateId` / selected styling / checkmarks on state map nodes
 
 ---
 
 ## Preview states & state map
 
-Prototypes with preview modes use `definePreviewStateRegistry` in `*-preview-states.ts`. One registry drives the state picker, map nodes, `edges`, and sections.
+Prototypes with preview modes use `definePreviewStateRegistry` in `*-preview-states.ts`. One registry drives the state picker, map nodes, `edges`, and sections. The picker, canvas config, and verification script must all import from this file — never maintain parallel state lists.
+
+### State map behavior (mandatory)
+
+The state map is a **stateless picker** — it must **not** reflect, highlight, or mark the current preview state.
+
+- **No active-state association** — Do not pass the current preview mode, `liveState`, or any `activeStateId` into `PrototypeStateCanvasConfig` or `build…StateCanvasConfig`. Clicking a node navigates to that state; there is no checkmark, selected border, or `aria-current` on the map.
+- **Follows tool theme** — The state map canvas (background, chrome, edges, section labels, node cards) uses `--tool-chrome-*` tokens and matches the gallery/review light/dark mode toggle.
+- **`build…StateCanvasConfig(onStateSelect)`** — The builder takes only the select handler. Wire it once in `index.tsx` and `state-map-page.tsx`; do not re-build when `liveState` changes.
+
+Reference: `src/prototypes/booking-flow/_components/booking-flow-state-canvas-config.tsx`, `state-map-page.tsx`.
 
 ### State map layout
 
@@ -142,7 +345,7 @@ When two states are connected by an `edges` entry, arrange `canvasLayout.rows` s
 
 Prefer adjacent columns on the same row, or use `{ id, column }` / `startColumn` to offset nodes so vertical edges do not cut through unrelated cards in the same column.
 
-Reference: `src/prototypes/example-feature/_components/list-preview-states.ts`.
+Reference: `src/prototypes/booking-flow/_components/booking-flow-preview-states.ts`.
 
 ---
 
@@ -153,11 +356,33 @@ Use when comparing **2+ UI directions** for the same user problem.
 
 | Layer         | Location                                               | Owns                                                                                         |
 | ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-| **Tool**      | `prototype` (`PrototypeVariantExplorer`, etc.) | Modal chrome, variant tabs, rationale popover, Mobbin gallery, localStorage for brief fields |
-| **Prototype** | `src/prototypes/<slug>/_components/`                   | Variant renderers, copy, rationale, context JSON, Mobbin references, `component-ids.ts`      |
+| **Tool**      | `prototype` (`PrototypeVariantExplorer`, etc.) | Modal chrome, variant tabs, Mobbin gallery, localStorage for brief fields |
+| **Prototype** | `src/prototypes/<slug>/_components/`                   | Variant renderers, context JSON, Mobbin references, `component-ids.ts`      |
+
 
+Reference: `src/prototypes/proto-partner-page/_components/invite-copy-design-exploration-config.tsx` + `invite-copy-variant-toggle.tsx`.
 
-Reference: `example-feature/_components/no-data-design-exploration-config.tsx` + `no-data-variant-toggle.tsx`.
+### Renderers
+
+Build one preview per option with `buildDesignExplorationRenderers`. In host prototype files (client components), import from `@prototype/...` — not the `proto-plugin` barrel, which includes server-only modules:
+
+```ts
+import { buildDesignExplorationRenderers } from "@prototype/lib/prototypes/build-design-exploration-renderers";
+import { DesignExplorationVariantPreviewShell } from "@prototype/components/prototypes/design-exploration-variant-preview-shell";
+
+const renderers = buildDesignExplorationRenderers(VARIANT_OPTIONS, (variant) => (
+  <MyBlock variant={variant} />
+), BASELINE);
+
+// Overlay-style variants (absolute positioning on the live page):
+const renderers = buildDesignExplorationRenderers(VARIANT_OPTIONS, (variant) => (
+  <DesignExplorationVariantPreviewShell layout={isOverlay(variant) ? "overlay" : "inline"}>
+    <MyBlock variant={variant} />
+  </DesignExplorationVariantPreviewShell>
+), BASELINE);
+```
+
+Do not hand-roll renderer maps that return `null` for some variants — the helper maps every option and warns in dev when a renderer returns empty content.
 
 ### Config shape
 
@@ -167,22 +392,42 @@ Reference: `example-feature/_components/no-data-design-exploration-config.tsx` +
   variantTabsIdPrefix: string;
   storageKeyPrefix: string;
   variant, onVariantChange,
-  options: { value, label, hint? }[];
-  rationale: Record<TVariant, { good, bad }>;
+  options: { value, label, hint? }[]; // exploration directions — newest first; exclude baseline when possible
   renderers: Record<TVariant, ComponentType>;
   brief: { titleDefault, descriptionDefault };
+  baseline: { value, label?, hint? }; // pre-exploration UI — always pinned at the bottom of the variant list
+  defaultVariant?: TVariant; // codebase-stored default (e.g. DEFAULT_*_VARIANT); marked "Default" in the brief
   context?: { label, data: unknown, render?, defaultExpanded?, panelId? };
   mobbin?: { references, title?, description?, imagePathForReference? };
   variantsSection?: { title?, description? };
 }
 ```
 
+Every exploration **must** define `baseline` — the UI as it existed before the exploration was added. The design brief shows it last with an **Original** badge. Use `getDesignExplorationDisplayOptions(options, baseline)` for tabs and keyboard cycling; use `getDesignExplorationVariantOptions(options, baseline)` when listing directions in prompts.
+
+Build renderers with `buildDesignExplorationRenderers(options, renderVariant, baseline)` so the baseline preview is included.
+
+### Exploration icons
+
+The review sidebar explorations menu shows a Lucide icon per variant set via `VariantSetLucideIcon` (`packages/prototype/src/lib/prototypes/variant-set-lucide-icon.tsx`). Rules match on `id` + `label` (first fit wins); unmatched sets fall back to `LayoutGrid`.
+
+When adding a new exploration, **assign it a distinct icon**:
+
+1. Pick a Lucide icon that reflects the exploration topic (not `LayoutGrid` unless nothing else fits).
+2. Add a `{ test: /…/, icon: … }` entry to `VARIANT_SET_ICON_RULES`, placed **above** broad rules such as `/mobile/i`, so this exploration wins over generic matchers.
+3. Do not reuse icons already assigned to other explorations on the same prototype.
+4. Import the chosen icon from `lucide-react`.
+
+The default variant lives in the codebase config (`defaultVariant`, typically `DEFAULT_*_VARIANT`) — not KV. In the brief, each non-default option shows a **Make default** button that copies a prompt (`buildSetDefaultVariantPrompt`) asking an agent to update that constant; the current default is marked **Default**.
+
 ### Iterating on variants
 
 When asked to **modify an existing option**, add a **new variant** (do not replace in place), register ids, and update `DEFAULT_*_VARIANT`.
 
 **Variant list order:** prepend each new entry to the top of `*_VARIANT_OPTIONS` (first item in the array). That order drives the design-brief sidebar/modal scroll view and variant tabs — newest explorations appear at the top.
 
+In review mode, each exploration sidebar includes a brief field and **Copy prompt** button below the header. It copies `buildMoreDesignExplorationVariantsCopyText` with the typed brief, existing variants, and config path — use that to request more layout directions from an agent.
+
 
 | Prompt intent         | Action                                          |
 | --------------------- | ----------------------------------------------- |
@@ -203,7 +448,7 @@ Use when a prototype ships as a **sequence of small source PRs** rather than one
 | **Prototype** | `src/prototypes/<slug>/_components/` | `PR_SPLIT_ENTRIES` data, `PR_SPLIT_CONFIG`, wireframe renderers, live-state URL wiring                                                           |
 
 
-Reference: `example-feature/_components/pr-split-config.ts` + `pr-split-wireframes.tsx`.
+Reference: `booking-flow/_components/pr-split-config.ts` + `pr-split-wireframes.tsx` (when present) or any prototype with a spec panel.
 
 ### Host setup
 
@@ -279,15 +524,16 @@ export const PR_SPLIT_ENTRIES: MyPrSplitEntry[] = [
 
 ### Wireframes (`pr-split-wireframes.tsx`)
 
-Prototype-specific schematic thumbnails for each `wireframeId`. Pattern:
+Prototype-specific **full-page** schematic previews for each `wireframeId`. Each card must show the complete page shell (sidebar, header/toolbar, main content) — not a cropped excerpt or zoomed-in slice of the PR target. Pattern:
 
-1. Define a `PageShell` (or layout scaffold) matching the prototype page structure.
-2. Use low-fidelity `Wire` blocks — neutral grays for chrome, **highlighted** regions for the PR target.
+1. Define a `PageShell` (or layout scaffold) matching the prototype's real page structure — every zone reviewers see in the live preview.
+2. Use low-fidelity `Wire` blocks — neutral grays for chrome, **highlighted** regions for the PR target only.
 3. Import highlight tokens from the tool: `PR_TARGET_HIGHLIGHT_BORDER`, `PR_TARGET_HIGHLIGHT_FILL`.
-4. Register one renderer per `wireframeId` in a `Record<WireframeId, () => ReactNode>`.
-5. Export `PrSplitWireframe` wrapped in `PrototypeComponent` (register id in `component-ids.ts`).
+4. Fill the card preview: wrap the wireframe root in `PR_SPLIT_WIREFRAME_FRAME_CLASS` from `prototype` (`aspect-video w-full overflow-hidden`) so the schematic reads as a full screen, not a short strip.
+5. Register one renderer per `wireframeId` in a `Record<WireframeId, () => ReactNode>`.
+6. Export `PrSplitWireframe` wrapped in `PrototypeComponent` (register id in `component-ids.ts`).
 
-Highlighted areas must match what `targetId` points to on the real prototype.
+Highlighted areas must match what `targetId` points to on the real prototype; surrounding chrome provides context for where the change sits on the page.
 
 ### Page wiring (`index.tsx`)
 
@@ -326,6 +572,34 @@ setSpecContent(
 
 ---
 
+## Consuming the review context in effects
+
+`usePrototypeReview()` / `usePrototypeReviewOptional()` return a **new context object on most renders** — the provider's `value` memo rebuilds whenever review state changes (e.g. `variantSets`, panel open state). Several of its methods (`registerVariantSet`, `unregisterVariantSet`, etc.) also call `setState`.
+
+**Never put the whole `review` object in an effect dependency array.** Doing so creates an infinite loop ("Maximum update depth exceeded"): the effect calls a method → state changes → `value` gets a new identity → the effect re-runs → its cleanup undoes the work → the body redoes it → repeat.
+
+Depend on the **specific stable callbacks** instead. The context methods are wrapped in `useCallback(..., [])`, so their identities are stable across renders.
+
+```tsx
+// ❌ loops forever — `review` identity changes whenever it registers/unregisters
+useLayoutEffect(() => {
+  if (!review) return;
+  review.registerVariantSet(set);
+  return () => review.unregisterVariantSet(set.id);
+}, [review]);
+
+// ✅ stable deps — runs once, cleans up once
+const registerVariantSet = review?.registerVariantSet;
+const unregisterVariantSet = review?.unregisterVariantSet;
+useLayoutEffect(() => {
+  if (!registerVariantSet || !unregisterVariantSet) return;
+  registerVariantSet(set);
+  return () => unregisterVariantSet(set.id);
+}, [registerVariantSet, unregisterVariantSet]);
+```
+
+---
+
 ## Comment system
 
 - Storage: Upstash Redis key `prototype-comments:<slug>`
@@ -347,4 +621,9 @@ Before finishing, confirm side-by-side with source or a screenshot:
 - Importing from `source/` at runtime
 - Reimplementing synced `@/components/ui` primitives
 - Approximating layout dimensions or colors
+- **Inventing custom prototype state** instead of `liveState` + `definePreviewStateRegistry` (see **Live state & preview states**)
+- **Adding screens/modals without registering preview states** in the same change
+- Depending on the whole `review` context object in an effect's deps (see "Consuming the review context in effects") — use the specific stable callbacks instead
+- **`scroll-container` with `overflow-y-auto` and no `h-full` fill chain** — causes top-left offset and clipped content in the preview frame (see **Prototype viewport fill**)
+- **Page-level motion with `translateX` on wrappers missing `w-full flex-1`** — same offset bug; use opacity-only or fill classes first
 

package/README.md

@@ -64,14 +64,32 @@ import { withPrototype } from "./packages/prototype/src/config/with-prototype";
 export default withPrototype({ nextConfig: { /* … */ } });
 ```
 
-5. **Tailwind** — scan prototype package components from the host `globals.css`:
+5. **Tailwind** — scan prototype package components from the host `globals.css`. Register semantic `--color-*` tokens as self-referential vars so utilities like `text-muted-foreground` resolve from `[data-prototype-root]` at runtime — **do not** map `--color-foreground` / `--color-background` to product `:root` tokens (that breaks gallery contrast):
 
 ```css
 @import "tailwindcss";
 @source "../../packages/prototype/src/**/*.{js,ts,jsx,tsx}";
+
+@theme inline {
+  --color-foreground: var(--color-foreground);
+  --color-muted-foreground: var(--color-muted-foreground);
+  /* …other semantic colors used by proto-plugin */
+}
+```
+
+Product tokens use separate names (e.g. `--product-background`) scoped to `[data-prototype-screenshot]`.
+
+6. **Root layout + tool themes** — wrap routes with `createPrototypeSiteLayout()` and import package chrome CSS (dark/light themes live here, not in host `globals.css`):
+
+```tsx
+import { createPrototypeSiteLayout } from "proto-plugin";
+import "proto-plugin/styles/globals.css";
+import "./globals.css";
+
+const PrototypeSiteLayout = createPrototypeSiteLayout();
 ```
 
-6. **tsconfig paths** (optional, for tool internal `@prototype/*` alias when developing the package):
+7. **tsconfig paths** (optional, for tool internal `@prototype/*` alias when developing the package):
 
 ```json
 {
@@ -84,6 +102,18 @@ export default withPrototype({ nextConfig: { /* … */ } });
 }
 ```
 
+8. **Dev server port** — run the host on port **1985** so it stays separate from a typical source app on 3000. In the host `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev -p 1985"
+  }
+}
+```
+
+Open [http://localhost:1985](http://localhost:1985) when developing.
+
 ## Public API
 
 | Export | Use |
@@ -116,6 +146,8 @@ The `prototype` package uses the **host design system** — same tokens and Tail
 
 Host `globals.css` must `@source` prototype package TSX for Tailwind utilities.
 
+**Do not** implement gallery/review dark or light mode in host `globals.css`. Import `proto-plugin/styles/globals.css` in `layout.tsx` — the package defines both themes on `[data-prototype-root]` (default dark; `data-prototype-comment-theme="light"` for light). Host `globals.css` is for **product** tokens synced from the source app (prototype preview content only).
+
 ## Publish
 
 From `packages/prototype/`:
@@ -190,21 +222,21 @@ pnpm download-mobbin-references -- --ids=uuid1,uuid2
 
 ## Starter prompt (for AI agents)
 
-Copy the block below into a new agent chat to scaffold a host app from scratch. The agent should ask you for a few values up front, then handle the rest (including inferring what to sync from source).
+Copy the block below into a new agent chat to scaffold a host app from scratch. The agent should ask you for a few values up front — **one question at a time** — then handle the rest (including inferring what to sync from source).
 
 ````markdown
 Set up a new Next.js host app for `proto-plugin` — a framework for shareable UI prototypes.
 
 ## Before you start — ask me for these
 
-Do not scaffold or run commands until I answer. Ask in one message:
+Do not scaffold or run commands until I answer all four questions. Ask **one question at a time** — wait for my reply before asking the next:
 
-1. **Host app name** — directory name for the new Next.js project.
-2. **Where to create it** — parent directory (absolute path), or confirm the current workspace.
-3. **Source app path** — absolute path to the real product repo whose UI we will prototype (used for `source/` symlink and sync).
-4. **Optional env** — whether I want comment/screenshot persistence configured now (`KV_REST_API_URL`, `KV_REST_API_TOKEN`, `BLOB_READ_WRITE_TOKEN`) or to skip for later.
+1. **Host app name** — What should the new Next.js project directory be called? (e.g. `my-product-prototypes`)
+2. **Where to create it** — Parent directory as an absolute path (e.g. `/Users/maayanalbert/Projects`), or confirm you want it in the current workspace.
+3. **Source app path** — Absolute path to the real product repo whose UI we'll prototype (used for the `source/` symlink and sync).
+4. **Optional env** — Should I configure comment/screenshot persistence now (`KV_REST_API_URL`, `KV_REST_API_TOKEN`, `BLOB_READ_WRITE_TOKEN`), or skip that for later?
 
-Wait for my answers, then do all setup yourself.
+After I answer all four, do all setup yourself.
 
 ## 1. Scaffold the app
 
@@ -229,19 +261,29 @@ Follow the package README (`node_modules/proto-plugin/README.md`) and implement
 1. **`prototype.config.ts`** at the repo root — start with an empty `prototypes: []` array using `definePrototypeConfig` from `proto-plugin`.
 2. **Gallery home** — `src/app/page.tsx` via `createPrototypeGalleryPage(prototypeConfig)`.
 3. **Prototype route** — `src/app/prototypes/[slug]/page.tsx` via `createPrototypePage(prototypeConfig)` (export `default` + `generateStaticParams`).
-4. **Root layout** — wrap children with `createPrototypeSiteLayout()` from `proto-plugin` in `src/app/layout.tsx`.
+4. **Root layout** — wrap children with `createPrototypeSiteLayout()` from `proto-plugin` in `src/app/layout.tsx`, and import the tool chrome theme:
+
+   ```tsx
+   import { createPrototypeSiteLayout } from "proto-plugin";
+   import "proto-plugin/styles/globals.css";
+   import "./globals.css";
+   ```
 5. **API catch-all** — `src/app/api/[...path]/route.ts` using `createPrototypeApiRoute(prototypeConfig)` from `proto-plugin/server`; export `GET`, `POST`, and `PUT` handlers that call `dispatch`.
 6. **`next.config.ts`** — wrap with `withPrototype` from `proto-plugin/with-prototype` and ensure `proto-plugin` is transpiled.
-7. **`src/app/globals.css`** — keep Tailwind v4 setup and add:
+7. **`src/app/globals.css`** — Tailwind v4 + product tokens synced from source. **Do not** put tool chrome dark/light mode here (no `prefers-color-scheme`, no hardcoded gallery colors). Scan package components:
 
    ```css
+   @import "tailwindcss";
    @source "../../node_modules/proto-plugin/src/**/*.{js,ts,jsx,tsx}";
    ```
 
-8. **`package.json` scripts** — forward CLI commands to the installed package:
+   Tool themes live in `proto-plugin/styles/globals.css` (import in layout). The package toggles dark/light on `[data-prototype-root]` via `data-prototype-comment-theme`.
+
+8. **`package.json` scripts** — set dev to port 1985 and forward CLI commands to the installed package:
 
    ```json
    {
+     "dev": "next dev -p 1985",
      "link-source": "pnpm --dir node_modules/proto-plugin link-source",
      "sync-from-source": "pnpm --dir node_modules/proto-plugin sync-from-source",
      "link-source-db": "pnpm --dir node_modules/proto-plugin link-source-db",
@@ -252,7 +294,7 @@ Follow the package README (`node_modules/proto-plugin/README.md`) and implement
 
 9. **`.env.example` and `.env.local`** — document and set `SOURCE_PATH` to the source app path I provided. Add comment/screenshot storage vars only if I asked for them in step 5 — the app should run without them, but comments won't persist.
 
-Run `pnpm dev` and confirm `/` shows the empty gallery and the app builds cleanly before continuing.
+Run `pnpm dev` and confirm [http://localhost:1985](http://localhost:1985) shows the empty gallery and the app builds cleanly before continuing.
 
 ## 3. Link the source app
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proto-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/scripts/lib/host-config.example.sh

@@ -33,7 +33,7 @@ SYNC_GLOBS=(
 # the source version, which the blanket copy overwrites and you must re-apply.
 # Leave empty if the host does not diverge from source.
 SYNC_LOCAL_EXTENSIONS=(
-  # "my-component (local variant + semantic token classes)"
+  # "src/app/globals.css (keep @source line; tool theme lives in layout via proto-plugin/styles/globals.css)"
 )
 
 # --- pnpm link-source-db ---------------------------------------------------