@marver-design/marver 0.2.2 → 0.2.4

package/src/client/shell/tidy.ts

@@ -1,24 +1,354 @@
-export interface TidyNode { key: string; scene: string; w: number; h: number }
+export interface TidyNode { key: string; frame: string; scene: string; group?: string; variant?: string; w: number; h: number }
 export interface Placed { key: string; x: number; y: number }
 
-const GUTTER = 72
-const SCENE_GAP = 96
+// SPEC-024 lane-flow grammar: one shape at both scopes. A scope is rows XOR columns
+// of lanes; a lane is atoms + {space:n} tokens. Board atoms are scene names; a scene
+// recipe's atoms are frame basenames or a variant-group name (one indivisible run).
+export interface Space { space: number }
+export type Lane = Array<string | Space>
+export interface Flow { rows?: Array<Lane | Space>; columns?: Array<Lane | Space> }
+export interface BoardLayout extends Flow { scenes?: Record<string, Flow> }
+export type Warn = (msg: string) => void
 
-/** Pure: rows per scene (scenes alphabetical, node order preserved within a scene). Spec §7. */
-export function tidy(nodes: TidyNode[]): Placed[] {
-  const scenes = [...new Set(nodes.map((n) => n.scene))].sort()
-  const out: Placed[] = []
-  let y = 0
-  for (const scene of scenes) {
-    const row = nodes.filter((n) => n.scene === scene)
-    let x = 0
-    let rowH = 0
-    for (const n of row) {
-      out.push({ key: n.key, x, y })
-      x += n.w + GUTTER
-      rowH = Math.max(rowH, n.h)
+const isSpace = (x: unknown): x is Space => !!x && typeof x === 'object' && !Array.isArray(x)
+const units = (s: Space, warn: Warn): number =>
+  Number.isInteger(s.space) && s.space > 0 ? s.space : (warn(`invalid space ${JSON.stringify(s.space)} - using 1`), 1)
+
+// Adaptive units (SPEC-024 §2): a "block" is a multiple of the proportional gutter,
+// measured from the touching content's characteristic FRAME size (its largest single
+// frame) - a wide multi-frame box must not inflate its neighbors' gutters.
+const frameGapX = (w: number) => Math.max(140, w * 0.12)
+const frameGapY = (h: number) => Math.max(96, h * 0.16)
+const sceneGapX = (w: number) => Math.max(280, w * 0.2)
+const sceneGapY = (h: number) => Math.max(96, h * 0.16)
+
+/** An atom resolved to concrete content: member nodes at relative offsets + extents. */
+interface Box {
+  id: string
+  parts: Array<{ key: string; dx: number; dy: number }>
+  w: number; h: number
+  charW: number; charH: number
+}
+
+const box = (id: string, parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }>): Box => ({
+  id,
+  parts: parts.map(({ key, dx, dy }) => ({ key, dx, dy })),
+  w: Math.max(0, ...parts.map((p) => p.dx + p.w)),
+  h: Math.max(0, ...parts.map((p) => p.dy + p.h)),
+  charW: Math.max(0, ...parts.map((p) => p.w)),
+  charH: Math.max(0, ...parts.map((p) => p.h)),
+})
+
+/** A run of nodes laid side by side (a frame's instances, or a variant run). */
+const runBox = (id: string, run: TidyNode[]): Box => {
+  const parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }> = []
+  let dx = 0
+  for (const n of run) { parts.push({ key: n.key, dx, dy: 0, w: n.w, h: n.h }); dx += n.w + frameGapX(n.w) }
+  return box(id, parts)
+}
+
+/**
+ * The one flow engine (both scopes, both axes). Places boxes; returns absolute box
+ * origins. Lanes share an origin on the cross axis - that IS the alignment.
+ * Two phases: COLLECT lanes (resolving atoms, so skipped content never strands a
+ * track), then PLACE knowing both neighbors of every boundary.
+ */
+function layoutFlow(
+  flow: Flow,
+  resolve: (atom: string) => Box | null,
+  trailing: () => Box[],             // unlisted content, appended after the recipe (evaluated post-collection)
+  trailingMode: 'lanes' | 'append',  // board scope: own trailing lanes · scene scope: tail of the final lane
+  gapX: (c: number) => number,
+  gapY: (c: number) => number,
+  warn: Warn,
+): Map<string, { x: number; y: number }> {
+  const vertical = !!flow.columns    // columns: lanes advance in X, atoms flow in Y
+  // the gap belongs to the AXIS, not the argument slot: a columns lane flows in Y,
+  // so its in-lane gaps are vertical units and its lane boundaries horizontal ones
+  const gapMain = vertical ? gapY : gapX
+  const gapCross = vertical ? gapX : gapY
+  const entries = (vertical ? flow.columns : flow.rows) ?? []
+  const out = new Map<string, { x: number; y: number }>()
+  const seen = new Set<string>()
+
+  // ---- phase 1: collect ----
+  interface CollectedLane { beforeUnits: number; items: Array<Box | number> }  // number = spacer units
+  const lanes: CollectedLane[] = []
+  let pendingLane = 0                // 0 = ordinary boundary · -1 = degraded (consecutive/invalid)
+  for (const entry of entries) {
+    if (isSpace(entry)) {
+      if (pendingLane) { warn('consecutive lane spacers - degrading to one ordinary gap'); pendingLane = -1 }
+      else pendingLane = units(entry, warn)
+      continue
+    }
+    if (!Array.isArray(entry)) continue
+    const items: Array<Box | number> = []
+    let pending = 0
+    let hasBox = false
+    for (const a of entry) {
+      if (isSpace(a)) {
+        if (!hasBox) { warn('leading spacer in lane ignored'); continue }
+        if (pending) { warn('consecutive spacers - degrading to one ordinary gap'); pending = -1; items[items.length - 1] = -1 }
+        else { pending = units(a, warn); items.push(pending) }
+        continue
+      }
+      if (typeof a !== 'string') { warn(`ignoring non-string atom ${JSON.stringify(a)}`); continue }
+      if (seen.has(a)) { warn(`"${a}" listed twice - first occurrence wins`); continue }
+      const b = resolve(a)
+      if (!b) continue                               // resolve() warned with specifics
+      seen.add(a)
+      items.push(b)
+      hasBox = true
+      pending = 0
+    }
+    if (pending) { warn('trailing spacer in lane ignored'); items.pop() }
+    if (!hasBox) {
+      // a lane whose every atom was skipped (or an empty array) must not consume a
+      // track - P1: `[["ghost"],["a"]]` places a at the origin, not one gap down
+      if (entry.length) warn('lane with no placeable content dropped')
+      continue                                       // pendingLane stays armed for the next real lane
+    }
+    if (lanes.length === 0 && pendingLane) warn('leading lane spacer ignored')
+    lanes.push({ beforeUnits: lanes.length === 0 ? 0 : (pendingLane === -1 ? 1 : Math.max(1, pendingLane || 1)), items })
+    pendingLane = 0
+  }
+  if (pendingLane) warn('trailing lane spacer ignored')
+  const extra = trailing()
+  if (extra.length) {
+    if (trailingMode === 'append') {
+      // scene scope: leftovers extend the FINAL lane (one shared row even when
+      // every authored lane was dropped - they must not scatter into lanes)
+      if (lanes.length) lanes[lanes.length - 1].items.push(...extra)
+      else lanes.push({ beforeUnits: 0, items: [...extra] })
+    }
+    else for (const b of extra) lanes.push({ beforeUnits: lanes.length === 0 ? 0 : 1, items: [b] })
+  }
+
+  // ---- phase 2: place ----
+  const laneChar = (l: CollectedLane) =>
+    Math.max(0, ...l.items.filter((i): i is Box => typeof i !== 'number').map((b) => (vertical ? b.charW : b.charH)))
+  const laneExtent = (l: CollectedLane) =>
+    Math.max(0, ...l.items.filter((i): i is Box => typeof i !== 'number').map((b) => (vertical ? b.w : b.h)))
+
+  let cross = 0
+  for (let i = 0; i < lanes.length; i++) {
+    const lane = lanes[i]
+    if (i > 0) {
+      // the boundary sees BOTH lanes (P1: a small lane before a monitor lane must
+      // not produce a phone-sized gap)
+      const c = Math.max(laneChar(lanes[i - 1]), laneChar(lane), 1)
+      cross += laneExtent(lanes[i - 1]) + gapCross(c) * lane.beforeUnits
+    }
+    let main = 0
+    let pendingUnits = 0
+    let prevChar = 0
+    let placedAny = false
+    for (const item of lane.items) {
+      if (typeof item === 'number') { pendingUnits = item; continue }
+      if (placedAny) {
+        const n = pendingUnits === -1 ? 1 : Math.max(1, pendingUnits || 1)
+        main += gapMain(Math.max(prevChar, vertical ? item.charH : item.charW)) * n
+      }
+      pendingUnits = 0
+      out.set(item.id, { x: vertical ? cross : main, y: vertical ? main : cross })
+      main += vertical ? item.h : item.w
+      prevChar = vertical ? item.charH : item.charW
+      placedAny = true
     }
-    y += rowH + SCENE_GAP
   }
   return out
 }
+
+/** Scene placement order for the DEFAULT (recipe-less) flow: appearance order, but a
+ *  variant group is one contiguous run (sorted by variant key) at its first member's slot. */
+function orderWithinScene(members: TidyNode[]): TidyNode[] {
+  const consumed = new Set<string>()
+  const ordered: TidyNode[] = []
+  for (const n of members) {
+    if (consumed.has(n.key)) continue
+    if (!n.group) { ordered.push(n); continue }
+    const run = members.filter((m) => m.group === n.group)
+      .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''))
+    for (const m of run) { ordered.push(m); consumed.add(m.key) }
+  }
+  return ordered
+}
+
+/** Group leftover nodes into placement boxes: node order, variant runs contiguous
+ *  and indivisible (P1: leftovers must honor the same contract as listed content). */
+function leftoverBoxes(remaining: TidyNode[]): Box[] {
+  const out: Box[] = []
+  const consumed = new Set<string>()
+  for (const n of remaining) {
+    if (consumed.has(n.key)) continue
+    if (!n.group) { consumed.add(n.key); out.push(runBox(`${n.frame}#${n.key}`, [n])); continue }
+    const run = remaining.filter((m) => m.group === n.group)
+      .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''))
+    for (const m of run) consumed.add(m.key)
+    out.push(runBox(`${n.group}#run`, run))
+  }
+  return out
+}
+
+const rel = (id: string, scene: string) => (id.startsWith(scene + '/') ? id.slice(scene.length + 1) : id)
+
+/** Lay out ONE scene: recipe if present, else a single default lane. Returns member
+ *  positions relative to the scene origin. */
+function layoutScene(scene: string, members: TidyNode[], flow: Flow | undefined, warn: Warn): Map<string, { x: number; y: number }> {
+  // atoms CONSUME nodes: a later atom that names already-placed content is a
+  // duplicate reference, not a second placement (P1: ["pay", "pay/a"] must not
+  // tear member a out of the run)
+  const consumed = new Set<string>()
+  const boxIndex = new Map<string, Box>()
+  const resolve = (atom: string): Box | null => {
+    const frames = members.filter((n) => rel(n.frame, scene) === atom)
+    const run = members.filter((n) => n.group && rel(n.group, scene) === atom)
+    if (frames.length && run.length) warn(`scene "${scene}": "${atom}" names a frame AND a variant group - the frame wins`)
+    const chosen = frames.length ? frames : run.sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''))
+    if (!chosen.length) { warn(`unknown "${atom}" in scene "${scene}" layout - skipped`); return null }
+    const fresh = chosen.filter((n) => !consumed.has(n.key))
+    if (!fresh.length) { warn(`"${atom}" repeats already-placed content - skipped`); return null }
+    if (!frames.length && fresh.length !== chosen.length) {
+      // some members were placed individually; the run can no longer be indivisible
+      warn(`group "${atom}" already partially placed - skipped (remaining members append as unlisted)`)
+      return null
+    }
+    for (const n of fresh) consumed.add(n.key)
+    const b = runBox(atom, fresh)
+    boxIndex.set(atom, b)
+    return b
+  }
+
+  let flows: Flow
+  if (flow && flow.rows && flow.columns) {
+    warn(`scene "${scene}": layout has rows AND columns - using the default lane`)
+    flows = { rows: [[...new Set(orderWithinScene(members).map((n) => rel(n.frame, scene)))]] }
+  } else if (flow && (flow.rows || flow.columns)) {
+    flows = flow
+  } else {
+    // default: one lane, node order, group runs contiguous (dedupe: duplicate node
+    // instances share one atom - resolve() expands every instance)
+    flows = { rows: [[...new Set(orderWithinScene(members).map((n) => rel(n.frame, scene)))]] }
+  }
+
+  // unlisted frames append AFTER the recipe as their own lane content, node order,
+  // variant runs intact; evaluated post-collection so `consumed` is final
+  const trailing = () => leftoverBoxes(members.filter((n) => !consumed.has(n.key)))
+
+  const placedBoxes = layoutFlow(flows, resolve, () => {
+    const boxes = trailing()
+    for (const b of boxes) boxIndex.set(b.id, b)
+    return boxes
+  }, 'append', frameGapX, frameGapY, warn)
+
+  const out = new Map<string, { x: number; y: number }>()
+  for (const [id, pos] of placedBoxes) {
+    const b = boxIndex.get(id)
+    if (!b) continue
+    for (const p of b.parts) out.set(p.key, { x: pos.x + p.dx, y: pos.y + p.dy })
+  }
+  return out
+}
+
+/**
+ * Pure layout (spec §7 + SPEC-023 + SPEC-024). Returns positions only - the nodes
+ * array is never reordered (iframe law G-1). Two passes: each scene lays out its
+ * frames (recipe or default lane), then the board flow places the scene boxes.
+ */
+export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () => {}): Placed[] {
+  const scenes = [...new Set(nodes.map((n) => n.scene))]
+
+  // pass 1: per-scene relative layouts + bounding boxes
+  const sceneMaps = new Map<string, Map<string, { x: number; y: number }>>()
+  const sceneBoxes = new Map<string, Box>()
+  for (const scene of scenes) {
+    const members = nodes.filter((n) => n.scene === scene)
+    const m = layoutScene(scene, members, layout?.scenes?.[scene], warn)
+    sceneMaps.set(scene, m)
+    const parts = members
+      .filter((n) => m.has(n.key))
+      .map((n) => ({ key: n.key, dx: m.get(n.key)!.x, dy: m.get(n.key)!.y, w: n.w, h: n.h }))
+    sceneBoxes.set(scene, box(scene, parts))
+  }
+
+  // pass 2: board flow over scene boxes. rows AND columns is invalid: fall back to
+  // PLAIN tidy (default trailing lanes), never a silent pick (SPEC-024 §5)
+  let boardFlow: Flow
+  if (layout && layout.rows && layout.columns) { warn('layout has rows AND columns - ignoring it (plain tidy)'); boardFlow = { rows: [] } }
+  else if (layout && (layout.rows || layout.columns)) boardFlow = { rows: layout.rows, columns: layout.columns }
+  else boardFlow = { rows: [] }      // default: every scene its own trailing lane (alphabetical)
+
+  const listed = new Set<string>()
+  for (const entry of [...(boardFlow.rows ?? []), ...(boardFlow.columns ?? [])]) {
+    if (Array.isArray(entry)) for (const a of entry) if (typeof a === 'string') listed.add(a)
+  }
+  // board scope: unlisted scenes become their OWN trailing lanes (below in rows mode,
+  // right in columns mode), alphabetical
+  const trailing = () => scenes.filter((s) => !listed.has(s)).sort().map((s) => sceneBoxes.get(s)!)
+
+  const placedScenes = layoutFlow(
+    boardFlow,
+    (atom) => {
+      const b = sceneBoxes.get(atom)
+      if (!b) warn(`unknown scene "${atom}" in layout - skipped`)
+      return b ?? null
+    },
+    trailing,
+    'lanes',
+    sceneGapX, sceneGapY, warn,
+  )
+
+  const out: Placed[] = []
+  for (const [scene, pos] of placedScenes) {
+    const m = sceneMaps.get(scene)
+    if (!m) continue
+    for (const [key, p] of m) out.push({ key, x: pos.x + p.x, y: pos.y + p.y })
+  }
+  return out
+}
+
+/** Guarded parse of agent-authored board.layout (SPEC-024 §1). Malformed pieces warn
+ *  and degrade - they never blank the board, and never vanish silently. */
+export function parseLayout(raw: unknown, warn: Warn): BoardLayout | null {
+  if (raw === undefined || raw === null) return null
+  if (typeof raw !== 'object' || Array.isArray(raw)) { warn('layout must be an object - ignored'); return null }
+  const o = raw as Record<string, unknown>
+  const flow = parseFlow(o, warn)
+  const scenes: Record<string, Flow> = {}
+  if (o.scenes !== undefined) {
+    if (!o.scenes || typeof o.scenes !== 'object' || Array.isArray(o.scenes)) warn('layout.scenes must be an object map - ignored')
+    else {
+      for (const [k, v] of Object.entries(o.scenes as Record<string, unknown>)) {
+        const f = v && typeof v === 'object' && !Array.isArray(v) ? parseFlow(v as Record<string, unknown>, warn) : null
+        if (f) scenes[k] = f
+        else warn(`layout.scenes["${k}"] is not a rows/columns flow - ignored`)
+      }
+    }
+  }
+  if (!flow && !Object.keys(scenes).length) return null
+  return { ...(flow ?? {}), ...(Object.keys(scenes).length ? { scenes } : {}) }
+}
+
+function parseFlow(o: Record<string, unknown>, warn: Warn): Flow | null {
+  const parseEntries = (v: unknown): Array<Lane | Space> | null => {
+    if (!Array.isArray(v)) { if (v !== undefined) warn('layout rows/columns must be an array - ignored'); return null }
+    const out: Array<Lane | Space> = []
+    for (const e of v) {
+      if (Array.isArray(e)) {
+        // pass atoms through loosely - the ENGINE warns with placement specifics -
+        // but never SILENTLY strip junk (a dropped atom must be visible)
+        out.push(e.filter((a: unknown): a is string | Space => {
+          const ok = typeof a === 'string' || (!!a && typeof a === 'object' && !Array.isArray(a))
+          if (!ok) warn(`ignoring invalid layout atom ${JSON.stringify(a)}`)
+          return ok
+        }))
+      } else if (e && typeof e === 'object' && !Array.isArray(e)) out.push(e as Space)
+      else warn(`ignoring invalid layout entry ${JSON.stringify(e)}`)
+    }
+    return out                                   // an EMPTY array is still a layout
+  }
+  const rows = parseEntries(o.rows)
+  const columns = parseEntries(o.columns)
+  if (!rows && !columns) return null
+  return { ...(rows ? { rows } : {}), ...(columns ? { columns } : {}) }
+}

