@marver-design/marver 0.2.4 → 0.3.0

package/src/client/shell/store.ts

@@ -14,7 +14,7 @@ const DATA: { manifest: Manifest; boards: Record<string, unknown>; names: string
 /** 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; variantGroup?: string; variant?: string }
+export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number }
 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
@@ -26,6 +26,11 @@ export interface Node {
   /** 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
+  /** Size provenance for CONTENT frames (SPEC-026), explicit: 'auto' = measured
+   *  (transient - never serialized); 'manual' = the human's - measurements never
+   *  overwrite; 'device' = a preset's. UI frames never carry it. Only manual/device
+   *  persist, so a reload can tell an authored size from a measured one. */
+  sizeMode?: 'auto' | 'manual' | 'device'
   status: 'loading' | 'ready' | 'error'; error?: string; missing?: boolean
 }
 export interface Toast { id: number; text: string }
@@ -71,7 +76,18 @@ const initialViewTheme = () => {
 }
 const manifestKey = (m: Manifest) => JSON.stringify(m.frames)   // any change counts, not just added/removed ids
 
+/** Latest measured content heights, keyed frameId@width. TRANSIENT by design
+ *  (SPEC-026): auto sizes are never serialized - a reload remeasures. */
+const measuredHeights = new Map<string, number>()
+
 function defaultSize(frame: FrameEntry) {
+  // content frames (SPEC-026): own width from Doc layout; height from the latest
+  // measurement at that width, or a placeholder until sh:measure lands.
+  // meta.viewport, when declared, wins - the existing precedence.
+  if (frame.contentWidth && !frame.viewport) {
+    const w = frame.contentWidth
+    return { w, h: measuredHeights.get(`${frame.id}@${w}`) ?? Math.round(w * 0.75) }
+  }
   const vp = CONFIG.viewports[frame.viewport ?? ''] ?? CONFIG.viewports.mobile ?? { width: 390, height: 844 }
   return { w: vp.width, h: vp.height }
 }
