@marver-design/marver 0.2.2 → 0.2.4

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

@@ -90,6 +90,42 @@ export const canvasCtl = {
   zoom100() { canvasCtl.zoomTo(1) },
 }
 
+/** Variant-group captions (SPEC-023 §4): "Landing · 3 variants" above each group with
+ *  2+ members on this board. World-space (scales with the canvas); min screen size via
+ *  --sh-inv. Groups with one lone member on a curated board keep the badge, no caption. */
+function GroupCaptions() {
+  const nodes = useStore((s) => s.nodes)
+  const manifest = useStore((s) => s.manifest)
+  const selection = useStore((s) => s.selection)
+  if (!manifest) return null
+  const byId = new Map(manifest.frames.map((f) => [f.id, f]))   // O(F+N), not O(F*N) per drag
+  const groups = new Map<string, { x: number; y: number; ids: Set<string>; keys: string[] }>()
+  for (const n of nodes) {
+    if (n.missing) continue
+    const f = byId.get(n.frame)
+    if (!f?.variantGroup) continue
+    const g = groups.get(f.variantGroup)
+    if (!g) groups.set(f.variantGroup, { x: n.x, y: n.y, ids: new Set([n.frame]), keys: [n.key] })
+    else { g.x = Math.min(g.x, n.x); g.y = Math.min(g.y, n.y); g.ids.add(n.frame); g.keys.push(n.key) }
+  }
+  return (
+    <>
+      {[...groups.entries()].filter(([, g]) => g.ids.size > 1).map(([id, g]) => {
+        const allOn = g.keys.every((k) => selection.includes(k))
+        return (
+          <div key={id} className={`sh-gcaption sh-no-pan${allOn ? ' on' : ''}`}
+            style={{ transform: `translate(${g.x}px, ${g.y}px) translateY(calc(-100% - clamp(4px, 8px * var(--sh-inv, 1), 40px)))` }}
+            title="Select all variants"
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => { useStore.getState().selectMany(g.keys); canvasCtl.fitNodes(g.keys) }}>
+            {id.split('/').map((s) => s[0].toUpperCase() + s.slice(1)).join(' / ')} · {g.ids.size} variants
+          </div>
+        )
+      })}
+    </>
+  )
+}
+
 export function Canvas() {
   const nodes = useStore((s) => s.nodes)
   const gesture = useStore((s) => s.gesture)
@@ -119,18 +155,28 @@ export function Canvas() {
       }
       ref.current.setTransform(px - x * scale, py - y * scale, scale, 320, 'easeOut')
     }
-    canvasCtl.fitNode = (key: string) => {
-      const n = useStore.getState().nodes.find((x) => x.key === key)
-      if (n) fitRect(n.x, n.y, n.w, n.h + HEADER, true)
-    }
     const fitKeys = (keys: string[], focus: boolean) => {
+      const st = useStore.getState()
       const sel = new Set(keys)
-      const ns = useStore.getState().nodes.filter((n) => sel.has(n.key))
+      const ns = st.nodes.filter((n) => sel.has(n.key))
       if (!ns.length) return
-      const x0 = Math.min(...ns.map((n) => n.x)), y0 = Math.min(...ns.map((n) => n.y))
+      let x0 = Math.min(...ns.map((n) => n.x)), y0 = Math.min(...ns.map((n) => n.y))
       const x1 = Math.max(...ns.map((n) => n.x + n.w)), y1 = Math.max(...ns.map((n) => n.y + n.h + HEADER))
+      // grouped frames carry chrome OUTSIDE their box (badge left, caption above) -
+      // fit must include that envelope or the variant text lands under the sidebar.
+      // Screen-clamped sizes need a scale estimate first: one pre-pass, then pad.
+      if (ns.some((n) => st.frameFor(n)?.variantGroup)) {
+        const el = wrap()
+        if (el) {
+          const p = insets(el)
+          const s1 = Math.max(0.05, Math.min(1, (el.clientWidth - p.left - p.right) / (x1 - x0), (el.clientHeight - p.top - p.bottom) / (y1 - y0)))
+          x0 -= Math.max(140, 44 / s1)   // badge letter+name column (min 44 screen px)
+          y0 -= Math.max(64, 36 / s1)    // caption line above the group
+        }
+      }
       fitRect(x0, y0, x1 - x0, y1 - y0, focus)
     }
