@marver-design/marver 0.8.0 → 0.9.0

package/src/client/shell/store.ts

@@ -1,6 +1,7 @@
 import { create } from 'zustand'
 import { ROUTE } from '../const.ts'
 import { tidy, parseLayout, type BoardLayout } from './tidy.ts'
+import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
 import shConfig from 'virtual:sh-config'
 // @ts-expect-error virtual module: null in dev; a published build inlines manifest+boards
@@ -26,14 +27,19 @@ 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
+  /** Size provenance for CONTENT frames, 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'
+  /** Transient (never serialized): this node was sized by the 390x844 GUESS because its
+   *  frame was not in the manifest yet AND its file carried no w/h (the create-first
+   *  choreography's append-before-scan race). applyManifest corrects ONLY these when the
+   *  frame arrives - an authored size on a temporarily-missing frame is never touched. */
+  sizeFallback?: boolean
   status: 'loading' | 'ready' | 'error'; error?: string; missing?: boolean
 }
-/** A Live Jam notification (SPEC-live-jam §9): a persistent bottom-right glass pill for a Marver
+/** A Live Jam notification: a persistent bottom-right glass pill for a Marver
  *  reply. Frame-first: the FRAME is the news (icon + title, blue), Marver + preview below. */
 export interface JamNote { threadId: string; board: string; preview: string; ts: number; frame?: string; frameTitle?: string; intent?: string }
 export interface Toast { id: number; text: string; jam?: JamNote }