package/src/client/stage/main.tsx

@@ -16,7 +16,12 @@ 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'
+// Both signals, always - same pair as the frame host: [data-theme] for attribute-keyed
+// token systems, .dark for class-keyed ones (Tailwind/shadcn). Missing the class made
+// play render class-keyed apps light while the canvas showed them dark.
+const bootTheme = params.get('theme') ?? 'light'
+document.documentElement.dataset.theme = bootTheme
+document.documentElement.classList.toggle('dark', bootTheme === 'dark')
 const startId = params.get('at') ?? ''
 
 const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
@@ -117,7 +122,7 @@ function Stage() {
       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))
+      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)
@@ -125,7 +130,10 @@ function Stage() {
     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
+      if (data?.type === 'sh:set-theme') {
+        document.documentElement.dataset.theme = data.theme
+        document.documentElement.classList.toggle('dark', data.theme === 'dark')
+      }
       else if (data?.type === 'sh:stage-set' && typeof data.at === 'string') goto(data.at, false)
     }
     window.addEventListener('message', onMsg)

package/templates/AGENTS-embedded.md

@@ -1,7 +1,9 @@
 # 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.
+Never drive or automate the canvas UI; read and write files only. (Starting
+`npx marver dev` so the human has a live canvas - first session, or on request -
+is the one allowed touch.)
 
 ## The method (binding)
 
