@marver-design/marver 0.2.0

package/src/client/stage/main.tsx

@@ -0,0 +1,160 @@
+/**
+ * The stage - play mode's single mount (SPEC-M2 §1). Unlike the frame host (one iframe
+ * per frame), the stage keeps ONE tree mounted - providers + layout chain - and swaps
+ * only the innermost frame on data-goto, so app shells in _layout persist across
+ * navigation like a real app. Swaps ride document.startViewTransition when available;
+ * agents opt into shared-element morphs with plain view-transition-name CSS.
+ *
+ * The shell owns chrome, device sizing, walk order, and the URL; the stage owns data-goto:
+ *   stage -> shell:  sh:stage-ready · sh:stage-at {at} · sh:stage-exit · sh:stage-error
+ *                    sh:stage-key {key, code} (forwarded shortcuts)
+ *   shell -> stage:  sh:stage-set {at} (history / walk / restart) · sh:set-theme
+ */
+import { Component, createElement, useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
+import { flushSync } from 'react-dom'
+import { createRoot } from 'react-dom/client'
+import { frameFile, frames, layoutChain, layouts, providers } from '../frame-host/registry.ts'
+
+const params = new URLSearchParams(location.search)
+document.documentElement.dataset.theme = params.get('theme') ?? 'light'
+const startId = params.get('at') ?? ''
+
+const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
+
+window.addEventListener('error', (e) => post({ type: 'sh:stage-error', message: String(e.message || e.error) }))
+window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:stage-error', message: `unhandled rejection: ${e.reason}` }))
+// pinch inside the stage must not zoom the parent page (same rule as the frame bridge)
+window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
+document.addEventListener('gesturestart', (e) => e.preventDefault())
+
+interface Mounted { id: string; Frame: ComponentType; wrappers: ComponentType[] }
+
+/** Resolve a frame id to its component + wrapper chain. Modules are import()-cached by
+ *  Vite, so re-resolving a chain yields the SAME component references - React keeps
+ *  unchanged layout instances mounted across swaps, which is the whole point. */
+async function resolve(id: string): Promise<Mounted> {
+  const fileKey = frameFile(id)
+  if (!fileKey) throw new Error(`unknown frame id "${id}"`)
+  const mod: any = await frames[fileKey]()
+  if (mod.default == null) throw new Error(`${fileKey} has no default export`)
+  const wrappers: ComponentType[] = []
+  const providerKey = Object.keys(providers)[0]
+  if (providerKey) wrappers.push((await providers[providerKey]() as any).default)
+  for (const lk of layoutChain(fileKey)) wrappers.push((await layouts[lk]() as any).default)
+  return { id, Frame: mod.default, wrappers: wrappers.filter((w) => w != null) }
+}
+
+class Boundary extends Component<{ resetKey: string; children?: ReactNode }, { err: Error | null }> {
+  state = { err: null as Error | null }
+  static getDerivedStateFromError(err: Error) { return { err } }
+  componentDidUpdate(prev: { resetKey: string }) {
+    if (prev.resetKey !== this.props.resetKey && this.state.err) this.setState({ err: null })
+  }
+  componentDidCatch(err: Error) { post({ type: 'sh:stage-error', message: err.message }) }
+  render() {
+    if (!this.state.err) return this.props.children
+    return createElement(ErrorCard, { title: 'frame crashed', message: this.state.err.message, detail: this.props.resetKey })
+  }
+}
+
+function ErrorCard({ title, message, detail }: { title: string; message: string; detail: string }) {
+  return createElement('div', { style: { fontFamily: 'ui-monospace,monospace', fontSize: 12, padding: 16, color: '#ff8a80' } },
+    createElement('div', { style: { fontWeight: 700, marginBottom: 8 } }, title),
+    createElement('div', { style: { whiteSpace: 'pre-wrap' } }, message),
+    createElement('div', { style: { marginTop: 8, color: '#7c859a' } }, detail),
+  )
+}
+
+function Stage() {
+  const [mounted, setMounted] = useState<Mounted | null>(null)
+  const [err, setErr] = useState<{ id: string; message: string } | null>(null)
+  const current = useRef(startId)
+  const swapSeq = useRef(0)
+
+  /** Swap to a frame. `announce` posts sh:stage-at (user-driven); history restores stay silent. */
+  const goto = async (id: string, announce: boolean) => {
+    if (id === current.current && mounted && !err) return
+    const seq = ++swapSeq.current
+    try {
+      const next = await resolve(id)
+      if (seq !== swapSeq.current) return       // a newer swap superseded this one
+      current.current = id
+      // startViewTransition runs its callback async - recheck the seq there too, or an
+      // older pending transition could commit stale state over a newer navigation
+      const apply = () => { if (seq === swapSeq.current) flushSync(() => { setErr(null); setMounted(next) }) }
+      if (document.startViewTransition) document.startViewTransition(apply)
+      else { apply(); document.getElementById('root')?.animate([{ opacity: 0.35 }, { opacity: 1 }], { duration: 180, easing: 'ease-out' }) }
+      if (announce) post({ type: 'sh:stage-at', at: id })
+    } catch (e) {
+      if (seq !== swapSeq.current) return
+      current.current = id
+      setErr({ id, message: (e as Error).message })
+      post({ type: 'sh:stage-error', message: (e as Error).message })
+      if (announce) post({ type: 'sh:stage-at', at: id })
+    }
+  }
+
+  useEffect(() => {
+    goto(startId, false)
+    post({ type: 'sh:stage-ready', at: startId })
+
+    // data-goto is handled HERE, in place - never posted up as sh:go (capture phase
+    // beats any frame handler; preventDefault stops real <a href> navigations)
+    const onClick = (e: MouseEvent) => {
+      const el = e.target instanceof Element ? e.target.closest('[data-goto]') : null
+      if (!el) return
+      e.preventDefault()
+      e.stopPropagation()
+      const target = el.getAttribute('data-goto')
+      if (target) goto(target, true)
+    }
+    document.addEventListener('click', onClick, true)
+
+    const onKey = (e: KeyboardEvent) => {
+      // Escape always exits, even mid-typing (matches the canvas bridge)
+      if (e.key === 'Escape') { post({ type: 'sh:stage-exit' }); return }
+      if ((e.metaKey || e.ctrlKey) && e.key === '/') { e.preventDefault(); post({ type: 'sh:stage-key', key: '/', code: e.code, meta: true }); return }
+      if (e.metaKey || e.ctrlKey) return       // ⌘D is the browser's bookmark, not our theme
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return
+      // every play shortcut belongs to the shell (it owns walk order + chrome) - forward
+      if (/^Digit[0-9]$/.test(e.code) || ['d', 'h', 'r', 'ArrowRight', 'ArrowLeft'].includes(e.key))
+        post({ type: 'sh:stage-key', key: e.key, code: e.code })
+    }
+    window.addEventListener('keydown', onKey)
+
+    const onMsg = (e: MessageEvent) => {
+      if (e.source !== window.parent) return
+      const data = e.data
+      if (data?.type === 'sh:set-theme') document.documentElement.dataset.theme = data.theme
+      else if (data?.type === 'sh:stage-set' && typeof data.at === 'string') goto(data.at, false)
+    }
+    window.addEventListener('message', onMsg)
+
+    return () => {
+      document.removeEventListener('click', onClick, true)
+      window.removeEventListener('keydown', onKey)
+      window.removeEventListener('message', onMsg)
+    }
+  }, [])
+
+  if (err) return createElement(ErrorCard, { title: 'frame failed', message: err.message, detail: err.id })
+  if (!mounted) return null
+  // identical wrapper references across swaps -> React preserves layout state; a chain
+  // that differs at depth k legitimately remounts everything below (SPEC-M2 §1)
+  let tree: ReactNode = createElement(mounted.Frame)
+  for (const W of [...mounted.wrappers].reverse()) tree = createElement(W, null, tree)
+  return createElement(Boundary, { resetKey: mounted.id }, tree)
+}
+
+async function boot() {
+  try {
+    await import('virtual:sh-theme' as string)
+    createRoot(document.getElementById('root')!).render(createElement(Stage))
+  } catch (err) {
+    post({ type: 'sh:stage-error', message: (err as Error).message })
+    document.getElementById('root')!.innerHTML =
+      `<div style="font-family:ui-monospace,monospace;font-size:12px;padding:16px;color:#ff8a80">stage failed: ${String((err as Error).message).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)}</div>`
+  }
+}
+
+boot()

package/templates/AGENTS-embedded.md

@@ -0,0 +1,76 @@
+# Design canvas - agent contract (embedded mode)
+
+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.
+
+## 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:
+  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
+  // 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.
+- 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
+  a terminal state; play mode makes dead ends visible. Give an element the same
+  view-transition-name CSS in two frames and play mode morphs it between screens.
+- Files starting with _ are infrastructure (never frames): _layout.tsx, _fixtures.ts.
+
+## Structure ladder (embedded mode: screens live in src/)
+1. First pass: write the whole page inline in the frame file. Diverge fast.
+2. When a direction wins: extract the screen into src/features/<feature>/<Name>.tsx as a
+   presentational component (props in, JSX out - no hooks into stores or the network),
+   and shrink the frame to a ~5-line harness mounting it with fixtures.
+3. Layouts: design/scenes/<scene>/_layout.tsx wraps every frame in the scene (Next.js
+   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.
+- 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.
+- Component galleries: create design/components/<name>/variants.tsx rendering each variant
+  and each state (default / hover-styled / focus / disabled / loading) of one ui component.
+
+## Rules
+- Do not edit design/boards/*.json while the canvas is open unless asked; the shell owns them.
+- Do not import from "design/" inside src/ or app/. The arrow points one way.
+- Do not add network calls, app stores, or auth to frames or the presentational screens.
+- A scene may not be named "components" or "screens".
+
+## Handoff (when a design is approved)
+- The screen already lives in src/features/. Implementation wires routes, data, and handlers
+  into the same component - fixtures are the only thing replaced. The frame stays, so the
+  canvas remains living documentation of every screen and state.
+
+## 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".

package/templates/AGENTS-studio.md

@@ -0,0 +1,76 @@
+# Design canvas - agent contract
+
+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.
+
+## 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:
+  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
+  // 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.
+- 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
+  a terminal state; play mode makes dead ends visible. Give an element the same
+  view-transition-name CSS in two frames and play mode morphs it between screens.
+- Files starting with _ are infrastructure (never frames): _layout.tsx, _fixtures.ts.
+
+## Structure ladder
+1. First pass: write the whole page inline in the frame file. Diverge fast.
+2. When a direction wins: extract shared markup into design/screens/<Name>.tsx and
+   shrink frames to harnesses that mount it with fixtures.
+3. Layouts: design/scenes/<scene>/_layout.tsx wraps every frame in the scene (Next.js
+   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.
+- 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.
+- Component galleries: create design/components/<name>/variants.tsx rendering each variant
+  and each state (default / hover-styled / focus / disabled / loading) of one ui component.
+
+## Rules
+- Do not edit design/boards/*.json while the canvas is open unless asked; the shell owns them.
+- Do not import from "design/" inside src/ or app/. The arrow points one way.
+- Do not add network calls, app stores, or auth to frames. Mocked data only.
+- Keep each frame self-sufficient: it must render from its file + fixtures + ui imports alone.
+- A scene may not be named "components" or "screens".
+
+## Promotion (when a design is approved)
+- Move the screen from design/screens/ into the app (src/features/...), replace fixture
+  props with live data/handlers, replace data-goto with the router's navigation.
+- Leave the frame in place, importing from its new home, so the canvas stays true.
+
+## 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".

package/templates/demo/_fixtures.ts

@@ -0,0 +1,9 @@
+// Typed mock data, shaped like the future API. Frames import from here, never the network.
+export const fx = {
+  user: { name: 'Alex Rivera', email: 'alex@example.com' },
+  items: [
+    { id: 1, name: 'Aeris Lamp', price: '$39.00' },
+    { id: 2, name: 'Shipping', price: '$9.00' },
+  ],
+  total: '$48.00',
+}

package/templates/demo/dark.tsx

@@ -0,0 +1,17 @@
+// Demo frame: an error state, dark-styled. Sibling frames = states (spec convention).
+export const meta = { title: 'Demo - error state', viewport: 'mobile' }
+
+export default function DarkError() {
+  return (
+    <div style={{ fontFamily: 'system-ui', minHeight: '100vh', background: '#12151f', color: '#e7eaf2', padding: 24, display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <b style={{ fontSize: 16 }}>‹ Checkout</b>
+      <div style={{ background: '#2a1215', border: '1px solid #5c2320', borderRadius: 8, padding: '12px 14px', color: '#f0776b', fontSize: 14, lineHeight: 1.5 }}>
+        <b style={{ display: 'block', color: '#f9a8a0' }}>Card declined</b>
+        Your bank rejected the charge. No money moved.
+      </div>
+      <button data-goto="demo/form" style={{ marginTop: 'auto', padding: '12px 16px', borderRadius: 8, border: '1px solid #363d4f', background: 'transparent', color: '#e7eaf2', fontWeight: 600, cursor: 'pointer' }}>
+        Try another card
+      </button>
+    </div>
+  )
+}

package/templates/demo/form.tsx

@@ -0,0 +1,51 @@
+// Demo frame: proves the resize gesture (real breakpoint at 768px) and interact mode (native <dialog>).
+import { useRef, useState } from 'react'
+import { fx } from './_fixtures.ts'
+
+export const meta = { title: 'Demo - form', viewport: 'laptop' }
+
+export default function Form() {
+  const dlg = useRef<HTMLDialogElement>(null)
+  const [email, setEmail] = useState(fx.user.email)
+  return (
+    <div style={{ fontFamily: 'system-ui', minHeight: '100vh', padding: 24 }}>
+      <style>{`
+        .demo-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 12px }
+        .demo-nav-links { display: flex; gap: 16px }
+        .demo-burger { display: none }
+        @media (max-width: 768px) {
+          .demo-grid { grid-template-columns: 1fr }
+          .demo-nav-links { display: none }
+          .demo-burger { display: block }
+        }
+        .demo-card { border: 1px solid #e4e8f0; border-radius: 10px; padding: 16px }
+        .demo-in { width: 100%; padding: 10px 12px; border: 1px solid #d4d9e4; border-radius: 8px; font-size: 14px }
+        .demo-in:focus { outline: 2px solid #2440c4; outline-offset: 1px }
+        .demo-btn { padding: 10px 16px; border-radius: 8px; border: 0; background: #111; color: #fff; font-weight: 600; cursor: pointer }
+        .demo-btn:hover { opacity: .85 }
+      `}</style>
+      <nav style={{ display: 'flex', alignItems: 'center', gap: 16, marginBottom: 20 }}>
+        <span className="demo-burger">☰</span>
+        <b>◆ Demo</b>
+        <span className="demo-nav-links" style={{ color: '#667085', fontSize: 14 }}><span>Shop</span><span>Journal</span><span>About</span></span>
+      </nav>
+      <div className="demo-grid">
+        {fx.items.map((it) => (
+          <div key={it.id} className="demo-card"><b>{it.name}</b><div style={{ color: '#667085' }}>{it.price}</div></div>
+        ))}
+        <div className="demo-card">
+          <label style={{ fontSize: 13, color: '#667085' }}>Email
+            <input className="demo-in" value={email} onChange={(e) => setEmail(e.target.value)} style={{ marginTop: 6 }} />
+          </label>
+          <button className="demo-btn" style={{ marginTop: 12 }} onClick={() => dlg.current?.showModal()}>Open dialog</button>
+        </div>
+      </div>
+      <p style={{ color: '#98a2b3', fontSize: 13, marginTop: 20 }}>Drag this frame's edge across 768px - the nav collapses to a burger and the grid drops to one column. Real CSS, real viewport.</p>
+      <dialog ref={dlg} style={{ border: '1px solid #e4e8f0', borderRadius: 12, padding: 24, maxWidth: 320 }}>
+        <b>It is a real dialog</b>
+        <p style={{ color: '#667085', fontSize: 14 }}>Typing, focus, and click all work in interact mode. Press Escape to close it, Escape again to leave interact mode.</p>
+        <button className="demo-btn" onClick={() => dlg.current?.close()}>Close</button>
+      </dialog>
+    </div>
+  )
+}

package/templates/demo/welcome.tsx

@@ -0,0 +1,21 @@
+// Demo frame: deletable. Shows meta, fixtures, data-goto. Styled inline so it works in any repo.
+import { fx } from './_fixtures.ts'
+
+export const meta = { title: 'Demo - welcome', viewport: 'mobile' }
+
+const s = {
+  wrap: { fontFamily: 'system-ui', minHeight: '100vh', display: 'flex', flexDirection: 'column', padding: 24, gap: 12, background: 'var(--background, #fff)', color: 'var(--foreground, #111)' },
+  h: { fontSize: 28, fontWeight: 700, letterSpacing: '-0.02em', margin: 0 },
+  p: { color: '#667085', margin: 0, lineHeight: 1.5 },
+  btn: { marginTop: 'auto', padding: '12px 16px', borderRadius: 8, border: 0, background: '#111', color: '#fff', fontWeight: 600, fontSize: 15, cursor: 'pointer' },
+} as const
+
+export default function Welcome() {
+  return (
+    <div style={s.wrap}>
+      <h1 style={s.h}>Hey {fx.user.name.split(' ')[0]} 👋</h1>
+      <p style={s.p}>This frame is a plain file: design/scenes/demo/welcome.tsx. Edit it and watch the canvas update. Double-click the frame to interact.</p>
+      <button style={s.btn} data-goto="demo/form">Continue → (data-goto)</button>
+    </div>
+  )
+}

package/templates/design-tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "noEmit": true
+  },
+  "include": ["."]
+}

package/templates/root-layout.tsx

@@ -0,0 +1,7 @@
+// The app shell for every scene. Replace the placeholder with your real layout
+// (sidebar, nav) once it exists - frames then render inside it automatically.
+import type { ReactNode } from 'react'
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return <>{children}</>
+}