@marver-design/marver 0.2.0 → 0.2.2

package/src/client/frame-host/bridge.js

@@ -4,9 +4,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
+// theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
+const setTheme = (theme) => {
+  document.documentElement.dataset.theme = theme
+  document.documentElement.classList.toggle('dark', theme === 'dark')
+}
+
 if (isHtmlFrame) {
   const theme = new URLSearchParams(location.search).get('theme')
-  if (theme) document.documentElement.dataset.theme = theme
+  if (theme) setTheme(theme)
 }
 
 document.addEventListener('click', (e) => {
@@ -23,7 +29,7 @@ window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: St
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}` }))
 
 window.addEventListener('message', (e) => {
-  if (e?.data?.type === 'sh:set-theme') document.documentElement.dataset.theme = e.data.theme
+  if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
 })
 
 if (isHtmlFrame) {

package/src/client/frame-host/main.tsx

@@ -12,7 +12,11 @@ import { frameFile, frames, layoutChain, layouts, providers } from './registry.t
 const params = new URLSearchParams(location.search)
 const id = params.get('id') ?? ''
 const theme = params.get('theme') ?? 'light'
+// Both signals, always: [data-theme] for token systems keyed on the attribute, and the
+// `dark` class for Tailwind/shadcn (`@custom-variant dark (&:is(.dark *))` never sees a
+// data attribute). The bridge applies the same pair on sh:set-theme.
 document.documentElement.dataset.theme = theme
+document.documentElement.classList.toggle('dark', theme === 'dark')
 
 const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 
@@ -47,7 +51,9 @@ async function boot() {
     await import('virtual:sh-theme' as string)
 
     const fileKey = frameFile(id)
-    if (!fileKey) return fail(`unknown frame id "${id}"`)
+    // Honest copy: the id usually IS valid on disk - this document's frame registry is
+    // what's stale (file just added/renamed, or the dev server restarted). See #20.
+    if (!fileKey) return fail(`frame "${id}" is not in this canvas's registry yet - the file was likely just added or renamed. The canvas should recover on its own; if this card persists, reload it.`)
 
     const frameMod: any = await frames[fileKey]()
     const Frame = frameMod.default

package/src/client/shell/App.tsx

@@ -1,12 +1,12 @@
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, boardLabel, cap, fetchBoardNames } from './store.ts'
+import { useStore, CONFIG, PUBLISHED, boardLabel, cap, fetchBoardNames } from './store.ts'
 import { Tip } from './Tip.tsx'
-import { ROUTE } from '../const.ts'
+import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
-import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, deviceIcon } from './icons.tsx'
+import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, XIcon, deviceIcon } from './icons.tsx'
 
 let booted = false                             // survives Fast Refresh; see the boot effect
 
