@marver-design/marver 0.22.0 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/CHANGELOG.md +106 -0
  2. package/README.md +13 -9
  3. package/dist/agent-BsieQGTD.mjs +99 -0
  4. package/dist/{bake-BSX4XR_U.mjs → bake-l6N12qgx.mjs} +1 -1
  5. package/dist/{board-status-CWGHIdo_.mjs → board-status-D_lHZZ09.mjs} +69 -610
  6. package/dist/{boards-BTGNPVMx.mjs → boards-CahYhF5B.mjs} +3 -1
  7. package/dist/boards-DbVJlbd5.mjs +612 -0
  8. package/dist/{build-Dd2Qm3OG.mjs → build-CuRhHXcY.mjs} +10 -6
  9. package/dist/cli.mjs +22 -12
  10. package/dist/{comments-ClVgfQib.mjs → comments-0d3e274b.mjs} +71 -9
  11. package/dist/{config-DJxMRVD8.mjs → config-g-J8NrPn.mjs} +5 -97
  12. package/dist/{context-DUAENlJ6.mjs → context-fAtQLHt2.mjs} +3 -2
  13. package/dist/{daemon-BmkwErpC.mjs → daemon-DZ367fiM.mjs} +75 -17
  14. package/dist/{dev-BW7a5kDF.mjs → dev-R6zvwbqX.mjs} +55 -9
  15. package/dist/{init-NJ3xjLVu.mjs → init-DAnBlt-V.mjs} +6 -4
  16. package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
  17. package/dist/link-CcfAfKY-.mjs +132 -0
  18. package/dist/{manifest-BqBcMJcd.mjs → manifest-BkjJ5OQk.mjs} +73 -5
  19. package/dist/{plugin-8XntSCx_.mjs → plugin-C1avHL7g.mjs} +357 -31
  20. package/dist/{poster-DRZDszTI.mjs → poster-Bc4-3DlQ.mjs} +1 -1
  21. package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
  22. package/dist/{publish-bakes-CCWRV9iX.mjs → publish-bakes-DQWn14IY.mjs} +2 -2
  23. package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
  24. package/dist/{shot-BFEuYbaz.mjs → shot-C1YR_Sqx.mjs} +1 -1
  25. package/dist/{shot-C22Ues04.mjs → shot-CVOlQHUr.mjs} +2 -2
  26. package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
  27. package/dist/{work-0YopuMt9.mjs → work-CJ8OIpBD.mjs} +9 -3
  28. package/dist/{work-CLrmY-vQ.mjs → work-CiUvBVa6.mjs} +72 -1
  29. package/docs/boards-and-folders.md +54 -6
  30. package/docs/context.md +10 -2
  31. package/docs/live-jam.md +11 -0
  32. package/package.json +1 -1
  33. package/src/client/content/diagram.tsx +7 -1
  34. package/src/client/content/img-lod.ts +12 -2
  35. package/src/client/content/index.tsx +69 -6
  36. package/src/client/frame-host/inspect.js +23 -0
  37. package/src/client/shell/App.tsx +19 -9
  38. package/src/client/shell/BoardList.tsx +21 -6
  39. package/src/client/shell/LockedApp.tsx +2 -2
  40. package/src/client/shell/Play.tsx +5 -1
  41. package/src/client/shell/StatusPicker.tsx +12 -5
  42. package/src/client/shell/Tip.tsx +25 -5
  43. package/src/client/shell/board-icons.tsx +15 -1
  44. package/src/client/shell/canvas/Canvas.tsx +42 -6
  45. package/src/client/shell/canvas/anchor.ts +41 -0
  46. package/src/client/shell/canvas/ctl.ts +6 -0
  47. package/src/client/shell/comments-store.ts +8 -5
  48. package/src/client/shell/goto.ts +52 -3
  49. package/src/client/shell/hash.ts +24 -3
  50. package/src/client/shell/store.ts +242 -28
  51. package/src/client/shell/styles.css +19 -2
  52. package/src/shared/board-types.ts +10 -6
  53. package/src/shared/status.ts +17 -8
  54. package/templates/AGENTS-embedded.md +54 -8
  55. package/templates/AGENTS-studio.md +54 -8
  56. package/templates/instructions/boards.md +15 -3
  57. package/templates/instructions/context.md +20 -7
  58. package/templates/instructions/iterate.md +29 -16
  59. package/templates/instructions/jam.md +9 -2
  60. package/templates/instructions/reference/deck-layouts.md +2 -1
  61. package/templates/instructions/reference/deck-story.md +2 -1
@@ -3,6 +3,7 @@ import { ROUTE, slideSize } from '../const.ts'
3
3
  import { tidy, parseLayout, type BoardLayout, type TidyNode } from './tidy.ts'
4
4
  import { clearNoteHeights, noteHeight, noteReserve, notesCramped, setNoteHeight } from './notes.ts'
5
5
  import { stableNodeKey } from './keys.ts'
6
+ import { canvasCtl } from './canvas/ctl.ts'
6
7
  // @ts-expect-error virtual module provided by the plugin
7
8
  import shConfig from 'virtual:sh-config'
8
9
  // @ts-expect-error virtual module: null in dev; a published build inlines manifest+boards
@@ -25,6 +26,8 @@ const DATA: {
25
26
  policy?: { boards: Record<string, { type?: string; open?: string; lock?: boolean }>; reveal?: { structure?: boolean; source?: boolean }; lockedShell?: boolean }
26
27
  /** the generation of the glass textures this build shipped (publish-bakes.ts); absent = none */
27
28
  bakes?: number
29
+ /** content-frame heights, `scene/frame@width` -> px (design/boards/_sizes.json, published frames only) */
30
+ sizes?: Record<string, number>
28
31
  } | null = shData
29
32
 