+    canvasCtl.fitNode = (key: string) => fitKeys([key], true)
     canvasCtl.fitNodes = (keys: string[]) => fitKeys(keys, true)
     canvasCtl.fitAll = () => fitKeys(useStore.getState().nodes.map((n) => n.key), false)
     canvasCtl.zoomTo = (target: number) => {
@@ -177,7 +223,7 @@ export function Canvas() {
     if (!el) return
     const down = (e: PointerEvent) => {
       const t = e.target as HTMLElement | null
-      if (t?.closest('.sh-node')) return
+      if (t?.closest('.sh-node') || t?.closest('.sh-gcaption')) return
       const s = useStore.getState()
       if (s.selection.length || s.interact) s.select(null)
     }
@@ -277,6 +323,7 @@ export function Canvas() {
     >
       <TransformComponent wrapperClass="sh-canvas" contentClass="sh-content">
         <div id="sh-world">
+          <GroupCaptions />
           {nodes.map((n) => <FrameNode key={n.key} node={n} />)}
         </div>
       </TransformComponent>

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

@@ -1,5 +1,5 @@
 import { memo, useEffect, useRef } from 'react'
-import { frameUrl, useStore, CONFIG, type Node } from '../store.ts'
+import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, ReloadIcon, XIcon } from '../icons.tsx'
 
 export const HEADER = 28
@@ -148,6 +148,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     )
   }
 