@@ -10,6 +12,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 
 | Phase | When | Read |
 |---|---|---|
+| Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
 | 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 |
@@ -22,6 +25,12 @@ Refining an existing screen: Configure must hold, then Build + Review. New work
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
 phase of wrong work.
 
+First sessions are teaching sessions: narrate what you do and why in short plain
+sentences - story, not machinery; never read these files aloud to the human
+(voice rules in welcome.md).
+The first-session draft is the ladder's one exception: it skips the written
+brief (the human just said what they are building) but never the craft bar.
+
 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.
@@ -32,14 +41,16 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   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.
+  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
+  // frame's own size, 1..n per configured device) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- 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.
+- VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
+  design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept
+  contiguous through tidy and device views, badged A/B on the canvas, one row with
+  chips in the sidebar, and switchable in place in play mode ([ and ]). Scope
+  alternatives inside a busy scene with a nested dir: checkout/payment/a-card.tsx vs
+  b-wallet.tsx groups beside checkout/cart.tsx. meta `of`/`variant` (literal strings)
+  override when filenames can't carry it. Never spread versions across scenes.
 - {{UI_GUIDANCE}}
 {{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
@@ -83,6 +94,9 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
 ## Boards (curated canvases)
 
 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).
+by writing files; `all-scenes` is auto-managed, never write it. Compose a board
+deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
+whitespace tokens, and the same grammar per scene for frames (columns align left
+edges; a variant-group name is one indivisible atom). BEFORE creating a board or
+publishing anything, read instructions/boards.md (the layout grammar, file format,
+publishing rules).

package/templates/AGENTS-studio.md

@@ -1,7 +1,9 @@
 # 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.
+Never drive or automate the canvas UI; read and write files only. (Starting
+`npx marver dev` so the human has a live canvas - first session, or on request -
+is the one allowed touch.)
 
 ## The method (binding)
 
@@ -10,6 +12,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
 
 | Phase | When | Read |
 |---|---|---|
+| Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
 | 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 |
@@ -22,6 +25,12 @@ Refining an existing screen: Configure must hold, then Build + Review. New work
 the full ladder. Unsure which phase you are in? Ask the human - one question beats a
 phase of wrong work.
 
+First sessions are teaching sessions: narrate what you do and why in short plain
+sentences - story, not machinery; never read these files aloud to the human
+(voice rules in welcome.md).
+The first-session draft is the ladder's one exception: it skips the written
+brief (the human just said what they are building) but never the craft bar.
+
 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.
@@ -32,14 +41,16 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   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.
+  // flip the whole board to any device (Devices menu; digit keys - 0 restores each
+  // frame's own size, 1..n per configured device) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- 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.
+- VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
+  design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept
+  contiguous through tidy and device views, badged A/B on the canvas, one row with
+  chips in the sidebar, and switchable in place in play mode ([ and ]). Scope
+  alternatives inside a busy scene with a nested dir: checkout/payment/a-card.tsx vs
+  b-wallet.tsx groups beside checkout/cart.tsx. meta `of`/`variant` (literal strings)
+  override when filenames can't carry it. Never spread versions across scenes.
 - {{UI_GUIDANCE}}
 {{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
@@ -83,6 +94,9 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
 ## Boards (curated canvases)
 
 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).
+by writing files; `all-scenes` is auto-managed, never write it. Compose a board
+deliberately with `"layout"`: rows/columns lanes of scenes plus `{ "space": n }`
+whitespace tokens, and the same grammar per scene for frames (columns align left
+edges; a variant-group name is one indivisible atom). BEFORE creating a board or
+publishing anything, read instructions/boards.md (the layout grammar, file format,
+publishing rules).

package/templates/design-tsconfig.json

@@ -2,7 +2,12 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "jsx": "react-jsx",
-    "noEmit": true
+    "noEmit": true,
+    // frames import _fixtures.ts with the extension (marver's native-TS convention)
+    "allowImportingTsExtensions": true{{PATHS}}
   },
-  "include": ["."]
+  "include": ["."],
+  // the host tsconfig excludes "design" (init adds it so the APP's typecheck skips
+  // frames); inherited here it would make this project exclude itself (TS18003)
+  "exclude": ["node_modules"]
 }