30
33
  /** The published textures' generation, or 0: the static index this build shipped is at /__mv/bakes/<gen>/index.json. */
@@ -210,6 +213,11 @@ export const HAS_ALL_SCENES = !DATA || DATA.names.includes('all-scenes')
210
213
  /** Display name for a board: its title when one is set (subscribe to `boardTitles` to
211
214
  * re-render on change), else the Title-Cased slug ('all-scenes' reads "All Scenes"). */
212
215
  export const boardLabel = (n: string) => labelOf(n, useStore.getState().boardTitles[n])
216
+ /** The canvas's name, as the sidebar heads it: the project's (share.name, else the repo folder). */
217
+ export const CANVAS_NAME = CONFIG.projectName ? humanize(CONFIG.projectName) : 'Marver'
218
+ /** The browser tab: the board, then the canvas - "Start here - Acme Studio" - so a row of canvas tabs
219
+ * says which project each one is (it said "- Marver" on all of them). */
220
+ export const tabTitle = (board: string | null | undefined): string => (board ? `${boardLabel(board)} - ${CANVAS_NAME}` : CANVAS_NAME)
213
221
  /** Display name for a scene: the title in its brief's front matter, else the Title-Cased directory. */
214
222
  export const sceneLabel = (n: string) => labelOf(n, useStore.getState().manifest?.scenes.find((s) => s.name === n)?.title)
215
223
 
@@ -276,22 +284,115 @@ const manifestKey = (m: Manifest) => JSON.stringify(m.frames) // any change co
276
284
  let scenesRev = 0 // bumps per sh:scenes, so a load that straddled one keeps the live labels
277
285
  let liveScenes: Manifest['scenes'] | null = null // the last sh:scenes payload - applied late when it beat the first manifest
278
286
 
279
- /** Latest measured content heights, keyed frameId@width. TRANSIENT by design:
280
- * auto sizes are never serialized - a reload remeasures. */
287
+ /** Latest measured content heights, keyed frameId@width - this session's live truth. Board files
288
+ * never carry auto sizes; the committed cache below does. */
281
289
  const measuredHeights = new Map<string, number>()
282
290
 