@@ -115,6 +115,18 @@ function SelectionBar() {
   const node = useStore((s) => s.nodes.find((n) => n.key === s.selection[s.selection.length - 1]))
   const frame = useStore((s) => (node ? s.frameFor(node) : undefined))
   const nodes = useStore((s) => s.nodes)
+  // measured width feeds the viewport clamp below; a callback ref because the bar
+  // mounts/unmounts with the selection (an effect with [] would miss remounts)
+  const [barW, setBarW] = useState(0)
+  const roRef = useRef<ResizeObserver | null>(null)
+  const barRef = (el: HTMLDivElement | null) => {
+    roRef.current?.disconnect()
+    roRef.current = null
+    if (el) {
+      roRef.current = new ResizeObserver(() => setBarW(el.offsetWidth))
+      roRef.current.observe(el)
+    }
+  }
   if (!node || !frame || node.missing) return null
   // anchor: centered over the bounding box of ALL selected frames, above the topmost
   const selNodes = nodes.filter((n) => selection.includes(n.key))
@@ -135,14 +147,21 @@ function SelectionBar() {
       .map((k) => { const n = st.nodes.find((x) => x.key === k); return n ? st.frameFor(n) : undefined })
       .filter((f): f is NonNullable<typeof f> => !!f)
   }
+  // centered over the selection's bounding box, then CLAMPED into the viewport: the
+  // controls for a selected frame must stay reachable when its top edge is panned
+  // off-screen, and must never drift off the sides (friction log #23)
+  const centerX = `calc(var(--sh-tx, 0px) + var(--sh-s, 1) * ${(bx0 + bx1) / 2}px)`
+  const rawTop = `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - 52px)`
   return (
     <div
       className="sh-ctx"
+      ref={barRef}
       style={{
-        // centered over the selection's bounding box; translateX keeps it centered at any width
-        left: `calc(var(--sh-tx, 0px) + var(--sh-s, 1) * ${(bx0 + bx1) / 2}px)`,
-        top: `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - 52px)`,
-        transform: 'translateX(-50%)',
+        left: barW
+          ? `clamp(8px, calc(${centerX} - ${Math.round(barW / 2)}px), calc(100vw - ${barW + 8}px))`
+          : centerX,
+        top: `clamp(8px, ${rawTop}, calc(100vh - 52px))`,
+        transform: barW ? undefined : 'translateX(-50%)',
       }}
     >
       {multi && <>
@@ -232,6 +251,45 @@ function DeviceMenu() {
   )
 }
 
+/** Update pill (dev only): the daily registry check surfaces here - same glass, same
+ *  pill, bottom-center. Click the command to copy it; × dismisses THIS version for
+ *  good (localStorage), so the pill returns only when the next release lands. */
+function UpdatePill() {
+  const [latest, setLatest] = useState<string | null>(null)
+  const play = useStore((s) => s.play)
+  useEffect(() => {
+    if (PUBLISHED) return                     // a shared canvas never nags its viewers
+    fetch(`${ROUTE}/api/update`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((u) => {
+        if (u?.latest && localStorage.getItem('mv-update-seen') !== u.latest) setLatest(u.latest)
+      })
+      .catch(() => { /* dev server gone or endpoint absent - stay quiet */ })
+  }, [])
+  if (!latest || play) return null
+  // init rides along so managed files (AGENTS.md, instructions/) refresh with the code
+  const cmd = `npm i -D ${PKG}@latest && npx marver init`
+  const dismiss = () => {
+    try { localStorage.setItem('mv-update-seen', latest) } catch { /* storage unavailable */ }
+    setLatest(null)
+  }
+  return (
+    <div className="sh-update">
+      <span><b>{latest}</b> is out</span>
+      <Tip side="top" label="Copy, then paste to your terminal or your agent">
+        <button className="cmd" onClick={() => {
+          const t = useStore.getState().toast
+          navigator.clipboard?.writeText(cmd).then(() => t('update command copied'), () => t('copy blocked - select it manually'))
+            ?? t('copy unavailable - select it manually')
+        }}><code>{cmd}</code></button>
+      </Tip>
+      <Tip side="top" label="Dismiss this version">
+        <button className="x" onClick={dismiss}><XIcon size={13} /></button>
+      </Tip>
+    </div>
+  )
+}
+
 const ZOOMS = [2, 1.5, 1, 0.5, 0.25, 0.1]
 
 /** Zoom preset dropdown on the percentage readout. */
@@ -623,7 +681,10 @@ export function App() {
 
       <PlayOverlay />
 
-      {CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled (design/config.ts → theme)</div>}
+      {CONFIG.setup
+        ? <div className="sh-banner">no app detected - designs would be built from nothing. See design/instructions/setup.md, then restart</div>
+        : CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set theme in design/config.ts)</div>}
+      <UpdatePill />
 
       <div className="sh-toasts">
         {toasts.map((t) => <div key={t.id} className="sh-toast"><CheckIcon size={12} /> {t.text}</div>)}

package/src/client/shell/canvas/FrameNode.tsx

@@ -47,6 +47,15 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     fileRef.current = sig
   }, [frame?.kind, frame?.file])
 
+  // shell-requested renavigation (store bumps node.nav): reload on a FRESH rev-stamped
+  // URL - the errored document's own URL may be poisoned by cache (friction log #20)
+  const navRef = useRef(node.nav ?? 0)
+  useEffect(() => {
+    if ((node.nav ?? 0) === navRef.current) return
+    navRef.current = node.nav ?? 0
+    if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
+  }, [node.nav])
+
   // ready timeout (spec §7): 10s without sh:ready -> error card with reload
   useEffect(() => {
     if (node.status !== 'loading') return

package/src/client/shell/store.ts

@@ -11,12 +11,18 @@ import shData from 'virtual:sh-data'
  *  is where `/` opens - never a synthesized aggregate of a filtered build. */
 const DATA: { manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string } | null = shData
 
+/** True on a published static canvas - no dev server, no API, no update checks. */
+export const PUBLISHED = DATA !== null
+
 export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
   /** RESOLVED theme (what renders): themeUser ?? frame meta.theme ?? viewTheme. */
   theme: string
+  /** Renavigation nonce: bumped when the shell wants this iframe on a FRESH URL
+   *  (errored frame whose file is back in the manifest). Never persisted. */
+  nav?: number
   /** Explicit per-frame override, set by scoped theme actions; cleared by a global set.
    *  The only theme value that persists into the board file. */
   themeUser?: string
@@ -24,7 +30,7 @@ export interface Node {
 }
 export interface Toast { id: number; text: string }
 
-export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean } = shConfig
+export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean } = shConfig
 
 export const cap = (s: string) => (s ? s[0].toUpperCase() + s.slice(1) : s)
 
@@ -42,10 +48,16 @@ const HEADER = 28
 let toastSeq = 0
 const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
 
+/** Manifest revision - bumps whenever a manifest lands (boot, switch, sh:manifest).
+ *  Stamped into frame URLs so a changed frame set mints genuinely NEW iframe URLs:
+ *  the browser can never revive a pre-change document from cache (friction log #20). */
+let manifestRev = 0
+export const bumpManifestRev = () => { manifestRev++ }
+
 export function frameUrl(frame: FrameEntry, theme: string): string {
   return frame.kind === 'html'
     ? `/${frame.file}?theme=${theme}`
-    : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}`
+    : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}&r=${manifestRev}`
 }
 
 /** The global view theme: the user's sticky preference, applied across boards and
@@ -148,6 +160,7 @@ export const useStore = create<State>((set, get) => {
         raw = await mRes.json().catch(() => undefined)
       }
       if (raw === undefined || raw === null || typeof raw !== 'object') return null
+      bumpManifestRev()                        // fresh manifest → fresh iframe URLs
       const manifest: Manifest = {
         frames: (Array.isArray(raw?.frames) ? raw.frames : [])
           .filter((f: any) => f && typeof f.id === 'string' && typeof f.file === 'string'),
@@ -164,9 +177,12 @@ export const useStore = create<State>((set, get) => {
       if (DATA) loaded = DATA.boards[boardName] ? { board: DATA.boards[boardName], sha256: 'published' } : 'fresh'
       else {
         const res = await fetch(`${ROUTE}/api/boards/${boardName}`)
-        if (res.ok) loaded = await res.json()
-        else if (res.status === 404) loaded = 'fresh'
-        else loaded = null                     // only 404 means "fresh board"; anything else must not commit an empty canvas
+        if (res.ok) {
+          const body = await res.json()
+          loaded = body?.board == null ? 'fresh' : body   // board:null = not materialized yet
+        }
+        else if (res.status === 404) loaded = 'fresh'    // older servers still 404 fresh boards
+        else loaded = null                     // anything else must not commit an empty canvas
       }
       if (loaded === null) return null
       if (loaded !== 'fresh') {
@@ -210,6 +226,16 @@ export const useStore = create<State>((set, get) => {
         if (typeof board?.deviceView === 'string' && CONFIG.viewports[board.deviceView]) deviceView = board.deviceView
         if (board?.baseLayout && typeof board.baseLayout === 'object') baseLayout = board.baseLayout
       }
+      // auto-managed goes both ways (friction log #15): an auto board gains new frames
+      // AND sheds deleted ones. Tombstone cards are a curated-board concept (spec §7).
+      // Pruning at load DIRTIES the board (dev only) so the file on disk sheds the
+      // tombstones too - otherwise a recreated frame id resurrects its stale node.
+      let prunedAtLoad = false
+      if (boardAuto) {
+        const before = nodes.length
+        nodes = nodes.filter((n) => !n.missing)
+        prunedAtLoad = !DATA && nodes.length !== before
+      }
       // frames not on the board yet → auto boards only (a curated board shows exactly its list)
       if (boardAuto) {
         const placed = new Set(nodes.map((n) => n.frame))
@@ -234,8 +260,9 @@ export const useStore = create<State>((set, get) => {
         const placedAll = tidy(nodes.map((n) => ({ key: n.key, scene: sceneOf(n.frame), w: n.w, h: n.h + HEADER })))
         for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
       }
-      // dirty: false - the committed state matches disk by construction
-      return { manifest, nodes, boardHash, boardAuto, deviceView, baseLayout, selection: [], dirty: false }
+      // dirty matches disk by construction - except when load-time pruning changed the
+      // node set; callers see dirty:true and schedule the save that persists the prune
+      return { manifest, nodes, boardHash, boardAuto, deviceView, baseLayout, selection: [], dirty: prunedAtLoad }
     } catch { return null }
   }
 
@@ -255,6 +282,7 @@ export const useStore = create<State>((set, get) => {
       if (get().board !== boardName || editRev !== revAtStart) return false
       const live = get().manifest             // a WS manifest update may have landed mid-fetch
       set(next)
+      if (next.dirty) scheduleSave()          // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
       return true
     },
@@ -280,10 +308,12 @@ export const useStore = create<State>((set, get) => {
       ++loadSeq                                // invalidate any in-flight boot of the old board
       const live = get().manifest              // a WS manifest update may have landed mid-load
       set({ board: name, interact: null, ...next })
+      if (next.dirty) scheduleSave()           // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
     },
 
     applyManifest(m) {
+      bumpManifestRev()                        // frame set changed → new iframes get fresh URLs
       const { nodes, toast, boardAuto } = get()
       const known = new Set(nodes.map((n) => n.frame))
       const next = [...nodes]
@@ -313,8 +343,28 @@ export const useStore = create<State>((set, get) => {
         const f = m.frames.find((x) => x.id === n.frame)
         const want = n.themeUser ?? f?.theme ?? get().viewTheme
         if (n.theme !== want) { n.theme = want; retinted = true }
+        // an errored frame whose file IS in the fresh manifest gets one automatic retry
+        // on a rev-stamped URL - the "unknown frame id" dead end must self-heal (#20)
+        if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; retinted = true }
       }
-      set({ manifest: m, nodes: changed || retinted ? [...next] : next, ...(changed ? { dirty: true, baseLayout: nextBase } : {}) })
+      // auto boards prune deleted frames outright - "auto-managed" must manage both
+      // directions (friction log #15). Curated boards keep the explicit card (spec §7).
+      let final = next
+      if (boardAuto) {
+        final = next.filter((n) => !n.missing)
+        const dropped = next.length - final.length
+        if (dropped) {
+          changed = true
+          toast(dropped === 1 ? 'removed 1 deleted frame' : `removed ${dropped} deleted frames`)
+        }
+      }
+      set((s) => ({
+        manifest: m,
+        nodes: changed || retinted ? [...final] : final,
+        selection: s.selection.filter((k) => final.some((n) => n.key === k)),
+        interact: s.interact && final.some((n) => n.key === s.interact) ? s.interact : null,
+        ...(changed ? { dirty: true, baseLayout: nextBase } : {}),
+      }))
       if (changed) scheduleSave()
     },
 

package/src/client/shell/styles.css

@@ -194,7 +194,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-handle.se { right: -5px; bottom: -5px; width: 11px; height: 11px; cursor: nwse-resize }
 
 /* glass surfaces share one recipe; chrome text is never selectable (shift-click = multi-select) */
