@marver-design/marver 0.2.2 → 0.2.3

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) }