291
+ /** Committed content heights (design/boards/_sizes.json - src/server/sizes.ts), keyed frameId@width:
292
+ * a content frame's height BEFORE it measures, so a board opens at its final geometry instead of
293
+ * growing from a guess and re-flowing row after row. Read at every board load in dev (the API: an
294
+ * agent may have edited frames since), once from the bundle on a published canvas. A stale entry
295
+ * is still the best first guess - the live measurement corrects it, and the dev shell writes the
296
+ * correction back. */
297
+ const savedHeights = new Map<string, number>()
298
+ /** The frames that measure (render a Doc), as the dev server read their sources at the last load -
299
+ * only theirs is a height to trust: a Doc turned bare Md keeps the size its board gives it, even
300
+ * in a page that measured it as a Doc earlier. null = no such list (a published bundle ships only
301
+ * measuring frames' heights). */
302
+ let measuring: Set<string> | null = null
303
+ let publishedLoaded = false
304
+ async function loadSavedHeights(): Promise<void> {
305
+ if (DATA) {
306
+ if (publishedLoaded) return
307
+ publishedLoaded = true
308
+ for (const [k, v] of Object.entries(DATA.sizes ?? {})) if (typeof v === 'number' && Number.isFinite(v) && v > 0) savedHeights.set(k, Math.round(v))
309
+ return
310
+ }
311
+ try {
312
+ const r = await fetch(`${ROUTE}/api/sizes`)
313
+ if (!r.ok) return
314
+ const body = (await r.json()) as { heights?: Record<string, unknown>; measuring?: unknown }
315
+ savedHeights.clear()
316
+ for (const [k, v] of Object.entries(body.heights ?? {})) if (typeof v === 'number' && Number.isFinite(v) && v > 0) savedHeights.set(k, Math.round(v))
317
+ measuring = Array.isArray(body.measuring) ? new Set(body.measuring.filter((x): x is string => typeof x === 'string')) : null
318
+ } catch { /* no cache: placeholders, as before */ }
319
+ }
320
+ const measures = (frameId: string) => !measuring || measuring.has(frameId)
321
+
322
+ // settled heights that differ from the committed ones, written back in batches (dev only). One
323
+ // write in flight at a time; a height that changes while its write is in flight queues behind it,
324
+ // so the LAST settled height is the one the file ends with
325
+ const pendingHeights = new Map<string, number>()
326
+ const inflightHeights = new Map<string, number>()
327
+ let heightsTimer: ReturnType<typeof setTimeout> | undefined
328
+ let flushing = false
329
+ const persistHeight = (key: string, h: number) => {
330
+ if (DATA) return
331
+ if (!inflightHeights.has(key) && savedHeights.get(key) === h) { pendingHeights.delete(key); return }
332
+ pendingHeights.set(key, h)
333
+ if (!flushing) heightsTimer ??= setTimeout(flushHeights, 1500) // a throttle, not a debounce: a board settling in waves still writes
334
+ }
335
+ async function flushHeights() {
336
+ heightsTimer = undefined
337
+ if (flushing || !pendingHeights.size) return
338
+ flushing = true
339
+ const batch = Object.fromEntries([...pendingHeights].slice(0, 500))
340
+ for (const [k, v] of Object.entries(batch)) { pendingHeights.delete(k); inflightHeights.set(k, v) }
341
+ let answered = false
342
+ try {
343
+ const r = await postOwner('sizes', { heights: batch })
344
+ if (r.ok) {
345
+ const accepted = new Set(((await r.json()) as { accepted?: string[] }).accepted ?? [])
346
+ for (const k of Object.keys(batch)) if (accepted.has(k)) savedHeights.set(k, batch[k])
347
+ answered = true
348
+ }
349
+ } catch { /* lost: below */ }
350
+ // no answer = the write may or may not have landed: what the file holds is unknown, so nothing is
351
+ // deduplicated against it - a correction queued meanwhile still goes, the next report still writes
352
+ if (!answered) for (const k of Object.keys(batch)) savedHeights.delete(k)
353
+ for (const k of Object.keys(batch)) inflightHeights.delete(k)
354
+ // a height that settled while the write was in flight: still owed only if it differs from what landed
355
+ for (const [k, v] of pendingHeights) if (savedHeights.get(k) === v) pendingHeights.delete(k)
356
+ flushing = false
357
+ if (pendingHeights.size) heightsTimer ??= setTimeout(flushHeights, 1500)
358
+ }
359
+
360
+ const hasKnownHeight = (frameId: string, w: number) => measures(frameId) && (measuredHeights.has(`${frameId}@${w}`) || savedHeights.has(`${frameId}@${w}`))
361
+
362
+ /** The Doc sizes a layout was computed around: each auto content node whose height is known, by key,
363
+ * as "WxH" (one line per node in the board file). A composed board saves it with its positions
364
+ * (`laidOut`); a load where a node it names now has another size knows its rows were laid out
365
+ * around other sizes - grown, shrunk, or gone from document to wide. A drag changes no size, and a
366
+ * node added or removed is no size change of the others. */
367
+ export type LaidOut = Record<string, string>
368
+ const sizeOf = (n: Node) => `${Math.round(n.w)}x${Math.round(n.h)}`
369
+ function sizeRecord(nodes: readonly Node[]): LaidOut {
370
+ const out: LaidOut = {}
371
+ for (const n of nodes) if (n.sizeMode === 'auto' && hasKnownHeight(n.frame, Math.round(n.w))) out[n.key] = sizeOf(n)
372
+ return out
373
+ }
374
+ const readLaidOut = (v: unknown): LaidOut | null => {
375
+ if (!v || typeof v !== 'object' || Array.isArray(v)) return null
376
+ const out: LaidOut = {}
377
+ for (const [k, wh] of Object.entries(v)) if (typeof wh === 'string' && /^\d+x\d+$/.test(wh)) out[k] = wh
378
+ return out
379
+ }
380
+
283
381
  function defaultSize(frame: FrameEntry) {
284
382
  // the precedence chain (spec 09 slice 1): slide stage → authored
285
383
  // viewport → content sizing → default (one helper, shared with shot) -
286
384
  // a slide's stage is its declared viewport, else 1280×720
287
385
  const sl = slideSize(frame, CONFIG.viewports)
288
386
  if (sl) return { w: sl.width, h: sl.height }
289
- // content frames: own width from Doc layout; height from the latest
290
- // measurement at that width, or a placeholder until sh:measure lands.
291
- // meta.viewport, when declared, wins - the existing precedence.
292
- if (frame.contentWidth && !frame.viewport) {
293
- const w = frame.contentWidth
294
- return { w, h: measuredHeights.get(`${frame.id}@${w}`) ?? Math.round(w * 0.75) }
387
+ // content frames: own width from Doc layout (meta.viewport, when declared, wins - the existing
388
+ // precedence); height from this session's measurement at that width, else the committed one,
389
+ // else a placeholder until sh:measure lands
390
+ if (frame.contentWidth) {
391
+ const vp = CONFIG.viewports[frame.viewport ?? '']
392
+ const w = vp?.width ?? frame.contentWidth
393
+ const key = `${frame.id}@${w}`
394
+ const known = measures(frame.id) ? measuredHeights.get(key) ?? savedHeights.get(key) : undefined
395
+ return { w, h: known ?? vp?.height ?? Math.round(w * 0.75) }
295
396
  }
296
397
  const vp = CONFIG.viewports[frame.viewport ?? ''] ?? CONFIG.viewports.mobile ?? { width: 390, height: 844 }
297
398
  return { w: vp.width, h: vp.height }
@@ -329,6 +430,8 @@ interface State {
329
430
  layout: BoardLayout | null // lane-flow recipe, parsed; wins over sceneRows when both exist
330
431
  layoutRaw: unknown // the author's layout VERBATIM - save round-trips this, never the parse
331
432
  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)
433
+ laidOut: LaidOut | null // a composed board's record of the Doc heights its positions were laid out around (sizeRecord)
434
+ baseLaidOut: LaidOut | null // the free-form layout's laidOut, kept with baseLayout while a device view is up; Default restores both
332
435
  panelOpen: boolean
333
436
  scale: number
334
437
  toasts: Toast[]
@@ -353,7 +456,9 @@ interface State {
353
456
  frameFor(node: Node): FrameEntry | undefined
354
457
  moveNode(key: string, x: number, y: number): void
355
458
  resizeNode(key: string, w: number, h: number): void
356
- measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
459
+ /** `settled`: the Doc's fonts, images and diagrams are done (content/index.tsx). false = provisional
460
+ * (an image still loading) - it may grow a frame, never shrink it under a known height. */
461
+ measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number, settled?: boolean): void
357
462
  /** A node's sticky column was drawn (or grew, or went): its extent from the node's top, world px. */
358
463
  noteMeasured(key: string, height: number): void
359
464
  setStatus(key: string, status: Node['status'], error?: string): void
@@ -409,7 +514,15 @@ interface State {
409
514
  /** When each working frame's job started (ms epoch) - phases the animations so parallel
410
515
  * frames never pulse in sync. */
411
516
  workingSince: Record<string, number>
412
- setWorking(frames: string[]): void
517
+ setWorking(frames: string[], boards?: string[]): void
518
+ /** setWorking from a wire payload (`{ frames, boards }`), strings only. */
519
+ setWorkingFrom(m: unknown): void
520
+ /** Fetch what is lit now (dev only) - the snapshot behind the broadcasts. */
521
+ syncWorking(): Promise<void>
522
+ /** Boards showing a working frame - their sidebar icon shimmers while an agent works. */
523
+ workingBoards: string[]
524
+ /** The place in the server's order of the activity last applied - an older answer is dropped. */
525
+ workingSeq: number
413
526
  spawn(frameId: string): Node | null
414
527
  save(): Promise<boolean>
415
528
  }
@@ -447,12 +560,19 @@ export const useStore = create<State>((set, get) => {
447
560
  // The captured board name is the generation guard - a debounce surviving a board
448
561
  // switch fires into a name check and dies, never touching the new board.
449
562
  // `onlyIf` (a note asking for room) is re-judged when the timer fires - a drag or a restore
450
- // in the meantime may have settled it - and never downgrades an unconditional reflow pending.
563
+ // in the meantime may have settled it - and never downgrades an unconditional reflow pending;
564
+ // two conditions pending are EITHER one (a later ask never drops an earlier one).
451
565
  let reflowTimer: ReturnType<typeof setTimeout> | undefined
452
566
  let reflowCheck: (() => boolean) | null = null
453
- const scheduleReflow = (onlyIf?: () => boolean) => {
567
+ /** A board load (boot, switch) starts its own reflow story: whatever was pending - an
568
+ * unconditional reflow from the board that was up - must never carry over and tidy this one. */
569
+ const cancelReflow = () => { clearTimeout(reflowTimer); reflowTimer = undefined; reflowCheck = null }
570
+ /** How long a content reflow waits for a camera in flight - past it, the rows move anyway. */
571
+ const REFLOW_CAMERA_WAIT = 1500
572
+ const scheduleReflow = (onlyIf?: () => boolean, delay = 400, cameraSince?: number) => {
454
573
  const boardAt = get().board
455
- reflowCheck = reflowTimer !== undefined && reflowCheck === null ? null : (onlyIf ?? null)
574
+ const prev = reflowTimer !== undefined ? reflowCheck : undefined // undefined: nothing pending
575
+ reflowCheck = prev === null || !onlyIf ? null : prev ? () => prev() || onlyIf() : onlyIf
456
576
  clearTimeout(reflowTimer)
457
577
  reflowTimer = setTimeout(() => {
458
578
  reflowTimer = undefined
@@ -460,10 +580,18 @@ export const useStore = create<State>((set, get) => {
460
580
  reflowCheck = null
461
581
  const s = get()
462
582
  if (s.board !== boardAt) return
463
- if (s.gesture) { scheduleReflow(check ?? undefined); return } // defer, never drop - retries after the drag
583
+ // defer, never drop - retries after the drag
584
+ if (s.gesture) { scheduleReflow(check ?? undefined); return }
585
+ // and after a camera flight: a link's fit lands first, then the rows move around the frames it
586
+ // showed (holdView keeps them where the fit put them). Looked at often, so the reflow follows the
587
+ // landing closely - and never waited on past REFLOW_CAMERA_WAIT: a camera that keeps moving (fit
588
+ // after fit) does not hold the rows apart forever
589
+ const since = cameraSince ?? Date.now()
590
+ if (canvasCtl.cameraBusy() && Date.now() - since < REFLOW_CAMERA_WAIT) { scheduleReflow(check ?? undefined, 60, since); return }
464
591
  if (check && !check()) return
465
- if (composed(s)) s.runTidy()
466
- }, 400)
592
+ // content moved the rows, not the human: hold what they are looking at still (Canvas.tsx)
593
+ if (composed(s)) { canvasCtl.holdView(); s.runTidy() }
594
+ }, delay)
467
595
  }
468
596
  /** Boards whose layout the shell owns: a recipe, scene rows, or the auto board. Room for a
469
597
  * note is made here; a board the human placed by hand is never moved (spec 18, 0.19.1). */
@@ -472,6 +600,32 @@ export const useStore = create<State>((set, get) => {
472
600
  /** A note may have landed with no room (a frame note via the manifest, a scene note via
473
601
  * sh:scenes, either merged late by boot/switch): a composed board re-applies its layout. */
474
602
  const roomForNotes = () => { if (composed(get()) && cramped()) scheduleReflow(cramped) }
603
+ /** A composed board's saved positions were laid out around the heights of the session that saved
604
+ * them. A committed height that changed since (the doc grew or shrank while another board was
605
+ * open) opens at its new size over - or far above - the row below, and no measurement will re-flow
606
+ * it: it already equals the committed one. So once the board is up, the recipe re-runs if the
607
+ * known heights differ from the ones its positions were laid out around (`laidOut`). A frame the
608
+ * human dragged, at heights that did not change, stays where they put it. */
609
+ const layoutStale = () => {
610
+ const { nodes, laidOut } = get()
611
+ const record = laidOut ?? {}
612
+ const known = (n: Node) => n.sizeMode === 'auto' && hasKnownHeight(n.frame, Math.round(n.w))
613
+ const has = (n: Node) => Object.prototype.hasOwnProperty.call(record, n.key)
614
+ // a node the layout recorded, at another size now
615
+ if (nodes.some((n) => known(n) && has(n) && sizeOf(n) !== record[n.key])) return true
616
+ // a node it never recorded (an agent's board, an older save, a Doc that had not measured yet):
617
+ // an overlap is the one thing a size change does that a hand never meant
618
+ const box = (n: Node) => ({ l: n.x, t: n.y, r: n.x + n.w, b: n.y + n.h + HEADER })
619
+ return nodes.some((a) => {
620
+ if (!known(a) || has(a)) return false
621
+ const A = box(a)
622
+ return nodes.some((b) => { if (b === a) return false; const B = box(b); return A.l < B.r - 1 && B.l < A.r - 1 && A.t < B.b - 1 && B.t < A.b - 1 })
623
+ })
624
+ }
625
+ const recheckLayout = () => {
626
+ const s = get()
627
+ if (composed(s) && s.nodes.some((n) => n.sizeMode === 'auto' && hasKnownHeight(n.frame, Math.round(n.w)))) scheduleReflow(layoutStale)
628
+ }
475
629
 
476
630
  /** Theme resolution ladder: user pin > the frame's declared meta.theme > viewTheme. */
477
631
  const resolveTheme = (frame?: FrameEntry, user?: string) => user ?? frame?.theme ?? get().viewTheme
@@ -521,12 +675,14 @@ export const useStore = create<State>((set, get) => {
521
675
  clearNoteHeights() // heights are per column drawn; a key shared by two board files carries none across
522
676
  try {
523
677
  let raw: any
678
+ const saved = loadSavedHeights() // in parallel with the manifest; every size below reads it
524
679
  if (DATA) raw = DATA.manifest
525
680
  else {
526
681
  const mRes = await fetch('/design/manifest.json')
527
682
  if (!mRes.ok) return null
528
683
  raw = await mRes.json().catch(() => undefined)
529
684
  }
685
+ await saved
530
686
  if (raw === undefined || raw === null || typeof raw !== 'object') return null
531
687
  bumpManifestRev() // fresh manifest → fresh iframe URLs
532
688
  const manifest: Manifest = {
@@ -542,6 +698,8 @@ export const useStore = create<State>((set, get) => {
542
698
  let layout: BoardLayout | null = null
543
699
  let layoutRaw: unknown = undefined
544
700
  let baseLayout: State['baseLayout'] = null
701
+ let laidOut: LaidOut | null = null
702
+ let baseLaidOut: LaidOut | null = null
545
703
  let needTidy = false
546
704
  // published build: boards come from the inlined data; absent = fresh (the 404 path)
547
705
  let loaded: { board: any; sha256: string } | 'fresh' | null
@@ -585,11 +743,16 @@ export const useStore = create<State>((set, get) => {
585
743
  const sizeMode = f?.contentWidth
586
744
  ? { sizeMode: (n.sizeMode === 'manual' || n.sizeMode === 'device' ? n.sizeMode : 'auto') as Node['sizeMode'] }
587
745
  : {}
746
+ // an AUTO content node whose height is KNOWN (measured, or committed - sizes.ts) opens at
747
+ // it: a w/h in the file is a guess (an agent wrote the node) or a pre-auto leftover the
748
+ // first measurement overrides anyway - opening at it only to jump is the swim. Unknown
749
+ // (a frame that never measures: no Doc) keeps the file's size, as before
750
+ const own = sizeMode.sizeMode === 'auto' && !!f && hasKnownHeight(f.id, d.w)
588
751
  return {
589
752
  key,
590
753
  frame: n.frame,
591
754
  x: typeof n.x === 'number' ? n.x : 0, y: typeof n.y === 'number' ? n.y : 0,
592
- w: typeof n.w === 'number' ? n.w : d.w, h: typeof n.h === 'number' ? n.h : d.h,
755
+ w: !own && typeof n.w === 'number' ? n.w : d.w, h: !own && typeof n.h === 'number' ? n.h : d.h,
593
756
  ...(!f && typeof n.w !== 'number' && typeof n.h !== 'number' ? { sizeFallback: true } : {}),
594
757
  ...sizeMode,
595
758
  // pins persist as their own field (exact round-trip). Legacy boards stored a
@@ -619,6 +782,8 @@ export const useStore = create<State>((set, get) => {
619
782
  layout = parseLayout(board?.layout, layoutWarn)
620
783
  if (layout && sceneRows) layoutWarn('board has layout AND sceneRows - layout wins')
621
784
  if (board?.baseLayout && typeof board.baseLayout === 'object') baseLayout = board.baseLayout
785
+ laidOut = readLaidOut(board?.laidOut)
786
+ baseLaidOut = readLaidOut(board?.baseLaidOut)
622
787
  }
623
788
  // auto-managed goes both ways (friction log #15): an auto board gains new frames
624
789
  // AND sheds deleted ones. Tombstone cards are a curated-board concept.
@@ -685,6 +850,7 @@ export const useStore = create<State>((set, get) => {
685
850
  if ((!boardHash || needTidy || cramped) && nodes.length) {
686
851
  const placedAll = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn)
687
852
  for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
853
+ laidOut = sizeRecord(nodes)
688
854
  }
689
855
  // dirty matches disk by construction - except when load-time pruning changed the
690
856
  // node set (or a cramped note re-ran the recipe); callers see dirty:true and
@@ -694,14 +860,14 @@ export const useStore = create<State>((set, get) => {
694
860
  if (layout && boardHash && !needTidy && !cramped && nodes.length) {
695
861
  tidy(tidyInput(nodes, manifest), layout, layoutWarn)
696
862
  }
697
- return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, selection: [], dirty: prunedAtLoad || cramped }
863
+ return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, laidOut, baseLaidOut, selection: [], dirty: prunedAtLoad || cramped }
698
864
  } catch { return null }
699
865
  }
700
866
 
701
867
  return {
702
868
  manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
703
- board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
704
- panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
869
+ board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null, laidOut: null, baseLaidOut: null,
870
+ panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, workingBoards: [], workingSeq: -1, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
705
871
  pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
706
872
 
707
873
  async boot(mayCommit) {
@@ -715,10 +881,12 @@ export const useStore = create<State>((set, get) => {
715
881
  if (get().board !== boardName || editRev !== revAtStart || (mayCommit && !mayCommit())) return false
716
882
  const live = get().manifest // a WS manifest update may have landed mid-fetch
717
883
  set(next)
884
+ cancelReflow()
718
885
  if (next.dirty) scheduleSave() // load-time prune must reach the disk
719
886
  if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
720
887
  else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } }) // an sh:scenes that landed mid-fetch outranks the file we read
721
888
  roomForNotes() // whichever way the notes arrived, they get their room
889
+ recheckLayout() // and a height committed since the board was laid out, its rows
722
890
  return true
723
891
  },
724
892
 
@@ -750,10 +918,12 @@ export const useStore = create<State>((set, get) => {
750
918
  ++loadSeq // invalidate any in-flight boot of the old board
751
919
  const live = get().manifest // a WS manifest update may have landed mid-load
752
920
  set({ board: name, interact: null, ...next })
921
+ cancelReflow()
753
922
  if (next.dirty) scheduleSave() // load-time prune must reach the disk
754
923
  if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
755
924
  else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })
756
925
  roomForNotes()
926
+ recheckLayout()
757
927
  },
758
928
 
759
929
  renameBoard(name, title, baseHash) {
@@ -828,8 +998,11 @@ export const useStore = create<State>((set, get) => {
828
998
  if (status) {
829
999
  const meta = { ...get().boardMeta }
830
1000
  const cur = meta[name] ?? {}
831
- const row = ({ archived: 1, paused: 2, blocked: 3, 'in-progress': 5, done: 6, todo: 8, backlog: 9 } as const)[status]
832
- meta[name] = { ...cur, status: { status, row, ...(status === 'blocked' && reason ? { reason } : {}), evidence: [`design/boards/${name}.json: "status": "${status}"`] } }
1001
+ const row = ({ archived: 1, paused: 2, blocked: 3, 'in-progress': 5, building: 5, done: 6, todo: 8, backlog: 9 } as const)[status]
1002
+ // with context/, In progress and Building were written into the open plan, not the board
1003
+ const inPlan = (status === 'building' || status === 'in-progress') && !(cur.settable ?? []).includes('todo')
1004
+ const evidence = inPlan ? ['context/plans/: stage written from the sidebar'] : [`design/boards/${name}.json: "status": "${status}"`]
1005
+ meta[name] = { ...cur, status: { status, row, ...(status === 'blocked' && reason ? { reason } : {}), evidence } }
833
1006
  set({ boardMeta: meta })
834
1007
  }
835
1008
  return { ok: true }
@@ -1040,7 +1213,7 @@ export const useStore = create<State>((set, get) => {
1040
1213
  * clamped. A height only commits when it was measured at the width being applied;
1041
1214
  * auto sizes are transient - applying one never dirties the board (positions from
1042
1215
  * the follow-up reflow do, exactly like a human resize). */
1043
- measureNode(key, frameId, ownWidth, measuredWidth, height) {
1216
+ measureNode(key, frameId, ownWidth, measuredWidth, height, settled) {
1044
1217
  const s = get()
1045
1218
  const node = s.nodes.find((n) => n.key === key)
1046
1219
  // Only an explicit DEVICE viewport locks a content frame's height. 'auto' and 'manual' both
@@ -1053,13 +1226,22 @@ export const useStore = create<State>((set, get) => {
1053
1226
  const f = s.manifest?.frames.find((x) => x.id === node.frame)
1054
1227
  if (!f?.contentWidth) return // not a content frame - spoof-proofing
1055
1228
  if (![ownWidth, measuredWidth, height].every((v) => Number.isFinite(v) && v > 0)) return
1229
+ // a Doc that reports IS one, whatever the last load's scan said (it arrived since): its heights
1230
+ // count until the next load re-reads the sources
1231
+ measuring?.add(f.id)
1056
1232
  // Generous cap: a reference doc with many screenshots is legitimately very tall and must fit in
1057
1233
  // FULL (this was 2.5x a viewport ~= 2700px, which clipped image-heavy docs). Still bounded so a
1058
1234
  // broken measurement can't mint an infinite frame.
1059
1235
  const maxH = 40000
1060
1236
  const H = Math.min(maxH, Math.max(80, Math.round(height)))
1061
1237
  const curW = Math.round(node.w)
1062
- measuredHeights.set(`${node.frame}@${Math.round(measuredWidth)}`, H)
1238
+ const mKey = `${node.frame}@${Math.round(measuredWidth)}`
1239
+ // a PROVISIONAL height (an image off-screen still lazy-loading) may grow a frame but never
1240
+ // shrink it under a height already known for this width: that one is what the finished doc
1241
+ // measures, and shrinking now would only grow back when the image lands - the swim again
1242
+ const known = measuredHeights.get(mKey) ?? savedHeights.get(mKey)
1243
+ if (settled === false && known !== undefined && H < known) return
1244
+ measuredHeights.set(mKey, H)
1063
1245
  // AUTO owns the width too - adopt the Doc's declared/own width. MANUAL keeps the human's width
1064
1246
  // and only fits the height.
1065
1247
  if (node.sizeMode !== 'manual') {
@@ -1075,6 +1257,9 @@ export const useStore = create<State>((set, get) => {
1075
1257
  }
1076
1258
  }
1077
1259
  if (Math.round(measuredWidth) !== curW) return // height only true at the width it was measured at
1260
+ // a settled height at the frame's OWN width is the one the next load should open at (sizes.ts);
1261
+ // a human-owned width is the board file's business (manual sizes save there)
1262
+ if (settled === true && node.sizeMode !== 'manual') persistHeight(mKey, H)
1078
1263
  if (Math.round(node.h) === H) return
1079
1264
  set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
1080
1265
  scheduleReflow()
@@ -1111,10 +1296,15 @@ export const useStore = create<State>((set, get) => {
1111
1296
  const d = defaultSize(f) // frames added mid-device-view get their default
1112
1297
  return { ...n, w: d.w, h: d.h }
1113
1298
  })
1114
- return { deviceView: name, dirty: true, baseLayout, nodes }
1299
+ // the snapshot's positions were laid out around the free-form heights: its laidOut goes and
1300
+ // comes back with it (null = not known - the next load falls back to the overlap check)
1301
+ const laid = name
1302
+ ? { baseLaidOut: s.deviceView === null ? s.laidOut : s.baseLaidOut }
1303
+ : s.baseLayout ? { laidOut: s.baseLaidOut, baseLaidOut: null } : { baseLaidOut: null }
1304
+ return { deviceView: name, dirty: true, baseLayout, nodes, ...laid }
1115
1305
  })
1116
1306
  if (name) get().runTidy() // restore must NOT tidy - it would destroy positions
1117
- else { scheduleSave(); roomForNotes() } // ...unless a note grew meanwhile and the restored rows stand under it
1307
+ else { scheduleSave(); roomForNotes(); recheckLayout() } // ...unless a note grew meanwhile, or a Doc changed size, under the restored rows
1118
1308
  },
1119
1309
  bumpRev(key) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, rev: (n.rev ?? 0) + 1 } : n)) })) },
1120
1310
  setThemeOn(key, theme) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, themeOn: theme } : n)) })) },
@@ -1328,6 +1518,7 @@ export const useStore = create<State>((set, get) => {
1328
1518
  const p = placed.find((x) => x.key === n.key)
1329
1519
  return p ? { ...n, x: p.x, y: p.y } : n
1330
1520
  }),
1521
+ laidOut: sizeRecord(nodes),
1331
1522
  dirty: true,
1332
1523
  }))
1333
1524
  scheduleSave()
@@ -1346,13 +1537,34 @@ export const useStore = create<State>((set, get) => {
1346
1537
  },
1347
1538
  dismissToast(id) { set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) })) },
1348
1539
  clearJamToasts() { set((s) => ({ toasts: s.toasts.filter((t) => !t.jam) })) },
1349
- setWorking(frames) {
1540
+ setWorkingFrom(m) {
1541
+ const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x: unknown): x is string => typeof x === 'string') : [])
1542
+ const o = (m && typeof m === 'object' ? m : {}) as { frames?: unknown; boards?: unknown; seq?: unknown }
1543
+ // a snapshot that left before a newer broadcast arrived is the past: it never undoes it
1544
+ const seq = typeof o.seq === 'number' && Number.isFinite(o.seq) ? o.seq : undefined
1545
+ if (seq !== undefined && seq < get().workingSeq) return
1546
+ if (seq !== undefined) set({ workingSeq: seq })
1547
+ get().setWorking(strings(o.frames), strings(o.boards))
1548
+ },
1549
+ async syncWorking() {
1550
+ if (PUBLISHED) return
1551
+ try {
1552
+ // a fresh page may ask before its double-submit cookie exists: the refusal primes it (api.ts),
1553
+ // so one more try carries it
1554
+ for (let i = 0; i < 2; i++) {
1555
+ const r = await fetch(`${ROUTE}/api/work`, { headers: { 'x-mv-c': csrf() } })
1556
+ if (r.ok) return get().setWorkingFrom(await r.json())
1557
+ if (r.status !== 403) return
1558
+ }
1559
+ } catch { /* the next broadcast heals it */ }
1560
+ },
1561
+ setWorking(frames, boards = []) {
1350
1562
  // preserve each frame's original start time; stamp now() only for newly-working frames -
1351
1563
  // the start phases the working animations so parallel frames never pulse in sync
1352
1564
  const prev = get().workingSince
1353
1565
  const workingSince: Record<string, number> = {}
1354
1566
  for (const f of frames) workingSince[f] = prev[f] ?? Date.now()
1355
- set({ working: frames, workingSince })
1567
+ set({ working: frames, workingSince, workingBoards: frames.length ? boards : [] })
1356
1568
  },