-.sh-ctx, .sh-panel, .sh-fab, .sh-pill, .sh-pill-fab, .sh-menu, .sh-banner, .sh-toast {
+.sh-ctx, .sh-panel, .sh-fab, .sh-pill, .sh-pill-fab, .sh-menu, .sh-banner, .sh-toast, .sh-update {
   background: var(--glass); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur);
   border: 1px solid var(--glass-brd); box-shadow: var(--shadow-glass); position: relative;
   user-select: none; -webkit-user-select: none }
@@ -202,7 +202,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* edge light: a 1px gradient ring over the border, so glass reads as glass even
    with nothing behind it to blur (masked-border technique) */
 .sh-ctx::after, .sh-panel::after, .sh-fab::after, .sh-pill::after, .sh-pill-fab::after,
-.sh-menu::after, .sh-banner::after, .sh-toast::after, .sh-node::after {
+.sh-menu::after, .sh-banner::after, .sh-toast::after, .sh-update::after, .sh-node::after {
   content: ''; position: absolute; inset: -1px; padding: 1px; border-radius: inherit;
   background: var(--edge-light); pointer-events: none;
   -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
@@ -404,6 +404,25 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-banner { position: absolute; bottom: var(--edge); right: var(--edge); z-index: 10; font: 500 12px -apple-system, system-ui, sans-serif;
   color: var(--glass-warn); border-radius: 999px; padding: 8px 14px }
 
+/* update pill: bottom-center, the quietest possible member of the pill family.
+   The command IS the button - one click copies it for the terminal or the agent. */
+.sh-update { position: absolute; left: 50%; bottom: var(--edge); transform: translateX(-50%); z-index: 10;
+  display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 7px 0 16px; border-radius: 999px;
+  max-width: min(92vw, 620px); white-space: nowrap;
+  font: 500 12.5px -apple-system, system-ui, sans-serif; color: var(--glass-ink-2);
+  animation: sh-update-in .35s cubic-bezier(.2, .9, .3, 1.2) }
+@keyframes sh-update-in { from { opacity: 0; transform: translate(-50%, 8px) scale(.96) } }
+.sh-update b { font-weight: 650; color: var(--glass-ink) }
+.sh-update .cmd { border: 1px solid var(--glass-brd); background: var(--glass-hover); border-radius: 999px;
+  padding: 4px 11px; cursor: pointer; min-width: 0; overflow: hidden; transition: color .15s }
+.sh-update .cmd code { font: 500 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--glass-ink-2);
+  display: block; overflow: hidden; text-overflow: ellipsis }
+.sh-update .cmd:hover code { color: var(--glass-ink) }
+.sh-update .x { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px;
+  border: 0; background: none; border-radius: 999px; color: var(--glass-ink-3); cursor: pointer;
+  transition: color .15s, background .15s }
+.sh-update .x:hover { background: var(--glass-hover); color: var(--glass-ink) }
+
 .sh-toasts { position: absolute; left: var(--edge); bottom: var(--edge); z-index: 12; display: flex; flex-direction: column; gap: 6px }
 .sh-toast { display: flex; align-items: center; gap: 6px; font: 500 12px -apple-system, system-ui, sans-serif;
   color: var(--glass-ink-2); border-radius: 999px; padding: 7px 13px }

package/templates/AGENTS-embedded.md

@@ -3,6 +3,29 @@
 You design by writing files. The canvas at the printed localhost URL reflects them live.
 Never run or talk to the canvas tool; read and write files only.
 
+## The method (binding)
+
+Design work moves through phases. BEFORE working in a phase, read its instruction
+file in design/instructions/ - they are short, strict, and part of this contract:
+
+| Phase | When | Read |
+|---|---|---|
+| Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
+| Discover | any new surface, feature, or flow | instructions/discover.md |
+| Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
+| Brand | before the first hi-fi work: extract or create the world | instructions/brand.md |
+| Build | hi-fi frames from real components | instructions/craft.md + components.md |
+| Review | before presenting anything | instructions/review.md |
+| Boards | creating a board or publishing | instructions/boards.md |
+
+Refining an existing screen: Configure must hold, then Build + Review. New work runs
+the full ladder. Unsure which phase you are in? Ask the human - one question beats a
+phase of wrong work.
+
+Stuck, or the human is unhappy with a result? instructions/reference/ holds the deep
+guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
+the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
+
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
@@ -11,7 +34,14 @@ Never run or talk to the canvas tool; read and write files only.
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- Use the app's UI: import from {{UI_ALIAS}}; style with the app's Tailwind classes.
+- VERSIONS are sibling frames too - the scene is the surface, each frame one direction:
+  design/scenes/landing/a-terminal.tsx, landing/b-editorial.tsx, landing/c-product.tsx.
+  Layout and the sidebar follow frame-id order, so variants named under one scene with
+  a-/b-/c- prefixes stay adjacent and ordered through tidy and every device view.
+  Never spread versions across scenes (terminal/landing, editorial/landing) - they
+  interleave with everything else and the comparison falls apart.
+- {{UI_GUIDANCE}}
+{{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
   In play mode (the human presses P) frames swap in place inside one device - design flows
   as complete graphs: every screen a data-goto points at should itself link somewhere or be
@@ -28,13 +58,14 @@ Never run or talk to the canvas tool; read and write files only.
    convention). The root design/scenes/_layout.tsx mounts the app's real shell component.
 
 ## Fixtures
-- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the future API.
+- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the component's PROPS (containers map real APIs into them at promotion; see instructions/components.md).
 - Fixture shapes should match the component's props so tsc catches drift.
 - Loading states are fixtures too: export const slowOrders = () => new Promise(r =>
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before exploring.
+- design/manifest.json lists every frame (id, file, scene, title) - read it before
+  exploring. `init` writes the first one; `marver dev` keeps it fresh.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -51,26 +82,7 @@ Never run or talk to the canvas tool; read and write files only.
 
 ## Boards (curated canvases)
 
-A board is a saved canvas: `design/boards/<name>.json` (name: `^[a-z0-9][a-z0-9-]*$`).
-The human switches boards in the sidebar; YOU create and manage them by writing files.
-Minimal file - just list the frames; the shell fills sizes from each frame's viewport,
-lays it out, and keeps it tidy:
-
-```json
-{ "version": 1, "name": "checkout-compare", "auto": false,
-  "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
-```
-
-- The same frame may appear on many boards, or twice on one board (e.g. two widths:
-  add `"w"`/`"h"` on a node to pin a size).
-- `auto: false` boards show exactly their list. The `all-scenes` board is auto-managed -
-  never write it.
-- Use boards for comparisons: version A vs B vs C of a flow, side by side.
-- Boards are also the unit of PUBLISHING (`marver build --boards <name>`): a flow being
-  published must have every frame it data-gotos on that board - unlisted frames are
-  excluded from the bundle at build time. The published gate page shows the app's
-  identity: design/logo.svg + the host package name (overridable via config `share`).
-  If the app has no logo asset yet, create a simple design/logo.svg for it.
-  Leave `share.branding` ON unless the human explicitly asks to remove it: Marver is
-  free, the gate is already fully personalized to the app, and the small "Powered by"
-  line is how the tool spreads. Do not remove it as part of "branding polish".
+A board is a saved canvas: `design/boards/<name>.json` - you create and manage them
+by writing files; `all-scenes` is auto-managed, never write it. BEFORE creating a
+board or publishing anything, read instructions/boards.md (file format, layout
+durability, publishing rules).

package/templates/AGENTS-studio.md

@@ -3,6 +3,29 @@
 You design by writing files. The canvas at the printed localhost URL reflects them live.
 Never run or talk to the canvas tool; read and write files only.
 
+## The method (binding)
+
+Design work moves through phases. BEFORE working in a phase, read its instruction
+file in design/instructions/ - they are short, strict, and part of this contract:
+
+| Phase | When | Read |
+|---|---|---|
+| Configure | first session in a repo, or frames render unstyled | instructions/configure.md |
+| Discover | any new surface, feature, or flow | instructions/discover.md |
+| Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
+| Brand | before the first hi-fi work: extract or create the world | instructions/brand.md |
+| Build | hi-fi frames from real components | instructions/craft.md + components.md |
+| Review | before presenting anything | instructions/review.md |
+| Boards | creating a board or publishing | instructions/boards.md |
+
+Refining an existing screen: Configure must hold, then Build + Review. New work runs
+the full ladder. Unsure which phase you are in? Ask the human - one question beats a
+phase of wrong work.
+
+Stuck, or the human is unhappy with a result? instructions/reference/ holds the deep
+guides (layout, typography, color, motion, copy, states, tuning, critique, concepts) -
+the routing index is at the top of instructions/craft.md. Pull ONE file, apply, return.
+
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
@@ -11,7 +34,14 @@ Never run or talk to the canvas tool; read and write files only.
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- Use the app's UI: import from {{UI_ALIAS}}; style with the app's Tailwind classes.
+- VERSIONS are sibling frames too - the scene is the surface, each frame one direction:
+  design/scenes/landing/a-terminal.tsx, landing/b-editorial.tsx, landing/c-product.tsx.
+  Layout and the sidebar follow frame-id order, so variants named under one scene with
+  a-/b-/c- prefixes stay adjacent and ordered through tidy and every device view.
+  Never spread versions across scenes (terminal/landing, editorial/landing) - they
+  interleave with everything else and the comparison falls apart.
+- {{UI_GUIDANCE}}
+{{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
   In play mode (the human presses P) frames swap in place inside one device - design flows
   as complete graphs: every screen a data-goto points at should itself link somewhere or be
@@ -27,13 +57,14 @@ Never run or talk to the canvas tool; read and write files only.
    convention). The root design/scenes/_layout.tsx is the app shell.
 
 ## Fixtures
-- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the future API.
+- design/scenes/<scene>/_fixtures.ts - typed plain objects shaped like the component's PROPS (containers map real APIs into them at promotion; see instructions/components.md).
 - Frames import fixtures, never stores, never the network, never auth.
 - Loading states are fixtures too: export const slowOrders = () => new Promise(r =>
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before exploring.
+- design/manifest.json lists every frame (id, file, scene, title) - read it before
+  exploring. `init` writes the first one; `marver dev` keeps it fresh.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -51,26 +82,7 @@ Never run or talk to the canvas tool; read and write files only.
 
 ## Boards (curated canvases)
 
-A board is a saved canvas: `design/boards/<name>.json` (name: `^[a-z0-9][a-z0-9-]*$`).
-The human switches boards in the sidebar; YOU create and manage them by writing files.
-Minimal file - just list the frames; the shell fills sizes from each frame's viewport,
-lays it out, and keeps it tidy:
-
-```json
-{ "version": 1, "name": "checkout-compare", "auto": false,
-  "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
-```
-
-- The same frame may appear on many boards, or twice on one board (e.g. two widths:
-  add `"w"`/`"h"` on a node to pin a size).
-- `auto: false` boards show exactly their list. The `all-scenes` board is auto-managed -
-  never write it.
-- Use boards for comparisons: version A vs B vs C of a flow, side by side.
-- Boards are also the unit of PUBLISHING (`marver build --boards <name>`): a flow being
-  published must have every frame it data-gotos on that board - unlisted frames are
-  excluded from the bundle at build time. The published gate page shows the app's
-  identity: design/logo.svg + the host package name (overridable via config `share`).
-  If the app has no logo asset yet, create a simple design/logo.svg for it.
-  Leave `share.branding` ON unless the human explicitly asks to remove it: Marver is
-  free, the gate is already fully personalized to the app, and the small "Powered by"
-  line is how the tool spreads. Do not remove it as part of "branding polish".
+A board is a saved canvas: `design/boards/<name>.json` - you create and manage them
+by writing files; `all-scenes` is auto-managed, never write it. BEFORE creating a
+board or publishing anything, read instructions/boards.md (file format, layout
+durability, publishing rules).

package/templates/instructions/boards.md

@@ -0,0 +1,38 @@
+# Boards - curated canvases and publishing
+
+A board is a saved canvas: `design/boards/<name>.json` (name: `^[a-z0-9][a-z0-9-]*$`).
+The human switches boards in the sidebar; YOU create and manage them by writing files.
+
+## The file
+
+Minimal is enough - list the frames; the shell fills sizes from each frame's
+viewport and lays it out:
+
+```json
+{ "version": 1, "name": "checkout-compare", "auto": false,
+  "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
+```
+
+- The same frame may appear on many boards, or twice on one (add `"w"`/`"h"` on a
+  node to pin a size, `"x"`/`"y"` to place it - e.g. a comparison row: same `y`,
+  increasing `x`).
+- The human's tidy (`t`) and device views re-layout in frame-id order, so id
+  ordering is the durable arrangement; explicit coordinates are one-off setups.
+- `auto: false` boards show exactly their list. `all-scenes` is auto-managed -
+  never write it.
+- Do not edit board files while the canvas is open unless asked; the shell owns
+  their layout fields.
+- Use boards for comparisons: version A vs B vs C of a flow, side by side.
+
+## Publishing
+
+Boards are the unit of publishing (`marver build --boards <name>`): every frame a
+published flow data-gotos must be ON that board - unlisted frames are excluded from
+the bundle at build time.
+
+The published gate page shows the app's identity: `design/logo.svg` + the host
+package name (overridable via config `share`). If the app has no logo asset yet,
+create a simple `design/logo.svg`. Leave `share.branding` ON unless the human
+explicitly asks to remove it: marver is free, the gate is already personalized to
+the app, and the small "Powered by" line is how the tool spreads. Do not remove it
+as part of "branding polish".