package/templates/instructions/boards.md

@@ -22,7 +22,53 @@ viewport and lays it out:
   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.
+- Use boards for comparisons: version A vs B vs C of a flow, side by side. Variant
+  groups (letter-prefixed siblings) stay contiguous through every relayout
+  automatically.
+
+## Composing the canvas: `layout`
+
+Compose a board deliberately - whitespace, lanes, alignment - with a `layout`
+recipe. One grammar: a scope is `"rows"` OR `"columns"` of lanes; a lane is an
+ordered list of atoms and `{ "space": n }` tokens.
+
+```json
+{ "version": 1, "name": "showcase", "auto": false,
+  "layout": {
+    "columns": [
+      ["hero", { "space": 2 }, "archive"],
+      { "space": 4 },
+      ["variants"]
+    ],
+    "scenes": {
+      "hero": { "rows": [["overview", "detail", "proof", { "space": 3 }, "directions"]] }
+    }
+  },
+  "nodes": [ { "frame": "hero/overview" }, { "frame": "hero/detail" } ] }
+```
+
+- **Board scope** (`layout.rows` / `layout.columns`): atoms are scene names.
+  `rows` lanes stack top-to-bottom, scenes in a lane flow left-to-right.
+  `columns` lanes sit left-to-right, scenes in a lane stack top-to-bottom and
+  share a left edge - use columns when things must align vertically (a parked
+  archive under a hero, a variants cluster off to the right).
+- **Scene scope** (`layout.scenes.<scene>`): the same grammar, atoms are frame
+  basenames within that scene; a variant-group name (its directory name) is ONE
+  atom - the run stays together. Example above: three frames, a 3-unit gap, then
+  the variant run.
+- `{ "space": n }` = n gap units at that boundary; a unit is the adaptive gutter
+  (proportional to the touching frames), so spacing holds across phone and
+  monitor frames and through resizes. Plain adjacency = 1 unit.
+- **Isolate variant runs.** When a variant group shares a scene with regular
+  flow frames, put `{ "space": 2 }` or `{ "space": 3 }` before (and after, if
+  frames follow) the group's atom in that scene's recipe - explorations should
+  read as their own cluster, not blend into the flow:
+  `"scenes": { "checkout": { "rows": [["cart", "payment", { "space": 3 }, "directions"]] } }`
+- Tidy, device switches, and frame resizes re-apply the recipe; dragging stays
+  free until sizes change. Scenes/frames not listed append after, in default
+  order. Unknown names warn and skip - check the name against the sidebar.
+- Legacy `"sceneRows": [["landing","docs"]]` still works (= a plain `rows`
+  layout); prefer `layout` for anything new.
 
 ## Publishing
 

package/templates/instructions/configure.md

@@ -20,9 +20,12 @@ All four true → idle state. Go design.
 
 ## By repo maturity
 
+The human's first session layers on top of this: philosophy, their product on the
+canvas, the tour - that flow lives in instructions/welcome.md, run it alongside.
+
 - **Brand-new repo (no app)**: `design/instructions/setup.md` exists and is the
-  authority - STOP, follow it (set up the stack, re-run init). Do not design against
-  a repo that has nothing to build from.
+  authority - follow it (set up the stack WITH the human, re-run init). Do not
+  design against a repo that has nothing to build from.
 - **Fresh repo (app scaffolded, little product code)**: init's detection is usually
   right. Verify the checklist, create DESIGN.md from the starter tokens (Path A -
   even a default shadcn theme is a documentable brand), and note in it which parts