@@ -102,7 +118,7 @@ interface State {
   sceneRows: string[][] | null        // LEGACY scene arrangement (SPEC-023 §2); still round-trips through save
   layout: BoardLayout | null          // lane-flow recipe (SPEC-024), parsed; wins over sceneRows when both exist
   layoutRaw: unknown                  // the author's layout VERBATIM - save round-trips this, never the parse
-  baseLayout: Record<string, { x: number; y: number; w: number; h: number }> | null   // snapshot taken on entering a device view; Default restores it exactly
+  baseLayout: Record<string, { x: number; y: number; w?: number; h?: number }> | null   // snapshot taken on entering a device view; Default restores it exactly (auto content entries carry positions only - their sizes are measured)
   panelOpen: boolean
   scale: number
   toasts: Toast[]
@@ -114,6 +130,7 @@ interface State {
   frameFor(node: Node): FrameEntry | undefined
   moveNode(key: string, x: number, y: number): void
   resizeNode(key: string, w: number, h: number): void
+  measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
   setStatus(key: string, status: Node['status'], error?: string): void
   removeNode(key: string): void
   select(key: string | null, additive?: boolean): void
@@ -144,6 +161,21 @@ export const useStore = create<State>((set, get) => {
   let switchSeq = 0                                  // last click wins when board switches race
   const scheduleSave = () => { editRev++; clearTimeout(saveTimer); saveTimer = setTimeout(() => get().save(), 500) }
 
+  // SPEC-026: one cancelable, BOARD-SCOPED reflow after content measurements settle.
+  // The captured board name is the generation guard - a debounce surviving a board
+  // switch fires into a name check and dies, never touching the new board.
+  let reflowTimer: ReturnType<typeof setTimeout> | undefined
+  const scheduleReflow = () => {
+    const boardAt = get().board
+    clearTimeout(reflowTimer)
+    reflowTimer = setTimeout(() => {
+      const s = get()
+      if (s.board !== boardAt) return
+      if (s.gesture) { scheduleReflow(); return }   // defer, never drop - retries after the drag
+      if (s.layout || s.sceneRows?.length) s.runTidy()
+    }, 400)
+  }
+
   /** Theme resolution ladder: user pin > the frame's declared meta.theme > viewTheme. */
   const resolveTheme = (frame?: FrameEntry, user?: string) => user ?? frame?.theme ?? get().viewTheme
 
@@ -163,6 +195,28 @@ export const useStore = create<State>((set, get) => {
     },
   }
 
+  /** Published parity for content-frame sizes (SPEC-026): manual/device sizes persist
+   *  to the session the same way theme pins do - a board switch or reload on a
+   *  published canvas must not silently drop a hand-resized spec frame. Keys are
+   *  frame#occurrence: node keys are minted per load on virtual boards, but the node
+   *  ORDER round-trips (board file order / manifest order), so the ordinal is the
+   *  stable identity - duplicates of one frame keep their individual sizes. */
+  const sizeKey = (nodes: Node[], node: Node) =>
+    `${node.frame}#${nodes.filter((n) => n.frame === node.frame).indexOf(node)}`
+  const sessionSizes = {
+    read(board: string): Record<string, { w: number; h: number; sizeMode: 'manual' | 'device' }> {
+      try { return JSON.parse(sessionStorage.getItem(`mv-sizes-${board}`) ?? '{}') } catch { return {} }
+    },
+    write(board: string, nodes: Node[]) {
+      try {
+        const sizes: Record<string, { w: number; h: number; sizeMode: string }> = {}
+        for (const n of nodes) if (n.sizeMode === 'manual' || n.sizeMode === 'device')
+          sizes[sizeKey(nodes, n)] = { w: Math.round(n.w), h: Math.round(n.h), sizeMode: n.sizeMode }
+        sessionStorage.setItem(`mv-sizes-${board}`, JSON.stringify(sizes))
+      } catch { /* storage unavailable */ }
+    },
+  }
+
   /** Fetch + normalize a board into ready-to-commit state, WITHOUT touching the store.
    *  null = failure (transport, malformed manifest, non-404 board error) - the caller
    *  keeps whatever board is currently mounted. */
@@ -221,11 +275,17 @@ export const useStore = create<State>((set, get) => {
             let key = typeof n.key === 'string' && n.key ? n.key : nodeKey()
             if (seenKeys.has(key)) key = nodeKey()
             seenKeys.add(key)
+            // content-frame size provenance round-trips (SPEC-026); auto nodes saved no
+            // w/h, so they fall to defaultSize (placeholder) and remeasure on mount
+            const sizeMode = f?.contentWidth
+              ? { sizeMode: (n.sizeMode === 'manual' || n.sizeMode === 'device' ? n.sizeMode : 'auto') as Node['sizeMode'] }
+              : {}
             return {
               key,
               frame: n.frame,
               x: typeof n.x === 'number' ? n.x : 0, y: typeof n.y === 'number' ? n.y : 0,
               w: typeof n.w === 'number' ? n.w : d.w, h: typeof n.h === 'number' ? n.h : d.h,
+              ...sizeMode,
               // pins persist as their own field (exact round-trip). Legacy boards stored a
               // theme on EVERY node: only values differing from the frame's static default
               // were deliberate - the rest follow viewTheme
@@ -285,17 +345,23 @@ export const useStore = create<State>((set, get) => {
             : null
           if (sibling) { x = sibling.x + sibling.w + Math.max(140, sibling.w * 0.12); y = sibling.y }
           else { x = nodes.length ? maxX + 96 : 0; y = 0 }
-          const node: Node = { key: nodeKey(), frame: f.id, x, y, w, h, theme: resolveTheme(f), status: 'loading' }
+          const node: Node = { key: nodeKey(), frame: f.id, x, y, w, h, theme: resolveTheme(f), status: 'loading', ...(f.contentWidth ? { sizeMode: (vp ? 'device' : 'auto') as Node['sizeMode'] } : {}) }
           nodes.push(node)
           maxX = Math.max(maxX, x + w)
         }
       }
-      // published: re-apply this visit's pins over the inlined data
+      // published: re-apply this visit's pins and content sizes over the inlined data
       if (DATA && nodes.length) {
         const pins = sessionPins.read(boardName)
+        const sizes = sessionSizes.read(boardName)
         for (const n of nodes) {
           const pin = pins[n.frame]
           if (pin && CONFIG.themes.includes(pin)) { n.themeUser = pin; n.theme = pin }
+          const sz = sizes[sizeKey(nodes, n)]
+          if (sz && manifest.frames.find((f) => f.id === n.frame)?.contentWidth
+            && Number.isFinite(sz.w) && Number.isFinite(sz.h) && (sz.sizeMode === 'manual' || sz.sizeMode === 'device')) {
+            n.w = sz.w; n.h = sz.h; n.sizeMode = sz.sizeMode
+          }
         }
       }
       if ((!boardHash || needTidy) && nodes.length) {
@@ -393,9 +459,10 @@ export const useStore = create<State>((set, get) => {
           ? next.filter((n) => { const g = m.frames.find((x) => x.id === n.frame)?.variantGroup; return g === f.variantGroup && !n.missing })
           : []
         const right = sibs.length ? sibs.reduce((a, n) => (n.x > a.x ? n : a)) : null
+        const mode = f.contentWidth ? { sizeMode: (vp ? 'device' : 'auto') as Node['sizeMode'] } : {}
         const node = right
-          ? { key: nodeKey(), frame: f.id, x: right.x + right.w + Math.max(140, right.w * 0.12), y: right.y, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' as const }
-          : { key: nodeKey(), frame: f.id, x: 0, y: maxY + 96, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' as const }
+          ? { key: nodeKey(), frame: f.id, x: right.x + right.w + Math.max(140, right.w * 0.12), y: right.y, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' as const, ...mode }
+          : { key: nodeKey(), frame: f.id, x: 0, y: maxY + 96, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' as const, ...mode }
         next.push(node)
         // in a device view, the snapshot learns the newcomer's DEFAULT size so 0 restores it sanely
         if (vp && nextBase) nextBase = { ...nextBase, [node.key]: { x: node.x, y: node.y, w: d.w, h: d.h } }
@@ -412,6 +479,12 @@ 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 }
+        // content-ness can change live (agent adds/removes the primitives): reconcile
+        // provenance or measurements are rejected / UI dims silently omitted from saves.
+        // Under an active device view the newcomer joins it as 'device' - a measurement
+        // must not override the preset the whole board is showing
+        if (f?.contentWidth && !n.sizeMode) { n.sizeMode = deviceView ? 'device' : 'auto'; retinted = true }
+        if (!f?.contentWidth && n.sizeMode) { delete n.sizeMode; 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 }
@@ -478,8 +551,10 @@ export const useStore = create<State>((set, get) => {
       set((s) => {
         const W = Math.max(120, w), H = Math.max(80, h)
         const cur = s.nodes.find((n) => n.key === key)
+        // a human-resized CONTENT frame goes 'manual': measurements never overwrite it (SPEC-026)
+        const content = !!s.manifest?.frames.find((x) => x.id === cur?.frame)?.contentWidth
         return {
-          nodes: s.nodes.map((n) => (n.key === key ? { ...n, w: W, h: H } : n)),
+          nodes: s.nodes.map((n) => (n.key === key ? { ...n, w: W, h: H, ...(content ? { sizeMode: 'manual' as const } : {}) } : n)),
           dirty: true,
           deviceView: null,
           baseLayout: s.baseLayout && cur
@@ -491,21 +566,62 @@ export const useStore = create<State>((set, get) => {
       // the gesture-end hook saves once, after any retidy
       if (!inGesture) scheduleSave()
     },
+
+    /** SPEC-026 sh:measure. Admission: content frames only, finite positive numbers,
+     *  clamped. A height only commits when it was measured at the width being applied;
+     *  auto sizes are transient - applying one never dirties the board (positions from
+     *  the follow-up reflow do, exactly like a human resize). */
+    measureNode(key, frameId, ownWidth, measuredWidth, height) {
+      const s = get()
+      const node = s.nodes.find((n) => n.key === key)
+      if (!node || node.sizeMode !== 'auto') return       // manual/device always win
+      if (node.frame !== frameId) return                  // generation guard: a reused node key
+                                                          // across a board switch never mis-attributes
+      const f = s.manifest?.frames.find((x) => x.id === node.frame)
+      if (!f?.contentWidth) return                        // not a content frame - spoof-proofing
+      if (![ownWidth, measuredWidth, height].every((v) => Number.isFinite(v) && v > 0)) return
+      const maxH = Math.round(2.5 * Math.max(844, ...Object.values(CONFIG.viewports).map((v) => v.height)))
+      // declared meta.viewport WINS over the Doc layout width - the existing precedence
+      const vpw = CONFIG.viewports[f.viewport ?? '']?.width
+      const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+      const H = Math.min(maxH, Math.max(80, Math.round(height)))
+      const curW = Math.round(node.w)
+      measuredHeights.set(`${node.frame}@${Math.round(measuredWidth)}`, H)
+      if (Math.round(measuredWidth) !== curW) return      // height not true at the applied width
+      if (W !== curW) {
+        // Doc layout changed (document<->wide): adopt the new own width first; the
+        // iframe resizes, remeasures, and the height commits on the next message
+        set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
+        scheduleReflow()
+        return
+      }
+      if (Math.round(node.h) === H) return
+      set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
+      scheduleReflow()
+    },
     setDeviceView(name) {
       const vp = name ? CONFIG.viewports[name] : null
       if (name && !vp) return
       set((s) => {
-        // entering a device view from free-form: snapshot the layout so Default restores it
+        // entering a device view from free-form: snapshot the layout so Default restores it.
+        // Auto content nodes snapshot POSITIONS only - their w/h are measured (transient by
+        // contract) and restore comes from the measurement cache, never from the snapshot
         const baseLayout = name
           ? (s.deviceView === null
-              ? Object.fromEntries(s.nodes.map((n) => [n.key, { x: n.x, y: n.y, w: n.w, h: n.h }]))
+              ? Object.fromEntries(s.nodes.map((n) => [n.key, n.sizeMode === 'auto' ? { x: n.x, y: n.y } : { x: n.x, y: n.y, w: n.w, h: n.h }]))
               : s.baseLayout)
           : null
         const nodes = s.nodes.map((n) => {
-          if (vp) return { ...n, w: vp.width, h: vp.height }
+          const f = s.manifest?.frames.find((x) => x.id === n.frame)
+          const content = !!f?.contentWidth
+          if (vp) return { ...n, w: vp.width, h: vp.height, ...(content ? { sizeMode: 'device' as const } : {}) }
+          // digit 0 on a CONTENT frame = back to auto: measured size, remeasure ahead (SPEC-026)
           const b = s.baseLayout?.[n.key]
+          if (content && f) {
+            const d = defaultSize(f)
+            return { ...n, ...(b ? { x: b.x, y: b.y } : {}), w: d.w, h: d.h, sizeMode: 'auto' as const }
+          }
           if (b) return { ...n, ...b }               // exact free-form layout, positions included
-          const f = s.manifest?.frames.find((x) => x.id === n.frame)
           if (!f) return n
           const d = defaultSize(f)                   // frames added mid-device-view get their default
           return { ...n, w: d.w, h: d.h }
@@ -539,11 +655,13 @@ export const useStore = create<State>((set, get) => {
         const sel = new Set(s.selection)
         const nodes = s.nodes.map((n) => {
           if (!sel.has(n.key)) return n
-          if (vp) return { ...n, w: vp.width, h: vp.height }
           const f = s.manifest?.frames.find((x) => x.id === n.frame)
+          const content = !!f?.contentWidth
+          if (vp) return { ...n, w: vp.width, h: vp.height, ...(content ? { sizeMode: 'device' as const } : {}) }
           if (!f) return n
           const d = defaultSize(f)
-          return { ...n, w: d.w, h: d.h }
+          // digit 0 on a content frame clears provenance back to auto (SPEC-026)
+          return { ...n, w: d.w, h: d.h, ...(content ? { sizeMode: 'auto' as const } : {}) }
         })
         const baseLayout = s.baseLayout ? { ...s.baseLayout } : null
         if (baseLayout) for (const k of s.selection) {
@@ -623,7 +741,7 @@ export const useStore = create<State>((set, get) => {
       const d = defaultSize(f)
       const vp = deviceView ? CONFIG.viewports[deviceView] : null
       const maxX = nodes.reduce((a, n) => Math.max(a, n.x + n.w), 0)
-      const node: Node = { key: nodeKey(), frame: f.id, x: maxX + 96, y: 0, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' }
+      const node: Node = { key: nodeKey(), frame: f.id, x: maxX + 96, y: 0, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading', ...(f.contentWidth ? { sizeMode: (vp ? 'device' : 'auto') as Node['sizeMode'] } : {}) }
       set((s) => ({
         nodes: [...s.nodes, node],
         dirty: true,
@@ -642,6 +760,7 @@ export const useStore = create<State>((set, get) => {
       // session instead, and dirty must clear or switchBoard's save-flush loop wedges
       if (DATA) {
         sessionPins.write(get().board, get().nodes)
+        sessionSizes.write(get().board, get().nodes)
         set({ dirty: false })
         return Promise.resolve(true)
       }
@@ -660,9 +779,23 @@ export const useStore = create<State>((set, get) => {
           ...(deviceView ? { deviceView } : {}),
           ...(get().sceneRows?.length ? { sceneRows: get().sceneRows } : {}),
           ...(get().layoutRaw !== undefined ? { layout: get().layoutRaw } : {}),
-          ...(baseLayout ? { baseLayout } : {}),
-          // only PINNED themes persist - inherited values follow viewTheme at load time
-          nodes: nodes.map(({ key, frame, x, y, w, h, themeUser }) => ({ key, frame, x: Math.round(x), y: Math.round(y), w: Math.round(w), h: Math.round(h), ...(themeUser ? { themeUser } : {}) })),
+          // baseLayout entries for auto content nodes keep POSITIONS only - their
+          // measured dimensions are transient and never reach the file (SPEC-026)
+          ...(baseLayout ? {
+            baseLayout: Object.fromEntries(Object.entries(baseLayout).map(([k, b]) => {
+              const n = nodes.find((x) => x.key === k)
+              return n?.sizeMode === 'auto' ? [k, { x: b.x, y: b.y }] : [k, b]
+            })),
+          } : {}),
+          // only PINNED themes persist - inherited values follow viewTheme at load time.
+          // Content frames in AUTO save no dimensions (SPEC-026): measured sizes are
+          // transient - a reflow-triggered save can never leak an auto height to disk.
+          nodes: nodes.map(({ key, frame, x, y, w, h, themeUser, sizeMode }) => ({
+            key, frame, x: Math.round(x), y: Math.round(y),
+            ...(sizeMode === 'auto' ? {} : { w: Math.round(w), h: Math.round(h) }),
+            ...(sizeMode === 'manual' || sizeMode === 'device' ? { sizeMode } : {}),
+            ...(themeUser ? { themeUser } : {}),
+          })),
         }
         try {
           const res = await fetch(`${ROUTE}/api/boards/${boardName}`, {

package/src/client/shell/styles.css

@@ -178,6 +178,12 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   background-color: var(--head-bg); background-image: var(--head-sheen);
   backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
 .sh-node-head .id { font-weight: 600; color: var(--head-ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
+/* frame icons (SPEC-026 + feedback): every sidebar row leads with one */
+.sh-node-head .iicon { flex: none; color: var(--head-dim) }
+.sh-panel .sub .iicon { flex: none; margin-right: 7px; opacity: .72 }
+/* variant members sit visibly INSIDE their group: the letter chip starts
+   exactly on the parent rows' 51px text column (31 pad + 13 icon + 7 gap) */
+.sh-panel .sub.vrow { padding-left: 51px }
 .sh-node-head .dim { margin-left: auto; color: var(--head-dim); flex: none; font-variant-numeric: tabular-nums }
 .sh-node-body { position: relative; background: var(--node-bg); border-radius: 0 0 var(--r-node) var(--r-node); overflow: hidden }
 .sh-node iframe { border: 0; display: block }
@@ -564,7 +570,9 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
 
 /* sidebar variant rows: group header carries the experimentation mark; each variant
    row carries its letter CHIP (accent-filled when selected) + name (SPEC-023 §5) */
-.sub.vgroup { display: flex; align-items: center; gap: 8px }
+/* gap 0: the leading .iicon's margin-right carries the spacing, so the group
+   label lands on the SAME 51px text column as every sibling row */
+.sub.vgroup { display: flex; align-items: center; gap: 0 }
 .sub.vgroup .glabel { overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
 .sub.vgroup .gicon { margin-left: auto; flex: none; color: var(--glass-ink-3); transition: color .15s }
 .sub.vgroup:hover .gicon { color: var(--glass-ink) }

package/templates/AGENTS-embedded.md

@@ -15,9 +15,11 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | 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 |
+| Shape | thinking a feature through on canvas (specs, diagrams, mood boards) - never the first session | instructions/shape.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 |
+| Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board or publishing | instructions/boards.md |
 
@@ -59,6 +61,9 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   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.
+- CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
+  from the block primitives in '@marver-design/marver/content' - import them directly
+  in the frame file and declare meta.intent. Full guide: instructions/shape.md.
 
 ## Structure ladder (embedded mode: screens live in src/)
 1. First pass: write the whole page inline in the frame file. Diverge fast.

package/templates/AGENTS-studio.md

@@ -15,9 +15,11 @@ file in design/instructions/ - they are short, strict, and part of this contract
 | 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 |
+| Shape | thinking a feature through on canvas (specs, diagrams, mood boards) - never the first session | instructions/shape.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 |
+| Iterate | changing a frame the human has seen, or retiring explorations | instructions/iterate.md |
 | Review | before presenting anything | instructions/review.md |
 | Boards | creating a board or publishing | instructions/boards.md |
 
@@ -59,6 +61,9 @@ the routing index is at the top of instructions/craft.md. Pull ONE file, apply,
   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.
+- CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
+  from the block primitives in '@marver-design/marver/content' - import them directly
+  in the frame file and declare meta.intent. Full guide: instructions/shape.md.
 
 ## Structure ladder
 1. First pass: write the whole page inline in the frame file. Diverge fast.

package/templates/instructions/boards.md

@@ -25,6 +25,12 @@ viewport and lays it out:
 - 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.
+- Content frames (specs, diagrams, mood boards - instructions/shape.md) are ordinary
+  atoms in every layout scope: a feature-story board mixes them freely with UI frames.
+- The `archive` board (instructions/iterate.md) is the one board of retired
+  explorations: curated over design/scenes/archive/, tidied with a recipe,
+  every frame relabeled with what it was and why it retired. Winners live on
+  the feature boards; the archive answers "what did we try?".
 
 ## Composing the canvas: `layout`
 

package/templates/instructions/brand.md

@@ -39,7 +39,9 @@ token-level work once a direction exists.
    - glassmorphism as decoration, gradient text, Inter/Geist/Space Grotesk as the
      "safe" pick
    - emoji as icons, `rounded-lg` on everything, everything centered
-   (the complete tell catalog: reference/slop.md)
+   (the complete tell catalog: reference/slop.md; icons and real-asset rules:
+   craft.md "Real assets" - Phosphor is the default icon system when the repo
+   has none)
 4. **Settle it into tokens.** The winning direction becomes CSS custom properties in
    the theme (grounds, text tiers, accent + meaning, radius scale, spacing scale, two
    type roles minimum). Then write DESIGN.md as in Path A. Components consume tokens;

package/templates/instructions/craft.md

@@ -76,6 +76,55 @@ it on review passes.
 - Choosing light or dark by product category reflex - the use scene decides, or
   DESIGN.md already did.
 
+## Real assets - fetched, not faked
+
+The difference between a frame that feels alive and one that feels generated is
+usually the assets. Doing the work - finding, downloading, and wiring the real
+thing - changes everything. This section is binding, not aspiration:
+
+- **Icons come from a real icon system, Phosphor by default.** The app's existing
+  icon library always wins (consistency beats preference); when the repo has none,
+  install Phosphor (`@phosphor-icons/react` or the framework's equivalent) - that
+  is the house default and good taste. One weight throughout a design. Never emoji,
+  never unicode glyphs, never hand-drawn approximations of icons that exist.
+- **Real brands get their real logos.** An integrations row, a payment-methods
+  strip, a press bar, a testimonial card - fetch the ACTUAL marks (official brand
+  or press pages first; Simple Icons for product marks), download them into the
+  repo (the host's `public/` for app frames, `design/assets/` for content frames),
+  SVG preferred, respectful of clear space, checked in both themes. A gray box
+  labeled "Logo" is a defect, not a placeholder.
+- **Imagery is real imagery.** When the design calls for photos or screenshots,
+  fetch and commit them locally with names that say what they are - never
+  hotlink (published canvases make zero external requests, and remote URLs rot).
+- **Licensing sanity, briefly:** brand marks from official sources shown to
+  identify the brand are fine; photos come from sources that permit the use.
+  Unsure about one? Use it, and flag it to the human in the same message.
+
+## Interactive means visibly interactive - true to life
+
+The prototype is only believable if everything that would respond in the shipped
+product responds here. This is binding at EVERY fidelity (the lo-fi version is in
+instructions/wireframe.md); in play mode a hover-dead control reads as a broken
+app, and the human attributes the fault to your frame, not to a library.
+
+- **Every clickable target shows `cursor: pointer` and a visible hover state** -
+  buttons, dropdown triggers AND the options inside them, tabs, toggles, rows and
+  cards that navigate, icon buttons. If it responds to a click, it must respond to
+  a hover first.
+- **Component libraries do not guarantee this - audit them.** shadcn/ui on
+  Tailwind v4 notably ships buttons with the browser's `cursor: default`, and
+  menu/select items can lack a hover treatment depending on version. These are
+  design-system deficiencies, not reasons the rule bends.
+- **Fix gaps at the design-system level, never per-instance.** One base-layer rule
+  (e.g. `@layer base { button:not(:disabled), [role="button"]:not(:disabled)
+  { cursor: pointer } }` plus the library's own hover token on option items) beats
+  a hundred scattered `cursor-pointer` classes - and fixes the app, not just the
+  frame. When you find such a gap, patch the theme/base layer and tell the human
+  what the library got wrong.
+- **Sweep by hand once per design system:** render a frame, hover every KIND of
+  control it uses, and watch for the dead ones. The check is against the rendered
+  frame - a class in the source proves nothing about what the cascade delivered.
+
 ## Frame law
 
 - Frames are made of the app's real components and tokens. Rebuilding a lookalike of

package/templates/instructions/discover.md

@@ -51,8 +51,8 @@ an absent human; never hide that the brief was self-answered.
 ## 4. Align on flow with a diagram frame
 
 When the flow has branches or more than four screens, draw it before wireframing:
-one frame (`<scene>/flow.tsx`) of labeled boxes and arrows - plain divs and SVG lines,
-grayscale, no dependency. Each box names a future frame. The human can look at one
+one content frame (`<scene>/flow.tsx`) with a mermaid `Diagram` block - the how lives
+in instructions/shape.md. Each node names a future frame. The human can look at one
 picture and say "step 3 is wrong" before step 3 costs anything.
 
 Then move to Wireframe. Do not brand, do not pick type, do not open the craft rules

package/templates/instructions/iterate.md

@@ -0,0 +1,50 @@
+# Iterate - versions are nearly free, so keep them
+
+Read this when you are about to CHANGE a frame the human has already seen, or
+when a direction has won and it is time to clean up. The rule underneath
+everything: exploration is cheap here - never make the human lose a version
+they might want back.
+
+## Fork, don't overwrite
+
+- **Meaningful direction change on a seen frame → fork a variant.** Rename the
+  current file to `a-<direction>.tsx`, write the new take as `b-<direction>.tsx`
+  (nested dir when the scene is busy: `checkout/payment/a-card.tsx`). The
+  canvas badges them, keeps them together, and `[` `]` swaps them in place in
+  play mode - the human compares in seconds and nothing is lost.
+- **Successive iterations are variants too.** "v2 of the hero" is just another
+  letter: `c-tighter.tsx`. Simultaneous alternatives and successive versions
+  use the same mechanism - letters carry the order, names carry the idea.
+- **Polish in place** for small refinements (spacing, copy, states): git holds
+  the fine-grained history; letters are for DIRECTIONS, not typo fixes.
+- Name variants for the idea, never the sequence alone: `b-editorial.tsx`
+  beats `b-v2.tsx` - three weeks later, "editorial" still means something.
+
+## Keep the working set live
+
+Divergences stay on the board while a decision is open - visible, comparable,
+playable. Never silently delete an exploration the human has seen; the human
+decides what dies, you decide when to ask.
+
+## The cleanup ritual - when a path wins
+
+The human picks a direction; then, in one pass:
+
+1. **The winner takes the clean name.** Drop its letter prefix (or promote it
+   over the original file); update goto targets pointing at old ids.
+2. **The losers move to `design/scenes/archive/`** - never deleted, RELABELED:
+   filename `<feature>-<direction>.tsx`, meta.title saying exactly what it was
+   and why it retired, e.g.
+   `{ title: "Routines editor - guided steps (retired: sentence canvas won, sharper mental model)" }`.
+   A one-line comment at the top of the file carries any longer why. That
+   sentence is the learning - write it while the reason is fresh.
+3. **The `archive` board stays clean and organized:** a curated board over the
+   archive scene, tidied with a layout recipe, grouped by feature. Anyone
+   opening it should know what every frame was without asking.
+4. **The main boards show winners only.** A feature board after cleanup holds
+   the kept path; the archive holds the rest. In-between states are fine WHILE
+   deciding - the ritual is what ends them.
+
+Archived frames are history, not options: never link them from live flows,
+never count them as current design. They exist so "what did we try for the
+editor?" has a visual answer.