@@ -58,6 +64,18 @@ export async function fetchBoardNames(): Promise<string[]> {
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
 export const boardLabel = (n: string) => humanize(n)
 
+/** The frames a board pins, straight from its file (dev fetch / published inline) -
+ *  membership only, never a load. Cross-board data-goto asks "which board shows this
+ *  frame?" without touching the live board state. */
+export async function boardFrames(name: string): Promise<string[]> {
+  const board: any = DATA
+    ? DATA.boards[name]
+    : (await (await fetch(`${ROUTE}/api/boards/${name}`)).json())?.board
+  return Array.isArray(board?.nodes)
+    ? board.nodes.map((n: any) => (n && typeof n.frame === 'string' ? n.frame : '')).filter(Boolean)
+    : []
+}
+
 const HEADER = 28
 let toastSeq = 0
 const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
@@ -85,12 +103,12 @@ 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. */
+/** Latest measured content heights, keyed frameId@width. TRANSIENT by design:
+ * 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
+  // content frames: 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) {
@@ -103,7 +121,7 @@ function defaultSize(frame: FrameEntry) {
 
 let resizedInGesture = false
 
-/** sceneRows is the legacy shorthand for a plain rows layout (SPEC-024 §5). */
+/** sceneRows is the legacy shorthand for a plain rows layout. */
 const effectiveLayout = (layout: BoardLayout | null, sceneRows: string[][] | null): BoardLayout | undefined =>
   layout ?? (sceneRows?.length ? { rows: sceneRows.map((r) => [...r]) } : undefined)
 
@@ -119,14 +137,14 @@ interface State {
   selection: string[]                 // ordered; last entry is the primary (bar anchor)
   interact: string | null
   viewTheme: string                   // the global theme preference; sticky across boards and reloads
-  play: { at: string; device: string; theme: string } | null   // play mode (SPEC-M2 §1); at = current frame id
+  play: { at: string; device: string; theme: string } | null   // play mode; at = current frame id
   gesture: boolean                    // a frame drag/resize is in progress - canvas panning is disabled
-  laser: boolean                      // laser/inspect mode (SPEC-M3 §7): frames outline their structure
+  laser: boolean                      // laser/inspect mode: frames outline their structure
   board: string                       // active board name; 'all-scenes' is the auto board
   boardAuto: boolean                  // auto boards gain new frames on arrival; curated boards never do
   deviceView: string | null           // board-wide device preview (viewport name), null = free-form layout
-  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
+  sceneRows: string[][] | null        // LEGACY scene arrangement; still round-trips through save
+  layout: BoardLayout | null          // lane-flow recipe, 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 (auto content entries carry positions only - their sizes are measured)
   panelOpen: boolean
@@ -175,7 +193,7 @@ interface State {
   jamToast(note: JamNote): void
   dismissToast(id: number): void
   clearJamToasts(): void
-  /** Frames Marver is editing right now (Live Jam presence, SPEC §10) - drives the working glow. */
+  /** Frames Marver is editing right now (Live Jam presence) - drives the working glow. */
   working: string[]
   /** When each working frame's job started (ms epoch) - phases the animations so parallel
    *  frames never pulse in sync. */
@@ -203,7 +221,7 @@ 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.
+  // 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
@@ -237,7 +255,7 @@ export const useStore = create<State>((set, get) => {
     },
   }
 
-  /** Published parity for content-frame sizes (SPEC-026): manual/device sizes persist
+  /** Published parity for content-frame sizes: 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
@@ -305,19 +323,26 @@ export const useStore = create<State>((set, get) => {
         boardHash = sha256
         if (typeof board?.auto === 'boolean') boardAuto = board.auto
         // Agent-authored boards may be just a frame list - fill sizes/keys, tidy on first load.
-        // Keys are load-bearing (iframe identity, selection) - dupes/blanks get reminted.
-        // Board nodes whose file is gone stay, flagged - deletion is surfaced, never silent (spec §7).
+        // Keys are load-bearing (iframe identity, selection, COMMENT ANCHORS) - dupes/blanks
+        // get minted DETERMINISTICALLY (keys.ts): a random key here orphaned every comment
+        // created on a never-saved board the moment it reloaded.
+        // Board nodes whose file is gone stay, flagged - deletion is surfaced, never silent.
         const seenKeys = new Set<string>()
+        const ordinals = new Map<string, number>()   // per-frame keyless-occurrence counter
         nodes = (Array.isArray(board?.nodes) ? board.nodes : [])
           .filter((n: any) => n && typeof n.frame === 'string')
           .map((n: any) => {
             const f = manifest.frames.find((x) => x.id === n.frame)
             const d = f ? defaultSize(f) : { w: 390, h: 844 }
             if (typeof n.x !== 'number' || typeof n.y !== 'number') needTidy = true
-            let key = typeof n.key === 'string' && n.key ? n.key : nodeKey()
-            if (seenKeys.has(key)) key = nodeKey()
+            let key = typeof n.key === 'string' && n.key ? n.key : ''
+            if (!key || seenKeys.has(key)) {
+              let salt = ordinals.get(n.frame) ?? 0
+              do { key = stableNodeKey(boardName, n.frame, salt++) } while (seenKeys.has(key))
+              ordinals.set(n.frame, salt)
+            }
             seenKeys.add(key)
-            // content-frame size provenance round-trips (SPEC-026); auto nodes saved no
+            // content-frame size provenance round-trips; 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'] }
@@ -327,6 +352,7 @@ export const useStore = create<State>((set, get) => {
               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,
+              ...(!f && typeof n.w !== 'number' && typeof n.h !== 'number' ? { sizeFallback: true } : {}),
               ...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
@@ -357,7 +383,7 @@ export const useStore = create<State>((set, get) => {
         if (board?.baseLayout && typeof board.baseLayout === 'object') baseLayout = board.baseLayout
       }
       // auto-managed goes both ways (friction log #15): an auto board gains new frames
-      // AND sheds deleted ones. Tombstone cards are a curated-board concept (spec §7).
+      // AND sheds deleted ones. Tombstone cards are a curated-board concept.
       // Pruning at load DIRTIES the board (dev only) so the file on disk sheds the
       // tombstones too - otherwise a recreated frame id resurrects its stale node.
       let prunedAtLoad = false
@@ -373,6 +399,15 @@ export const useStore = create<State>((set, get) => {
       // saved piled up at the origin)
       if (boardAuto) {
         const placed = new Set(nodes.map((n) => n.frame))
+        // newcomers get deterministic keys too - on published auto boards (all-scenes)
+        // this path mints EVERY key, every visit, and comments anchor to them
+        const haveKeys = new Set(nodes.map((n) => n.key))
+        const mint = (frame: string) => {
+          let salt = 0, k = stableNodeKey(boardName, frame, salt)
+          while (haveKeys.has(k)) k = stableNodeKey(boardName, frame, ++salt)
+          haveKeys.add(k)
+          return k
+        }
         let maxX = nodes.reduce((a, n) => Math.max(a, n.x + n.w), 0)
         for (const f of manifest.frames) {
           if (placed.has(f.id)) continue
@@ -387,7 +422,7 @@ 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', ...(f.contentWidth ? { sizeMode: (vp ? 'device' : 'auto') as Node['sizeMode'] } : {}) }
+          const node: Node = { key: mint(f.id), 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)
         }
@@ -497,15 +532,23 @@ export const useStore = create<State>((set, get) => {
         const d = defaultSize(f)
         const maxY = next.reduce((a, n) => Math.max(a, n.y + n.h), 0)
         // a grouped newcomer lands BESIDE its siblings, not at the canvas bottom - the
-        // badge/caption say "these belong together"; the position must agree (SPEC-023 §3)
+        // badge/caption say "these belong together"; the position must agree
         const sibs = f.variantGroup
           ? 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'] } : {}
+        // deterministic key (keys.ts): a comment dropped on a live-joined frame must
+        // survive the reload, where the SAME key gets minted by the board-load path
+        const mintKey = (() => {
+          const have = new Set(next.map((n) => n.key))
+          let salt = 0, k = stableNodeKey(get().board, f.id, salt)
+          while (have.has(k)) k = stableNodeKey(get().board, f.id, ++salt)
+          return k
+        })()
         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, ...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 }
+          ? { key: mintKey, 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: mintKey, 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 } }
@@ -516,7 +559,21 @@ export const useStore = create<State>((set, get) => {
       let retinted = false
       for (const n of next) {
         const missing = !live.has(n.frame)
-        if (missing !== !!n.missing) { n.missing = missing; changed = true }
+        if (missing !== !!n.missing) {
+          // a node whose frame just ARRIVED (the create-first choreography: the agent
+          // appends the board node before the manifest registers the file) was sized by
+          // the 390x844 GUESS - its real viewport is only knowable now. ONLY guessed
+          // sizes are corrected (sizeFallback): a restored frame keeps its authored w/h.
+          const arrived = !missing && m.frames.find((x) => x.id === n.frame)
+          if (arrived && n.sizeFallback && !arrived.contentWidth) {
+            const d = defaultSize(arrived)
+            n.w = vp?.width ?? d.w
+            n.h = vp?.height ?? d.h
+          }
+          if (arrived) delete n.sizeFallback
+          n.missing = missing
+          changed = true
+        }
         // a frame's declared meta.theme may have changed - re-resolve unpinned nodes
         // (derived value: re-render yes, dirty/save no)
         const f = m.frames.find((x) => x.id === n.frame)
@@ -533,7 +590,7 @@ export const useStore = create<State>((set, get) => {
         if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; retinted = true }
       }
       // auto boards prune deleted frames outright - "auto-managed" must manage both
-      // directions (friction log #15). Curated boards keep the explicit card (spec §7).
+      // directions (friction log #15). Curated boards keep the explicit card.
       let final = next
       if (boardAuto) {
         final = next.filter((n) => !n.missing)
@@ -594,7 +651,7 @@ 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)
+        // a human-resized CONTENT frame goes 'manual': measurements never overwrite it
         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, ...(content ? { sizeMode: 'manual' as const } : {}) } : n)),
@@ -610,7 +667,7 @@ export const useStore = create<State>((set, get) => {
       if (!inGesture) scheduleSave()
     },
 
-    /** SPEC-026 sh:measure. Admission: content frames only, finite positive numbers,
+    /** 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). */
@@ -619,7 +676,7 @@ export const useStore = create<State>((set, get) => {
       const node = s.nodes.find((n) => n.key === key)
       // Only an explicit DEVICE viewport locks a content frame's height. 'auto' and 'manual' both
       // auto-fit height: a content frame must always grow/shrink to show ALL its content, even after
-      // the human drags its WIDTH (SPEC-026 r4). 'manual' just means the human owns the WIDTH; the
+      // the human drags its WIDTH. 'manual' just means the human owns the WIDTH; the
       // HEIGHT is still measured, so resizing width reflows and refits height (no clipped/empty frame).
       if (!node || node.sizeMode === 'device') return
       if (node.frame !== frameId) return                  // generation guard: a reused node key
@@ -669,7 +726,7 @@ export const useStore = create<State>((set, get) => {
           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)
+          // digit 0 on a CONTENT frame = back to auto: measured size, remeasure ahead
           const b = s.baseLayout?.[n.key]
           if (content && f) {
             const d = defaultSize(f)
@@ -714,7 +771,7 @@ export const useStore = create<State>((set, get) => {
           if (vp) return { ...n, w: vp.width, h: vp.height, ...(content ? { sizeMode: 'device' as const } : {}) }
           if (!f) return n
           const d = defaultSize(f)
-          // digit 0 on a content frame clears provenance back to auto (SPEC-026)
+          // digit 0 on a content frame clears provenance back to auto
           return { ...n, w: d.w, h: d.h, ...(content ? { sizeMode: 'auto' as const } : {}) }
         })
         const baseLayout = s.baseLayout ? { ...s.baseLayout } : null
@@ -729,7 +786,7 @@ export const useStore = create<State>((set, get) => {
     selectAll() {
       set((s) => ({ selection: s.nodes.map((n) => n.key) }))
     },
-    // group/scene selection from sidebar rows and canvas captions (SPEC-023 feedback)
+    // group/scene selection from sidebar rows and canvas captions
     selectMany(keys) {
       set((s) => {
         const valid = keys.filter((k) => s.nodes.some((n) => n.key === k))
@@ -757,7 +814,7 @@ export const useStore = create<State>((set, get) => {
     },
     setGesture(gesture) {
       set({ gesture })
-      // SPEC-024 §4: a board WITH a layout recipe re-applies it when a resize
+      // A board WITH a layout recipe re-applies it when a resize
       // gesture ends - sizes changed, so lanes and gaps must recompute
       if (!gesture && resizedInGesture) {
         resizedInGesture = false
@@ -883,7 +940,7 @@ export const useStore = create<State>((set, get) => {
       // a resize gesture in flight = torn state (new sizes, pre-recipe positions):
       // even a PREVIOUSLY scheduled timer must defer to the gesture-end save
       if (get().gesture && resizedInGesture) { scheduleSave(); return Promise.resolve(false) }
-      // a published canvas is read-only ON DISK (spec §12): theme pins persist to the
+      // a published canvas is read-only ON DISK: theme pins persist to the
       // session instead, and dirty must clear or switchBoard's save-flush loop wedges
       if (DATA) {
         sessionPins.write(get().board, get().nodes)
@@ -894,11 +951,11 @@ export const useStore = create<State>((set, get) => {
       const p = saveChain.then(async () => {
         // recheck INSIDE the serialized chain: a save queued behind an in-flight PUT
         // may only execute after a resize gesture began - the entry guard above ran
-        // too early to see it (codex probe: torn PUT #2 behind blocked PUT #1)
+        // too early to see it (torn PUT #2 behind blocked PUT #1)
         if (get().gesture && resizedInGesture) { scheduleSave(); return false }
         const rev = editRev
         const { nodes, boardHash, deviceView, baseLayout, board: boardName, boardAuto } = get()
-        // Missing nodes persist too - only the explicit remove button drops them (spec §7).
+        // Missing nodes persist too - only the explicit remove button drops them.
         const board = {
           version: 1, name: boardName, auto: boardAuto,
           // deviceView and the free-form snapshot persist independently: a scoped
@@ -907,7 +964,7 @@ export const useStore = create<State>((set, get) => {
           ...(get().sceneRows?.length ? { sceneRows: get().sceneRows } : {}),
           ...(get().layoutRaw !== undefined ? { layout: get().layoutRaw } : {}),
           // baseLayout entries for auto content nodes keep POSITIONS only - their
-          // measured dimensions are transient and never reach the file (SPEC-026)
+          // measured dimensions are transient and never reach the file
           ...(baseLayout ? {
             baseLayout: Object.fromEntries(Object.entries(baseLayout).map(([k, b]) => {
               const n = nodes.find((x) => x.key === k)
@@ -915,11 +972,14 @@ export const useStore = create<State>((set, get) => {
             })),
           } : {}),
           // only PINNED themes persist - inherited values follow viewTheme at load time.
-          // Content frames in AUTO save no dimensions (SPEC-026): measured sizes are
+          // Content frames in AUTO save no dimensions: 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 }) => ({
+          // Guessed sizes (sizeFallback: the frame was not in the manifest yet) stay
+          // transient too - persisting the 390x844 guess would make it look authored
+          // and immortalize it across reloads.
+          nodes: nodes.map(({ key, frame, x, y, w, h, themeUser, sizeMode, sizeFallback }) => ({
             key, frame, x: Math.round(x), y: Math.round(y),
-            ...(sizeMode === 'auto' ? {} : { w: Math.round(w), h: Math.round(h) }),
+            ...(sizeMode === 'auto' || sizeFallback ? {} : { w: Math.round(w), h: Math.round(h) }),
             ...(sizeMode === 'manual' || sizeMode === 'device' ? { sizeMode } : {}),
             ...(themeUser ? { themeUser } : {}),
           })),

package/src/client/shell/styles.css

@@ -28,9 +28,9 @@
   --interact: #db35f2; --interact-ring: rgba(219, 53, 242, .16);
   --interact-strong: rgba(219, 53, 242, 1); --interact-soft: rgba(234, 141, 255, .95);
   --interact-deep: rgba(176, 47, 194, .85); --interact-spark: rgba(255, 255, 255, .95);
-  /* comments own a third mode color (Apple systemGreen): selection = blue,
-     interact = purple, comments = green - same geometry, unique hue per mode */
-  --comment: #34c759; --comment-ring: rgba(52, 199, 89, .22);
+  /* comments ride the brand blue: interact keeps purple, and a pin, a thread card
+     and a selected frame are told apart by shape, not by hue */
+  --comment: #0088ff; --comment-ring: rgba(0, 136, 255, .22);
   /* comment-card field surface: APP-scoped on purpose - the card keys to the board
      theme, and node-scoped --node-bg would flip with the frame underneath it */
   --cm-field: #fff;
@@ -67,7 +67,7 @@
   --interact: #ea8dff; --interact-ring: rgba(219, 53, 242, .3);
   --interact-strong: rgba(219, 53, 242, 1); --interact-soft: rgba(234, 141, 255, .95);
   --interact-deep: rgba(203, 48, 224, .8); --interact-spark: rgba(255, 255, 255, .9);
-  --comment: #30d158; --comment-ring: rgba(48, 209, 88, .34);
+  --comment: #4da6ff; --comment-ring: rgba(77, 166, 255, .34);
   --cm-field: #0f1015;
   --cm-modal-bg: rgba(22, 22, 27, .96);
 
@@ -157,7 +157,7 @@ button svg { pointer-events: none }   /* event targets stay on the button - pan
 #sh-world.sh-preset .sh-node-body,
 #sh-world.sh-preset .sh-node .sh-live { transition: width .32s cubic-bezier(.25,.46,.45,.94),
   height .32s cubic-bezier(.25,.46,.45,.94) }
-/* SPEC-M5 device-sweep: a frame WITH a ready lean cover jumps its LIVE iframe straight to the final
+/* Device-sweep: a frame WITH a ready lean cover jumps its LIVE iframe straight to the final
    width (ONE reflow, hidden under the cover) while the lean cover - being width:100% of the animating
    body - reflows smoothly every frame (real CSS, the device-sweep fix). A frame WITHOUT a usable
    cover keeps the live width animation above. */
@@ -200,7 +200,7 @@ 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 */
+/* frame icons: 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
@@ -209,7 +209,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .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 }
-/* SPEC-M5 LEAN-PRIMARY: the lean DOM-snapshot <iframe> (static html, 0 JS) is what you SEE for a
+/* LEAN-PRIMARY: the lean DOM-snapshot <iframe> (static html, 0 JS) is what you SEE for a
    passive frame - at rest AND during pan/zoom/resize. There is NO per-gesture swap between the lean
    and the live iframe (the swap shifted text ~1-2px = "jiggle", and flashed mermaid/theme colors,
    because two documents never render pixel-identically). The live app (.sh-live) sits underneath and
@@ -290,8 +290,8 @@ body.sh-commenting .sh-lean { opacity: 0 }
   .sh-node.interact::before, .sh-node.interact::after,
   .sh-node.working::before { animation: none } }
 
-/* Live Jam "working" (SPEC §10): the SELECTED state's exact geometry - crisp border + 2px screen-px
-   outline + 4px ring, edge-light off - in MARVER BLUE (Nic's pick over yellow), composed of three
+/* Live Jam "working": the SELECTED state's exact geometry - crisp border + 2px screen-px
+   outline + 4px ring, edge-light off - in MARVER BLUE, composed of three
    layers: the border shimmer (::before orbit), the periodic content WAVE (.sh-work-wave), and the
    shimmer MATRIX of tiny marks on the left flank (.sh-work-ind). Every animated layer is phased by
    --mv-w0 (negative ms since THIS frame's job started), so parallel frames never pulse in sync.
@@ -566,7 +566,7 @@ body.sh-commenting .sh-lean { opacity: 0 }
   transition: color .15s, background .15s }
 .sh-update .x:hover { background: var(--glass-hover); color: var(--glass-ink) }
 
-/* bottom-RIGHT now (SPEC-live-jam §9): jam reply pills live here; plain toasts ride along */
+/* bottom-RIGHT now: jam reply pills live here; plain toasts ride along */
 .sh-toasts { position: absolute; right: var(--edge); bottom: var(--edge); z-index: 32; display: flex;
   flex-direction: column; align-items: flex-end; gap: 8px; max-width: min(360px, 40vw) }
 .sh-toast { display: flex; align-items: center; gap: 6px; font: 500 12px -apple-system, system-ui, sans-serif;
@@ -624,7 +624,7 @@ body.sh-commenting .sh-lean { opacity: 0 }
   border: 0; border-radius: 50%; background: none; color: var(--glass-ink-3); cursor: pointer; transition: background .12s, color .12s }
 .sh-jam-x:hover { background: var(--glass-hover); color: var(--glass-ink) }
 
-/* ---- Play mode (SPEC-M2 §1): near-black stage, one centered device, auto-hiding bar.
+/* ---- Play mode: near-black stage, one centered device, auto-hiding bar.
    Fixed dark palette - the backdrop never follows the board theme, so no tokens here. */
 .sh-play { position: absolute; inset: 0; z-index: 30; background: #0a0a0b; display: flex;
   align-items: center; justify-content: center; animation: sh-play-in .28s ease-out; cursor: auto }
@@ -724,8 +724,8 @@ body.sh-commenting .sh-lean { opacity: 0 }
 .sh-app :focus { outline: none }
 body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-offset: -2px }
 
-/* ---- Variant groups (SPEC-023 §4): badge left of grouped frames + group caption.
-   Both live in WORLD space (scale with the canvas, per Nic's ask) with a screen-space
+/* ---- Variant groups: badge left of grouped frames + group caption.
+   Both live in WORLD space (scale with the canvas) with a screen-space
    minimum via --sh-inv, the resize-handle trick - legible at overview zoom, proportionate
    up close. Colors are on-canvas ink (the dot-grid's world), not chrome glass. */
 /* gap to the frame is ~12px screen at working zooms, capped at 40 world px far out:
@@ -761,7 +761,7 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
 .sh-app.dark .sh-gcaption { color: rgba(245, 245, 247, .45) }
 
 /* sidebar variant rows: group header carries the experimentation mark; each variant
-   row carries its letter CHIP (accent-filled when selected) + name (SPEC-023 §5) */
+   row carries its letter CHIP (accent-filled when selected) + name */
 /* 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 }
@@ -779,7 +779,7 @@ body.sh-kbd .sh-app :focus-visible { outline: 2px solid var(--accent); outline-o
 .sub .chip:hover { color: var(--glass-ink); background: var(--glass-hover) }
 .sub .chip.on { color: #fff; background: var(--accent); border-color: var(--accent) }
 
-/* play-mode variant chips (SPEC-023 §6): the SAME badge language as the sidebar's
+/* play-mode variant chips: the SAME badge language as the sidebar's
    variant rows (20px, 7px-radius square, one consistent shape in every state) so the
    two surfaces read as one concept - but in the pill's own dark-glass inks, never
    theme tokens (the nav is always dark; theme ink goes invisible in light mode). */
@@ -877,7 +877,7 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 .sub.vgroup.held { background: color-mix(in srgb, var(--glass-hover) 55%, transparent) }
 .sub.vgroup.held .gicon { color: var(--glass-ink-2) }
 
-/* ---- comments (SPEC-M3 §6) ----------------------------------------------------------
+/* ---- comments ----------------------------------------------------------
    The marker family (pins, stacks) is SOLID with the Figma teardrop silhouette - a
    marker must hold contrast on any artwork. The surfaces (card, composer, dialog)
    are OUR glass - the shell's own token language, theme-aware where Figma is flat. */

package/src/client/shell/tidy.ts

@@ -1,7 +1,7 @@
 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 }
 
-// SPEC-024 lane-flow grammar: one shape at both scopes. A scope is rows XOR columns
+// 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 }
@@ -14,7 +14,7 @@ const isSpace = (x: unknown): x is Space => !!x && typeof x === 'object' && !Arr
 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,
+// Adaptive units: 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)
@@ -251,7 +251,7 @@ function layoutScene(scene: string, members: TidyNode[], flow: Flow | undefined,
 }
 
 /**
- * Pure layout (spec §7 + SPEC-023 + SPEC-024). Returns positions only - the nodes
+ * Pure layout. 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.
  */
@@ -272,7 +272,7 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
   }
 
   // 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)
+  // PLAIN tidy (default trailing lanes), never a silent pick
   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 }
@@ -307,7 +307,7 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
   return out
 }
 
-/** Guarded parse of agent-authored board.layout (SPEC-024 §1). Malformed pieces warn
+/** Guarded parse of agent-authored board.layout. 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

package/src/client/stage/main.tsx

@@ -1,5 +1,5 @@
 /**
- * The stage - play mode's single mount (SPEC-M2 §1). Unlike the frame host (one iframe
+ * The stage - play mode's single mount. 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;
@@ -174,7 +174,7 @@ function Stage() {
   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)
+  // that differs at depth k legitimately remounts everything below
   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)

package/src/shared/events.ts

@@ -1,5 +1,5 @@
 /**
- * Comment events - the PURE half of the store (SPEC-M3 §1), shared by the node side
+ * Comment events - the PURE half of the store, shared by the node side
  * (JSONL persistence in server/comments.ts) and the browser shell (thread state from
  * fetched events). No node imports here, ever.
  */
@@ -19,7 +19,7 @@ export interface CommentEvent {
   board?: string
   nodeKey?: string                // a frame can sit on a board twice - comments are node-scoped
   frame?: string
-  anchor?: unknown                // SPEC-M3 §5 bundle; absent = frame-level comment; on 'reanchor' = the new anchor
+  anchor?: unknown                // anchor bundle; absent = frame-level comment; on 'reanchor' = the new anchor
   author?: { email: string; name?: string; avatar?: string }
   body?: string                   // plain text in v1
   emoji?: string                  // react events

package/src/shared/utm.ts

@@ -0,0 +1,22 @@
+/** Automatic attribution for the powered-by links: every canvas tags its marver.design
+ *  link so site analytics can see WHICH canvas sent a visitor - zero user setup.
+ *  Conventional UTM semantics (stable groupings first, the variable last):
+ *    utm_source   = the surface class ('published-canvas' | 'dev-canvas')
+ *    utm_medium   = the link unit ('powered-by')
+ *    utm_campaign = THIS canvas's name, slugged ("Marver tour" -> "marver-tour")
+ *    utm_content  = the placement ('gate' badge | 'shell' wordmark)
+ */
+export function poweredByUrl(
+  canvasName: string | undefined,
+  source: 'published-canvas' | 'dev-canvas',
+  content: 'gate' | 'shell',
+): string {
+  const slug = (canvasName ?? '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  const q = new URLSearchParams({
+    utm_source: source,
+    utm_medium: 'powered-by',
+    ...(slug ? { utm_campaign: slug } : {}),
+    utm_content: content,
+  })
+  return `https://marver.design/?${q.toString()}`
+}