1357
1569
  spawn(frameId) {
1358
1570
  const { manifest, nodes, deviceView, baseLayout } = get()
@@ -1402,6 +1614,7 @@ export const useStore = create<State>((set, get) => {
1402
1614
  ...(deviceView ? { deviceView } : {}),
1403
1615
  ...(get().sceneRows?.length ? { sceneRows: get().sceneRows } : {}),
1404
1616
  ...(get().layoutRaw !== undefined ? { layout: get().layoutRaw } : {}),
1617
+ ...(get().laidOut && Object.keys(get().laidOut!).length && composed(get()) ? { laidOut: get().laidOut } : {}),
1405
1618
  // baseLayout entries for auto content nodes keep POSITIONS only - their
1406
1619
  // measured dimensions are transient and never reach the file
1407
1620
  ...(baseLayout ? {
@@ -1409,6 +1622,7 @@ export const useStore = create<State>((set, get) => {
1409
1622
  const n = nodes.find((x) => x.key === k)
1410
1623
  return n?.sizeMode === 'auto' ? [k, { x: b.x, y: b.y }] : [k, b]
1411
1624
  })),
1625
+ ...(get().baseLaidOut ? { baseLaidOut: get().baseLaidOut } : {}),
1412
1626
  } : {}),
1413
1627
  // only PINNED themes persist - inherited values follow viewTheme at load time.
1414
1628
  // Content frames in AUTO save no dimensions: measured sizes are
@@ -475,8 +475,18 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
475
475
  /* the settled statuses' fills, one value per theme: done is the content palette's green (Apple's
476
476
  systemGreen); archived is Apple's brown - its increased-contrast value on light, its default on
477
477
  dark, where the increased-contrast one turns peach - so it reads as the same brown box in both */
478
- .sh-app { --status-done: #34c759; --status-archived: #956d51 }
479
- .sh-app.dark { --status-done: #30d158; --status-archived: #b78a66 }
478
+ .sh-app { --status-done: #34c759; --status-archived: #956d51; --status-building: #0088ff; --live-glint: #b3dbff }
479
+ .sh-app.dark { --status-done: #30d158; --status-archived: #b78a66; --status-building: #0088ff; --live-glint: #d6ecff }
480
+ /* the live signal (spec 20): an agent working on what a sidebar row holds - its icon accent blue, a
481
+ highlight sweeping across it. The glint is the icon again, masked to a band that travels left to right */
482
+ .sh-panel .it .sh-live-ic { position: relative; display: inline-flex; flex: none }
483
+ .sh-panel .it .sh-live-ic[data-live-icon] svg { color: var(--status-building) } /* Marver's blue, whatever the mode */
484
+ .sh-panel .it .sh-live-ic .glint { position: absolute; inset: 0; display: inline-flex; pointer-events: none;
485
+ -webkit-mask-image: linear-gradient(100deg, transparent 38%, #000 50%, transparent 62%); mask-image: linear-gradient(100deg, transparent 38%, #000 50%, transparent 62%);
486
+ -webkit-mask-size: 300% 100%; mask-size: 300% 100%; animation: sh-live-glint 1.8s ease-in-out infinite }
487
+ .sh-panel .it .sh-live-ic[data-live-icon] .glint svg { color: var(--live-glint) }
488
+ @keyframes sh-live-glint { from { -webkit-mask-position: 100% 0; mask-position: 100% 0 } to { -webkit-mask-position: 0 0; mask-position: 0 0 } }
489
+ @media (prefers-reduced-motion: reduce) { .sh-panel .it .sh-live-ic .glint { display: none } }
480
490
  .sh-panel .it.board .st svg, .sh-panel .it.board.cur .st svg { color: inherit; margin: 0 }
481
491
  /* drag-to-reorder: a grab cursor, the lifted row dims, and a 2px accent rule marks the
482
492
  drop seam above or below the hovered row */
@@ -631,6 +641,13 @@ body.sh-space .sh-node { pointer-events: none } /* space-drag
631
641
  /* top-of-screen chrome flips its tooltip below the trigger */
632
642
  .sh-tip.below { transform: translate(-50%, 0); animation-name: sh-tip-pop-b }
633
643
  @keyframes sh-tip-pop-b { from { opacity: 0; transform: translate(-50%, 0) scale(.95) } }
644
+ .sh-tip.right { transform: translate(0, -50%); animation-name: sh-tip-pop-r }
645
+ @keyframes sh-tip-pop-r { from { opacity: 0; transform: translate(0, -50%) scale(.95) } }
646
+ /* a status's tooltip: the status, then where it came from - each piece of evidence on its own line */
647
+ .sh-tip .sh-tip-lines { display: flex; flex-direction: column; gap: 2px; max-width: 420px; max-height: calc(100vh - 32px); overflow: hidden; white-space: normal }
648
+ /* read by a screen reader, never seen: what a glyph says to the eye */
649
+ .sh-sr { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0 }
650
+ .sh-tip .sh-tip-lines small { opacity: .62; font-size: 11px; line-height: 1.35; overflow-wrap: anywhere }
634
651
  /* play chrome is fixed dark glass regardless of board theme - its tips pin the light bubble */
635
652
  .sh-tip.inv { background: #f4f4f5; color: #18181b }
636
653
  .sh-tip b { font-weight: 600 }
@@ -56,18 +56,22 @@ export const PROPOSED_PUBLISH: Partial<Record<BoardType, 'slides' | 'refs' | 'do
56
56
  export const HAS_STATUS: readonly BoardType[] = ['feature', 'project']
57
57
 
58
58
  /** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
59
- * record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
59
+ * record. `todo`, `backlog`, `in-progress` and `building` count only where there is no `context/`. */
60
60
  export const DECISIONS = ['archived', 'paused', 'blocked'] as const
61
- export const BY_HAND = ['in-progress', 'todo', 'backlog'] as const
61
+ export const BY_HAND = ['in-progress', 'building', 'todo', 'backlog'] as const
62
62
  export const STATUS_WORDS = [...DECISIONS, ...BY_HAND, 'done'] as const
63
63
  export type StatusWord = (typeof STATUS_WORDS)[number]
64
64
  export const readStatusWord = (v: unknown): StatusWord | undefined =>
65
65
  (STATUS_WORDS as readonly string[]).includes(v as string) ? (v as StatusWord) : undefined
66
66
  /** The statuses a person may set on a feature or project board, in the order a picker lists them:
67
- * the three decisions always; Backlog, To do and In progress only where there is no `context/`
68
- * (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
69
- export const settableStatuses = (contextPresent: boolean): StatusWord[] =>
70
- contextPresent ? ['blocked', 'paused', 'archived'] : ['backlog', 'todo', 'in-progress', 'blocked', 'paused', 'archived']
67
+ * the three decisions always; Backlog, To do, In progress and Building where there is no `context/`
68
+ * (with it they are read from the evidence). With it, In progress and Building where an open plan
69
+ * names the capability - choosing one writes that plan's `stage`, the evidence they are read from.
70
+ * Never Done - that is the shipped record's alone. */
71
+ export const settableStatuses = (contextPresent: boolean, openPlan = false): StatusWord[] =>
72
+ contextPresent
73
+ ? [...(openPlan ? (['in-progress', 'building'] as const) : []), 'blocked', 'paused', 'archived']
74
+ : ['backlog', 'todo', 'in-progress', 'building', 'blocked', 'paused', 'archived']
71
75
 
72
76
  /** A capability slug - the same grammar as a board name, so a feature board and its contract
73
77
  * share it. */