+  // variant badge (SPEC-023 §4): letter + name floating LEFT of the frame, outside the
+  // artwork, world-anchored (scales with zoom) with a screen-space minimum via --sh-inv
+  const variantName = frame.title
+    ?? cap((frame.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' '))
+
   return (
     <div
       className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}`}
@@ -155,6 +160,14 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER }}
       data-node={node.key}
     >
+      {frame.variantGroup && (
+        <div className="sh-vbadge sh-no-pan" title={`${frame.variantGroup} · variant ${frame.variant?.toUpperCase()} - click to select`}
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => { select(node.key, e.shiftKey) }}>
+          <b>{frame.variant?.toUpperCase()}</b>
+          <span>{variantName}</span>
+        </div>
+      )}
       <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')} title={frame.file}>
         <span className="id sh-no-pan">{frame.title ?? frame.id}</span>
         <span className="dim sh-no-pan">{Math.round(node.w)} · {node.theme}</span>

package/src/client/shell/icons.tsx

@@ -44,6 +44,8 @@ export const CardsThreeIcon = icon(<path d="M208,88H48a16,16,0,0,0-16,16v96a16,1
 export const FrameCornersIcon = icon(<path d="M160 48h40a8 8 0 0 1 8 8v40M208 160v40a8 8 0 0 1-8 8h-40M96 208H56a8 8 0 0 1-8-8v-40M48 96V56a8 8 0 0 1 8-8h40" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" />)
 export const ArrowLeftIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H59.31l58.35,58.34a8,8,0,0,1-11.32,11.32l-72-72a8,8,0,0,1,0-11.32l72-72a8,8,0,0,1,11.32,11.32L59.31,120H216A8,8,0,0,1,224,128Z" />)
 export const ArrowRightIcon = icon(<path d="M221.66,133.66l-72,72a8,8,0,0,1-11.32-11.32L196.69,136H40a8,8,0,0,1,0-16H196.69L138.34,61.66a8,8,0,0,1,11.32-11.32l72,72A8,8,0,0,1,221.66,133.66Z" />)
+/** Variants/experimentation mark: the flask (Phosphor). */
+export const VariantsIcon = icon(<path d="M223.45,208.19,168,101.11V40h8a8,8,0,0,0,0-16H80a8,8,0,0,0,0,16h8v61.11L32.55,208.19A16,16,0,0,0,46.86,232H209.14a16,16,0,0,0,14.31-23.81ZM102.13,108.5A8,8,0,0,0,104,103.35V40h48v63.35a8,8,0,0,0,1.87,5.15L179.36,157c-11.71,2.87-26.5.66-44.16-6.64-14.08-5.82-27.34-8.53-39.66-8.16ZM46.86,216,84.36,143.6c11.68-2.9,26.47-.68,44.13,6.61,13.09,5.42,25.36,8.11,36.65,8.11a67.86,67.86,0,0,0,22.53-3.72L209.14,216Z" />)
 export const CardsIcon = icon(<path d="M184,72H40A16,16,0,0,0,24,88V200a16,16,0,0,0,16,16H184a16,16,0,0,0,16-16V88A16,16,0,0,0,184,72Zm0,128H40V88H184V200ZM232,56V176a8,8,0,0,1-16,0V56H64a8,8,0,0,1,0-16H216A16,16,0,0,1,232,56Z" />)
 /** Viewport-name -> device glyph; unknown custom names fall back to the generic Devices. */
 export function deviceIcon(name: string | null, size = 14) {

package/src/client/shell/store.ts

@@ -1,6 +1,6 @@
 import { create } from 'zustand'
 import { ROUTE } from '../const.ts'
-import { tidy } from './tidy.ts'
+import { tidy, parseLayout, type BoardLayout } from './tidy.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
@@ -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 }
+export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
@@ -76,6 +76,18 @@ function defaultSize(frame: FrameEntry) {
   return { w: vp.width, h: vp.height }
 }
 
+let resizedInGesture = false
+
+/** sceneRows is the legacy shorthand for a plain rows layout (SPEC-024 §5). */
+const effectiveLayout = (layout: BoardLayout | null, sceneRows: string[][] | null): BoardLayout | undefined =>
+  layout ?? (sceneRows?.length ? { rows: sceneRows.map((r) => [...r]) } : undefined)
+
+const layoutWarn = (msg: string) => {
+  console.warn('[marver layout]', msg)
+  try { useStore.getState().toast(`layout: ${msg}`) } catch { /* store not ready during boot */ }
+}
+
+
 interface State {
   manifest: Manifest | null
   nodes: Node[]                       // append-only order; NEVER sorted or reordered (iframe law G-1)
@@ -87,6 +99,9 @@ interface State {
   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
+  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
   panelOpen: boolean
   scale: number
@@ -102,6 +117,7 @@ interface State {
   setStatus(key: string, status: Node['status'], error?: string): void
   removeNode(key: string): void
   select(key: string | null, additive?: boolean): void
+  selectMany(keys: string[]): void
   selectAll(): void
   setInteract(key: string | null): void
   setPlay(p: State['play']): void
@@ -170,6 +186,9 @@ export const useStore = create<State>((set, get) => {
       let boardHash: string | null = null
       let boardAuto = boardName === 'all-scenes'
       let deviceView: string | null = null
+      let sceneRows: string[][] | null = null
+      let layout: BoardLayout | null = null
+      let layoutRaw: unknown = undefined
       let baseLayout: State['baseLayout'] = null
       let needTidy = false
       // published build: boards come from the inlined data; absent = fresh (the 404 path)
@@ -224,6 +243,15 @@ export const useStore = create<State>((set, get) => {
         // device view and the free-form snapshot survive reloads - independently:
         // a scoped "exception" clears deviceView but the snapshot must keep restoring
         if (typeof board?.deviceView === 'string' && CONFIG.viewports[board.deviceView]) deviceView = board.deviceView
+        if (Array.isArray(board?.sceneRows)) {
+          const rows = board.sceneRows
+            .map((r: unknown) => (Array.isArray(r) ? r.filter((x: unknown) => typeof x === 'string') : []))
+            .filter((r: string[]) => r.length)
+          if (rows.length) sceneRows = rows
+        }
+        layoutRaw = board?.layout
+        layout = parseLayout(board?.layout, layoutWarn)
+        if (layout && sceneRows) layoutWarn('board has layout AND sceneRows - layout wins')
         if (board?.baseLayout && typeof board.baseLayout === 'object') baseLayout = board.baseLayout
       }
       // auto-managed goes both ways (friction log #15): an auto board gains new frames
@@ -236,15 +264,30 @@ export const useStore = create<State>((set, get) => {
         nodes = nodes.filter((n) => !n.missing)
         prunedAtLoad = !DATA && nodes.length !== before
       }
-      // frames not on the board yet → auto boards only (a curated board shows exactly its list)
+      // frames not on the board yet → auto boards only (a curated board shows exactly its list).
+      // Grouped newcomers land beside their siblings (like the live JOIN); ungrouped ones
+      // go past the board's right edge (the live JOIN flows them below) - NEVER at (0,0)
+      // (the published all-scenes bug: frames created after the board file was last
+      // saved piled up at the origin)
       if (boardAuto) {
         const placed = new Set(nodes.map((n) => n.frame))
+        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
           placed.add(f.id)
           const d = defaultSize(f)
           const vp = deviceView ? CONFIG.viewports[deviceView] : null
-          nodes.push({ key: nodeKey(), frame: f.id, x: 0, y: 0, w: vp?.width ?? d.w, h: vp?.height ?? d.h, theme: resolveTheme(f), status: 'loading' })
+          const w = vp?.width ?? d.w, h = vp?.height ?? d.h
+          let x: number, y: number
+          const sibling = f.variantGroup
+            ? nodes.filter((n) => manifest.frames.find((m) => m.id === n.frame)?.variantGroup === f.variantGroup)
+                .reduce<Node | null>((a, n) => (!a || n.x + n.w > a.x + a.w ? n : a), null)
+            : 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' }
+          nodes.push(node)
+          maxX = Math.max(maxX, x + w)
         }
       }
       // published: re-apply this visit's pins over the inlined data
@@ -256,19 +299,31 @@ export const useStore = create<State>((set, get) => {
         }
       }
       if ((!boardHash || needTidy) && nodes.length) {
-        const sceneOf = (id: string) => manifest.frames.find((f) => f.id === id)?.scene ?? ''
-        const placedAll = tidy(nodes.map((n) => ({ key: n.key, scene: sceneOf(n.frame), w: n.w, h: n.h + HEADER })))
+        const entryOf = (id: string) => manifest.frames.find((f) => f.id === id)
+        const placedAll = tidy(nodes.map((n) => {
+          const f = entryOf(n.frame)
+          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
+        }), effectiveLayout(layout, sceneRows), layoutWarn)
         for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
       }
       // dirty matches disk by construction - except when load-time pruning changed the
       // node set; callers see dirty:true and schedule the save that persists the prune
-      return { manifest, nodes, boardHash, boardAuto, deviceView, baseLayout, selection: [], dirty: prunedAtLoad }
+      // surface recipe problems at load (dry-run): materialized boards otherwise
+      // never run tidy, so a broken agent-authored layout would fail silently
+      if (layout && boardHash && !needTidy && nodes.length) {
+        const entryOf2 = (id: string) => manifest.frames.find((f) => f.id === id)
+        tidy(nodes.map((n) => {
+          const f = entryOf2(n.frame)
+          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
+        }), layout, layoutWarn)
+      }
+      return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, selection: [], dirty: prunedAtLoad }
     } catch { return null }
   }
 
   return {
     manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false,
-    board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, baseLayout: null,
+    board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
     panelOpen: true, scale: 1, toasts: [], boardHash: null, dirty: false,
 
     async boot() {
@@ -290,6 +345,12 @@ export const useStore = create<State>((set, get) => {
     async switchBoard(name) {
       const mySwitch = ++switchSeq             // also cancels any pending switch (incl. re-clicking the current board)
       if (name === get().board) return
+      // a resize held across a switch: settle THIS board (retidy if it has a recipe)
+      // before the flush, so the torn mid-gesture state is never what reaches disk
+      if (resizedInGesture) {
+        resizedInGesture = false
+        if (get().layout || get().sceneRows?.length) get().runTidy()
+      }
       // flush loop: an edit landing mid-save keeps dirty set and gets its own pass
       let ok = true
       for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
@@ -326,7 +387,15 @@ export const useStore = create<State>((set, get) => {
         if (known.has(f.id)) continue
         const d = defaultSize(f)
         const maxY = next.reduce((a, n) => Math.max(a, n.y + n.h), 0)
-        const node = { 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 }
+        // 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)
+        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 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 }
         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 } }
@@ -402,6 +471,8 @@ export const useStore = create<State>((set, get) => {
       scheduleSave()
     },
     resizeNode(key, w, h) {
+      resizedInGesture = true
+      const inGesture = get().gesture
       // a manual resize means the board no longer uniformly shows one device; the resized
       // frame's snapshot entry follows the user's new size so Default will not undo it
       set((s) => {
@@ -416,7 +487,9 @@ export const useStore = create<State>((set, get) => {
             : s.baseLayout,
         }
       })
-      scheduleSave()
+      // mid-gesture saves would persist torn state (new sizes, pre-recipe positions);
+      // the gesture-end hook saves once, after any retidy
+      if (!inGesture) scheduleSave()
     },
     setDeviceView(name) {
       const vp = name ? CONFIG.viewports[name] : null
@@ -484,12 +557,28 @@ 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)
+    selectMany(keys) {
+      set((s) => {
+        const valid = keys.filter((k) => s.nodes.some((n) => n.key === k))
+        return { selection: valid, interact: s.interact && valid.includes(s.interact) ? s.interact : null }
+      })
+    },
     // interact is a ONE-frame mode: entering it collapses any multi-selection to the
     // interacted frame (a 4-frame selection double-clicked otherwise leaves all four
     // painted as "interactive"). Exiting keeps the frame selected for continuity.
     setInteract(key) { set((s) => ({ interact: key, selection: key ? [key] : s.selection })) },
     setPlay(play) { set({ play }) },
-    setGesture(gesture) { set({ gesture }) },
+    setGesture(gesture) {
+      set({ gesture })
+      // SPEC-024 §4: 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
+        if (get().layout || get().sceneRows?.length) get().runTidy()   // schedules the save
+        else scheduleSave()
+      }
+    },
     setScale(scale) { set({ scale }) },
     togglePanel() { set((s) => ({ panelOpen: !s.panelOpen })) },
     // global theme = the VIEW preference: persists across boards + reloads, clears
@@ -507,9 +596,12 @@ export const useStore = create<State>((set, get) => {
       scheduleSave()
     },
     runTidy() {
-      const { nodes, manifest } = get()
-      const sceneOf = (id: string) => manifest?.frames.find((f) => f.id === id)?.scene ?? ''
-      const placed = tidy(nodes.map((n) => ({ key: n.key, scene: sceneOf(n.frame), w: n.w, h: n.h + HEADER })))
+      const { nodes, manifest, sceneRows, layout } = get()
+      const entryOf = (id: string) => manifest?.frames.find((f) => f.id === id)
+      const placed = tidy(nodes.map((n) => {
+        const f = entryOf(n.frame)
+        return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
+      }), effectiveLayout(layout, sceneRows), layoutWarn)
       set((s) => ({
         nodes: s.nodes.map((n) => {
           const p = placed.find((x) => x.key === n.key)
@@ -543,6 +635,9 @@ export const useStore = create<State>((set, get) => {
     },
 
     save() {
+      // 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
       // session instead, and dirty must clear or switchBoard's save-flush loop wedges
       if (DATA) {
@@ -551,6 +646,10 @@ export const useStore = create<State>((set, get) => {
         return Promise.resolve(true)
       }
       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)
+        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).
@@ -559,6 +658,8 @@ export const useStore = create<State>((set, get) => {
           // deviceView and the free-form snapshot persist independently: a scoped
           // exception clears the view but 0 must still restore the snapshot after reload
           ...(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 } : {}) })),

package/src/client/shell/styles.css

@@ -525,3 +525,89 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
    Inset so scroll containers can never clip it; outline follows the border radius. */
 .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
+   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:
+   a pure world gap reads ever wider zoomed in, an uncapped screen gap outgrows the
+   gutter zoomed out */
+.sh-vbadge { position: absolute; right: 100%; top: 0;
+  /* margin caps at 40 WORLD px: below ~30% zoom an uncapped screen-constant margin
+     alone would outgrow the gutter and push the badge onto the left neighbor */
+  margin-right: clamp(6px, calc(12px * var(--sh-inv, 1)), 40px);
+  display: flex; flex-direction: column; align-items: flex-end; gap: 2px;
+  text-align: right; user-select: none; -webkit-user-select: none;
+  font-family: -apple-system, system-ui, sans-serif }
+.sh-vbadge b { font-size: min(clamp(40px, calc(20px * var(--sh-inv, 1)), 120px), calc(40px * var(--sh-inv, 1))); line-height: 1; font-weight: 750;
+  /* world cap 120px: past ~17% zoom the letter stops growing (in world terms) and
+     shrinks with the canvas instead of bleeding across the gutter onto the neighbor */
+  letter-spacing: -0.02em; color: rgba(24, 24, 27, .55);
+  /* the letter OUTLIVES the name (drive feedback 2026-08-12): the name leaves at
+     ~30%, the letter stays useful until ~10-16% - the world cap keeps it inside the
+     gutter down there - and then hands identity to the group caption */
+  opacity: clamp(0, calc((var(--sh-s, 1) - 0.1) * 15), 1) }
+.sh-vbadge span { font-size: min(max(15px, calc(10px * var(--sh-inv, 1))), calc(15px * var(--sh-inv, 1))); font-weight: 550;
+  color: rgba(24, 24, 27, .38); max-width: 96px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  /* the letter is the identity at overview zoom; the name earns pixels only close up */
+  opacity: clamp(0, calc((var(--sh-s, 1) - 0.3) * 6), 1) }
+.sh-app.dark .sh-vbadge b { color: rgba(245, 245, 247, .6) }
+.sh-app.dark .sh-vbadge span { color: rgba(245, 245, 247, .4) }
+
+.sh-gcaption { position: absolute; top: 0; left: 0; user-select: none; -webkit-user-select: none;
+  /* screen-clamped both ways: 12px floor at overview, 18px ceiling zoomed in - world
+     text that keeps growing past 100% zoom dwarfs the fixed-size floating menu above */
+  font: 600 clamp(calc(12px * var(--sh-inv, 1)), 17px, calc(18px * var(--sh-inv, 1)))/1.2 -apple-system, system-ui, sans-serif;
+  letter-spacing: .01em; color: rgba(24, 24, 27, .45); white-space: nowrap }
+.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) */
+.sub.vgroup { display: flex; align-items: center; gap: 8px }
+.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) }
+.sub.vgroup.on .gicon { color: var(--accent) }
+.sub .chip { width: 20px; height: 20px; flex: none; display: inline-flex; align-items: center; justify-content: center;
+  border: 1px solid var(--glass-brd); border-radius: 7px; background: none; cursor: pointer;
+  font: 700 10px -apple-system, system-ui, sans-serif; color: var(--glass-ink-3);
+  /* optical centering: trim the text box to CAP height so flex centers the glyph
+     itself, not the em box (whose descender space floats caps high) */
+  line-height: 1; letter-spacing: 0; text-box: trim-both cap alphabetic;
+  transition: color .15s, background .15s, border-color .15s }
+.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) */
+.sh-play-nav .vchip { min-width: 24px; font-weight: 700; font-size: 11px }
+.sh-play-nav .vchip.on { color: #fff; background: var(--accent); border-radius: 7px }
+
+.sh-play-nav .vname { font-size: 11px; font-weight: 600; color: var(--glass-ink-2); max-width: 120px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; text-transform: capitalize; padding: 0 2px }
+
+/* variant chrome goes LIVE with selection (drive feedback 2026-08-12): accent when the
+   frame is selected, the interact purple when it is being interacted with - the badge,
+   name, caption, and frame title all agree with the frame's state */
+.sh-vbadge { cursor: pointer }
+/* children stay click-transparent: rzpp's pan exclusion and the select handler both
+   need the BADGE DIV to be the event target (same pattern as button svg) */
+.sh-vbadge b, .sh-vbadge span { pointer-events: none }
+.sh-node.sel .sh-vbadge b, .sh-node.sel .sh-vbadge span { color: var(--accent) }
+.sh-node.interact .sh-vbadge b, .sh-node.interact .sh-vbadge span { color: var(--interact) }
+/* the frame header sits INSIDE the selection border - tinting its title too would
+   double-signal (drive feedback 2026-08-12); the badge/caption/sidebar carry state */
+.sh-gcaption { cursor: pointer }
+.sh-gcaption.on { color: var(--accent) }
+.sh-gcaption:hover { color: var(--glass-ink-2) }
+.sh-gcaption.on:hover { color: var(--accent) }
+
+/* per-variant sidebar rows under the group header */
+/* variant rows read one level QUIETER than frame rows: shorter, smaller, lighter -
+   the scannable hierarchy is scene > frame/surface > variants */
+.sub.vrow { display: flex; align-items: center; gap: 7px; padding-left: 31px; height: 24px; font-size: 12px }
+.sub.vrow .chip { width: 16px; height: 16px; border-radius: 5px; font-size: 8.5px }
+.sub.vrow .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
+.sub.vgroup { cursor: pointer }
+.sub.vgroup.held { background: color-mix(in srgb, var(--glass-hover) 55%, transparent) }
+.sub.vgroup.held .gicon { color: var(--glass-ink-2) }