@marver-design/marver 0.23.1 → 0.25.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 (80) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +3 -1
  3. package/dist/anchor-DVV732zR.mjs +33 -0
  4. package/dist/anchor-check-BE5VVN6Q.mjs +135 -0
  5. package/dist/{bake-DQtnDB8-.mjs → bake-D8byeRzB.mjs} +1 -1
  6. package/dist/{boards-BRLnoTC3.mjs → board-tree-DRioF94d.mjs} +21 -277
  7. package/dist/boards-CGg6piKF.mjs +342 -0
  8. package/dist/{boards-Dv-Ipd8G.mjs → boards-Csxj2WJn.mjs} +23 -9
  9. package/dist/{build-_ndp_dXn.mjs → build-BHoWLvSj.mjs} +63 -37
  10. package/dist/cli.mjs +31 -17
  11. package/dist/{collab-mAiNZlDj.mjs → collab-gqNdScUE.mjs} +39 -9
  12. package/dist/{comments-DZyobpxG.mjs → comments-Zoch254k.mjs} +19 -1
  13. package/dist/{comments-BlqyZh3D.mjs → comments-pTLlhjh4.mjs} +150 -20
  14. package/dist/{config-BUKprFAp.mjs → config-cKgZBRj0.mjs} +1 -1
  15. package/dist/{context-CdkNiKdJ.mjs → context-D2ugHqwO.mjs} +17 -123
  16. package/dist/{daemon-BvMPdQ3k.mjs → daemon-Cl8KXGW4.mjs} +146 -64
  17. package/dist/{dev-Cf-4eqaC.mjs → dev-DJdgow47.mjs} +23 -11
  18. package/dist/{events-B3LBn74P.mjs → events-DnK_AnrW.mjs} +13 -15
  19. package/dist/imports-WBSnnHLb.mjs +143 -0
  20. package/dist/{init-hfZV7TwY.mjs → init-DO4DhUt_.mjs} +28 -6
  21. package/dist/link-C-qUIuKU.mjs +160 -0
  22. package/dist/{board-status-BZSzc9Hp.mjs → manifest-DnAte_fB.mjs} +537 -13
  23. package/dist/marks-DFuintmJ.mjs +50 -0
  24. package/dist/marks-koRsbHfe.mjs +397 -0
  25. package/dist/{marver-id-gate-B_idGdHm.mjs → marver-id-gate-DGANtVyC.mjs} +2 -2
  26. package/dist/perf-CCisg-ny.mjs +49 -0
  27. package/dist/perf-QJIWtTw1.mjs +68 -0
  28. package/dist/{plugin-DoXql0ZZ.mjs → plugin-CTyhjwoJ.mjs} +469 -82
  29. package/dist/{poster-XBmUvQiL.mjs → poster-D0cbV7hi.mjs} +1 -1
  30. package/dist/{profile-CrZohD6g.mjs → profile-Do0nGkXO.mjs} +1 -1
  31. package/dist/{publish-bakes-KKTHWqq3.mjs → publish-bakes--l8ot2eQ.mjs} +9 -9
  32. package/dist/{serve-z5qtj_wJ.mjs → serve-wv2QWdxB.mjs} +6 -6
  33. package/dist/{share-BD-wcDQq.mjs → share-ScamJcks.mjs} +1 -1
  34. package/dist/{shot-DOD8v6fJ.mjs → shot-CckrGW-J.mjs} +19 -11
  35. package/dist/{shot-Dh6fV1Lm.mjs → shot-jdO_B6Qw.mjs} +1 -1
  36. package/dist/{summary-C7CAypbB.mjs → summary-CrW88e3q.mjs} +1 -1
  37. package/dist/{sync-DoA1vf4u.mjs → sync-C3035OnJ.mjs} +18 -8
  38. package/dist/{work-ClFFq0Qh.mjs → work-CpJn1gwY.mjs} +8 -4
  39. package/dist/{work-ayuL_9Kk.mjs → work-GE88wb_3.mjs} +4 -4
  40. package/docs/boards-and-folders.md +70 -4
  41. package/docs/live-jam.md +12 -4
  42. package/package.json +1 -1
  43. package/src/client/frame-host/bridge.js +2 -1
  44. package/src/client/frame-host/inspect.js +195 -84
  45. package/src/client/frame-host/main.tsx +7 -2
  46. package/src/client/frame-host/registry.ts +5 -5
  47. package/src/client/shell/App.tsx +98 -30
  48. package/src/client/shell/BoardList.tsx +74 -16
  49. package/src/client/shell/Comments.tsx +79 -34
  50. package/src/client/shell/ContextMenu.tsx +5 -2
  51. package/src/client/shell/LockedApp.tsx +45 -12
  52. package/src/client/shell/Play.tsx +35 -32
  53. package/src/client/shell/Toolbar.tsx +3 -1
  54. package/src/client/shell/canvas/Canvas.tsx +2 -0
  55. package/src/client/shell/canvas/FrameNode.tsx +15 -5
  56. package/src/client/shell/canvas/sleep.ts +4 -3
  57. package/src/client/shell/canvas/updates.ts +55 -0
  58. package/src/client/shell/comments-store.ts +48 -17
  59. package/src/client/shell/goto.ts +11 -14
  60. package/src/client/shell/hash.ts +12 -5
  61. package/src/client/shell/icons.tsx +1 -2
  62. package/src/client/shell/legacy-links.ts +67 -0
  63. package/src/client/shell/marks-ui.tsx +117 -0
  64. package/src/client/shell/pin-layout.ts +37 -0
  65. package/src/client/shell/store.ts +377 -67
  66. package/src/client/shell/styles.css +32 -8
  67. package/src/client/stage/main.tsx +19 -2
  68. package/src/shared/anchor.ts +57 -0
  69. package/src/shared/board-tree.ts +27 -10
  70. package/src/shared/events.ts +19 -10
  71. package/src/shared/marks.ts +70 -0
  72. package/templates/AGENTS-embedded.md +34 -15
  73. package/templates/AGENTS-studio.md +34 -15
  74. package/templates/instructions/boards.md +9 -5
  75. package/templates/instructions/iterate.md +20 -10
  76. package/templates/instructions/jam.md +13 -4
  77. package/templates/instructions/publish.md +2 -1
  78. package/templates/instructions/reference/deck-story.md +2 -2
  79. package/dist/link-BodAbIQz.mjs +0 -132
  80. package/dist/manifest-TpfDWldB.mjs +0 -528
@@ -10,8 +10,8 @@ import shConfig from 'virtual:sh-config'
10
10
  import shData from 'virtual:sh-data'
11
11
 
12
12
  /** Published-build data. Non-null = static site: no API, no saves, no live events.
13
- * `names` is the switcher list (all-scenes only when actually published); `default`
14
- * is where `/` opens - never a synthesized aggregate of a filtered build. */
13
+ * `names` is the switcher list; `default` is where `/` opens - never a synthesized
14
+ * aggregate of a filtered build. */
15
15
  const DATA: {
16
16
  manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string
17
17
  /** the sidebar's folder tree over the published boards (0.16.0 bundles; older ones have none) */
@@ -28,8 +28,12 @@ const DATA: {
28
28
  bakes?: number
29
29
  /** content-frame heights, `scene/frame@width` -> px (design/boards/_sizes.json, published frames only) */
30
30
  sizes?: Record<string, number>
31
+ /** node key -> frame, off a leftover all-scenes.json, for old links naming keys (spec 26; shipped frames only) */
32
+ allScenesKeys?: Record<string, string>
31
33
  } | null = shData
32
34
 
35
+ /** An old All Scenes link's node keys a published bundle can still turn back into frames (legacy-links.ts). */
36
+ export const ALL_SCENES_KEYS: Record<string, string> = DATA?.allScenesKeys ?? {}
33
37
  /** The published textures' generation, or 0: the static index this build shipped is at /__mv/bakes/<gen>/index.json. */
34
38
  export const BAKES = DATA?.bakes ?? 0
35
39
  /** When a published bundle's statuses were read (spec 20) - absent in dev, where they are live. */
@@ -92,6 +96,15 @@ export interface Node {
92
96
  * as a failed frame; see canvas/ready-watch.ts). Transient - cleared on any real ready/error and
93
97
  * on every fresh navigation. */
94
98
  readyRetried?: boolean
99
+ /** spec 26: an update waits for this node - it reloads through the boot queue once the frame is on
100
+ * screen and not in use (canvas/updates.ts). Transient. */
101
+ stale?: boolean
102
+ /** spec 26: the revision of the document it shows - "epoch:doc", stamped by the dev server when it
103
+ * served the document, echoed by its sh:ready. A look counts only up to it. Transient. */
104
+ shown?: string
105
+ /** spec 26: the revision ("epoch:doc") a stale node waits for - a document showing it (or later)
106
+ * clears the wait, an older one keeps it. Transient. */
107
+ want?: string
95
108
  }
96
109
  /** A comment notification: a persistent bottom-right glass pill. Three kinds
97
110
  * share it - a Marver (agent) reply renders frame-first with the mark; a
@@ -102,6 +115,10 @@ export interface JamNote {
102
115
  frame?: string; frameTitle?: string; intent?: string
103
116
  kind?: 'mention' | 'reply' // absent = the agent pill
104
117
  author?: { name?: string; avatar?: string; id?: string; email?: string }
118
+ /** an agent REPLY (not a new question): a board's replies fold into one notice per round (spec 25) */
119
+ round?: boolean
120
+ /** the earlier replies of the round, under this one - View walks through them */
121
+ stack?: JamNote[]
105
122
  }
106
123
  export interface Toast { id: number; text: string; jam?: JamNote }
107
124
 
@@ -147,9 +164,12 @@ export const modeAllowed = (board: string, mode: 'present' | 'focus' | 'slides')
147
164
  export { cap, humanize } from './labels.ts'
148
165
  import { cap, humanize } from './labels.ts'
149
166
  import { canAutoReload } from './canvas/ready-watch.ts'
150
- import { buildTree, flatten, labelOf, toWire, TREE_PROTOCOL, type TreeItem } from '../../shared/board-tree.ts'
167
+ import { pumpUpdates } from './canvas/updates.ts'
168
+ import { archiveLast, buildTree, flatten, framesOn, labelOf, toWire, TREE_PROTOCOL, type TreeItem } from '../../shared/board-tree.ts'
169
+ import { UNPLACED } from './hash.ts'
151
170
  import type { BoardType, StatusWord } from '../../shared/board-types.ts'
152
171
  import type { Phase, Status } from '../../shared/status.ts'
172
+ import { isNew, type Marks } from '../../shared/marks.ts'
153
173
 
154
174
  /** The CAS tokens a tree write echoes: the sha256 of every board file as last seen, and of
155
175
  * the folder registry (null = there was no file). */
@@ -169,11 +189,11 @@ export interface BoardMeta {
169
189
  }
170
190
 
171
191
  /** The sidebar tree: root boards and folders in rank order, each folder's boards and
172
- * sub-folders inside (shared/board-tree.ts), plus the hashes it was built from. `all-scenes` is not in it - it
173
- * is pinned last by the callers. Throws on transport failure and on a malformed registry
174
- * (the server's 422 message) - callers keep their last known tree. */
192
+ * sub-folders inside (shared/board-tree.ts), plus the hashes it was built from. Throws on
193
+ * transport failure and on a malformed registry (the server's 422 message) - callers keep
194
+ * their last known tree. */
175
195
  export async function fetchBoardTree(): Promise<TreeSnapshot> {
176
- if (DATA) return { tree: DATA.tree ?? DATA.names.filter((n) => n !== 'all-scenes').map((n) => ({ kind: 'board', name: n })), base: { boards: {}, folders: null }, titles: DATA.titles ?? {}, meta: DATA.meta ?? {} }
196
+ if (DATA) return { tree: DATA.tree ?? DATA.names.map((n) => ({ kind: 'board', name: n })), base: { boards: {}, folders: null }, titles: DATA.titles ?? {}, meta: DATA.meta ?? {} }
177
197
  const [boards, reg] = await Promise.all([
178
198
  fetch(`${ROUTE}/api/boards`).then((r) => r.json()) as Promise<{ name: string; sha256: string; order?: number; folder?: string; title?: string; type?: BoardType; status?: BoardMeta['status'] | null; settable?: StatusWord[]; error?: string }[]>,
179
199
  fetch(`${ROUTE}/api/folders`).then(async (r) => {
@@ -200,21 +220,34 @@ export function rememberTitles(titles: Record<string, string>) {
200
220
  if (JSON.stringify(useStore.getState().boardTitles) !== JSON.stringify(titles)) useStore.setState({ boardTitles: titles })
201
221
  }
202
222
 
203
- /** Board names for switchers: the sidebar's reading order (folders flattened depth-first) and
204
- * the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
205
- * Throws on transport failure - callers keep their last known list. */
223
+ /** Board names for switchers: the sidebar's reading order (folders flattened depth-first); the
224
+ * first is the landing board. Throws on transport failure - callers keep their last known list. */
206
225
  export async function fetchBoardNames(): Promise<string[]> {
207
226
  if (DATA) return DATA.names
208
227
  const snap = await fetchBoardTree()
209
228
  rememberTitles(snap.titles)
210
229
  rememberMeta(snap.meta)
211
- return [...flatten(snap.tree), 'all-scenes']
230
+ return flatten(snap.tree)
231
+ }
232
+ /** Where the canvas opens with no link: the first board in sidebar order, else (no board yet) the
233
+ * Not on a board view - empty, on a canvas with no frames either. */
234
+ export const landingBoard = async (): Promise<string> => (await fetchBoardNames().catch(() => [] as string[]))[0] ?? UNPLACED
235
+ /** Which board shows which frame (spec 26, Part 7): every board in sidebar order with archive
236
+ * boards last, the live frames each shows, and the frames on no board - from the dev server, or
237
+ * off a published bundle (whose frames are all on a published board). Throws on transport failure. */
238
+ export async function fetchMembership(): Promise<{ boards: { name: string; frames: string[] }[]; unplaced: string[] }> {
239
+ if (!DATA) {
240
+ const r = await fetch(`${ROUTE}/api/membership`)
241
+ if (!r.ok) throw new Error(`membership ${r.status}`)
242
+ return r.json()
243
+ }
244
+ const live = DATA.manifest.frames.map((f) => f.id)
245
+ const names = archiveLast(DATA.names, (n) => n === 'archive' || DATA.meta?.[n]?.type === 'archive')
246
+ return { boards: names.map((name) => ({ name, frames: framesOn(DATA.boards[name], live) })), unplaced: [] }
212
247
  }
213
- /** Does the switcher carry the auto `all-scenes` board? Always in dev; published only when it shipped. */
214
- export const HAS_ALL_SCENES = !DATA || DATA.names.includes('all-scenes')
215
248
  /** Display name for a board: its title when one is set (subscribe to `boardTitles` to
216
- * re-render on change), else the Title-Cased slug ('all-scenes' reads "All Scenes"). */
217
- export const boardLabel = (n: string) => labelOf(n, useStore.getState().boardTitles[n])
249
+ * re-render on change), else the Title-Cased slug. */
250
+ export const boardLabel = (n: string) => (n === UNPLACED ? 'Not on a board' : labelOf(n, useStore.getState().boardTitles[n]))
218
251
  /** The canvas's name, as the sidebar heads it: the project's (share.name, else the repo folder). */
219
252
  export const CANVAS_NAME = CONFIG.projectName ? humanize(CONFIG.projectName) : 'Marver'
220
253
  /** The browser tab: the board, then the canvas - "Start here - Acme Studio" - so a row of canvas tabs
@@ -226,19 +259,30 @@ export const sceneLabel = (n: string) => labelOf(n, useStore.getState().manifest
226
259
  /** The double-submit CSRF token the owner gate wants echoed (same read as comments-store). */
227
260
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
228
261
  /** POST to an owner-gated dev API route, echoing the CSRF cookie the gate requires. */
262
+ /** The reload log (spec 26 Part 1): what this page saw boot or settle - best effort, dev only. */
263
+ const TAB = Math.random().toString(36).slice(2, 8)
264
+ /** Why a node's next document boots - a reload job, a reload by hand, the watchdog's retry; none known
265
+ * means a first load, or a document that reloaded itself (the reload log tells them apart). */
266
+ const reloadCause = new Map<string, 'job' | 'manual' | 'retry'>()
267
+ export const takeReloadCause = (key: string) => { const c = reloadCause.get(key); reloadCause.delete(key); return c }
268
+ export const logReload = (entry: Record<string, unknown>) => {
269
+ if (PUBLISHED) return
270
+ const body = { tab: TAB, ...entry }
271
+ // a page's very first request may go before its request cookie exists: a GET primes it, then once more
272
+ void postOwner('perf/reload', body).then((r) => (r.status === 403 ? fetch(`${ROUTE}/api/work`).then(() => postOwner('perf/reload', body)) : r)).catch(() => {})
273
+ }
229
274
  const postOwner = (path: string, body: unknown) =>
230
275
  fetch(`${ROUTE}/api/${path}`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify(body) })
231
276
 
232
- /** The frames a board pins, straight from its file (dev fetch / published inline) -
233
- * membership only, never a load. Cross-board data-goto asks "which board shows this
234
- * frame?" without touching the live board state. */
235
- export async function boardFrames(name: string): Promise<string[]> {
236
- const board: any = DATA
237
- ? DATA.boards[name]
238
- : (await (await fetch(`${ROUTE}/api/boards/${name}`)).json())?.board
239
- return Array.isArray(board?.nodes)
240
- ? board.nodes.map((n: any) => (n && typeof n.frame === 'string' ? n.frame : '')).filter(Boolean)
241
- : []
277
+ /** Add to board (the Not on a board view): these frames appended to a board's file, as
278
+ * `marver boards pin` does. The answer is said; the file change re-reads the sidebar and the view. */
279
+ export async function addToBoard(board: string, frames: string[]): Promise<void> {
280
+ const { toast } = useStore.getState()
281
+ try {
282
+ const r = await postOwner('boards/pin', { board, frames })
283
+ const body = await r.json().catch(() => ({})) as { added?: string[]; error?: string }
284
+ toast(r.ok ? `${body.added?.length ? 'pinned' : 'already'} on ${boardLabel(board)}` : body.error ?? `could not pin (${r.status})`)
285
+ } catch { toast('could not reach the dev server') }
242
286
  }
243
287
 
244
288
  const HEADER = 28
@@ -401,6 +445,32 @@ function defaultSize(frame: FrameEntry) {
401
445
  }
402
446
 
403
447
  let resizedInGesture = false
448
+ // set inside the store (they need it): a reload's height hold, and the marks-vs-documents check
449
+ let holdHeight: (key: string) => void = () => {}
450
+ let reconcile: () => void = () => {}
451
+ // sidebar marks: the fetch in flight, and acknowledgements the server has not confirmed yet
452
+ let marksSeq = 0
453
+ let marksTimer: ReturnType<typeof setTimeout> | undefined
454
+ const pendingSeen: Record<string, number> = {}
455
+ let pendingEpoch = ''
456
+ /** nodes (or 'stage') looked at before the first marks arrived (a link, a click, focus) - counted when they land */
457
+ const lookedEarly = new Set<string>()
458
+ /** a look at a node (or 'stage') whose new version was still loading: it completes when that version is up,
459
+ * within ARMED_MS of the look (spec 26) */
460
+ const armed = new Map<string, { until: number; board: string; frame: string }>()
461
+ const ARMED_MS = 10_000
462
+ /** The doc revision a node's document shows, in this epoch - -1 when unknown or from another one. */
463
+ /** "epoch:rev" stamps: does `a` show at least `b` (same epoch, revision as high)? */
464
+ const atLeast = (a: string | undefined, b: string) => {
465
+ const [ea, ra] = (a ?? '').split(':'), [eb, rb] = b.split(':')
466
+ return ea === eb && Number(ra) >= Number(rb)
467
+ }
468
+ /** The later of two waits (a new epoch replaces the old one's). */
469
+ const later = (a: string | undefined, b: string | undefined) => (!a || !b ? a ?? b : atLeast(a, b) ? a : b)
470
+ export const shownRev = (n: Node, m: Marks): number => {
471
+ const [epoch, rev] = (n.shown ?? '').split(':')
472
+ return epoch === m.epoch && rev !== undefined && /^\d+$/.test(rev) ? Number(rev) : -1
473
+ }
404
474
  /** Why a board's last load failed, from the server (a parse error names its line) - for its toast. */
405
475
  const loadErrors = new Map<string, string>()
406
476
  const whyNot = (name: string) => { const e = loadErrors.get(name); return e ? ` - ${e}` : '' }
@@ -433,7 +503,7 @@ interface State {
433
503
  play: { at: string; device: string; theme: string; focus?: boolean; deep?: boolean; slides?: boolean } | null
434
504
  gesture: boolean // a frame drag/resize is in progress - canvas panning is disabled
435
505
  laser: boolean // laser/inspect mode: frames outline their structure
436
- board: string // active board name; 'all-scenes' is the auto board
506
+ board: string // active board name; UNPLACED is the Not on a board view
437
507
  boardAuto: boolean // auto boards gain new frames on arrival; curated boards never do
438
508
  deviceView: string | null // board-wide device preview (viewport name), null = free-form layout
439
509
  sceneRows: string[][] | null // LEGACY scene arrangement; still round-trips through save
@@ -447,13 +517,13 @@ interface State {
447
517
  toasts: Toast[]
448
518
  boardHash: string | null // sha256 of the board file on disk, when materialized
449
519
  dirty: boolean
450
- // A6/A7 controlled HMR (transient, never persisted): a frame the user is actively using
451
- // (interact/play target, mid-gesture, laser/comment engaged) is "leased" - a hot update to
452
- // it is DEFERRED (coalesced to the latest revision) until a safe point, so an agent edit
453
- // never yanks the user out of their flow.
454
- pendingFrameRevisions: Record<string, string> // frameId -> latest deferred revision
520
+ // Calm updates (spec 26, transient): an edit marks its frames' nodes stale; a stale node reloads
521
+ // through the boot queue once it is on screen and not in use - a frame the user is actively using
522
+ // (interact/play target, mid-gesture, laser/comment engaged) is "leased" and waits for a safe point.
455
523
  externalLeases: Record<string, { laser?: true; comment?: true }> // nodeKey -> transient engagement
456
524
  playUpdateRevision: string | null // a revision arrived while play is open
525
+ /** the frame the play/focus stage committed last, and the revision it shows (sh:stage-shown) */
526
+ stageShown: { at: string; shown: string } | null
457
527
  playNav: number // bumps to reload the play stage on demand
458
528
  pathPulse: number // bumps on each successful path copy - flashes the toolbar icon into a check
459
529
  imagePulse: number // bumps on each successful image copy - same flash, the images-square icon
@@ -483,9 +553,10 @@ interface State {
483
553
  setPlay(p: State['play']): void
484
554
  setGesture(g: boolean): void
485
555
  setLaser(on: boolean): void
486
- invalidateFrames(frameIds: string[], revision: string): void
556
+ invalidateFrames(frameIds: string[], revision: string, docs?: { epoch?: string; docs?: Record<string, number> }): void
487
557
  setExternalLease(nodeKey: string, reason: 'laser' | 'comment', on: boolean): void
488
- flushFrameUpdates(frameIds?: string[]): void
558
+ /** A safe point (a lease ended, a gesture ended): stale nodes may reload now. */
559
+ flushFrameUpdates(): void
489
560
  applyPlayUpdate(): void
490
561
  moveSelectedBy(dx: number, dy: number, starts: Record<string, { x: number; y: number }>): void
491
562
  setSelectedTheme(theme: string): void
@@ -518,6 +589,8 @@ interface State {
518
589
  toast(text: string): void
519
590
  jamToast(note: JamNote): void
520
591
  dismissToast(id: number): void
592
+ /** View on a notice: a round's notice moves to its next reply, any other one goes. */
593
+ advanceToast(id: number): void
521
594
  clearJamToasts(): void
522
595
  /** Frames Marver is editing right now (Live Jam presence) - drives the working glow. */
523
596
  working: string[]
@@ -529,17 +602,32 @@ interface State {
529
602
  setWorkingFrom(m: unknown): void
530
603
  /** Fetch what is lit now (dev only) - the snapshot behind the broadcasts. */
531
604
  syncWorking(): Promise<void>
605
+ /** Sidebar marks (spec 25): what changed since you looked - null on a published canvas. */
606
+ marks: Marks | null
607
+ syncMarks(): Promise<void>
608
+ /** Mark all as seen: clear these frames' "new", here and on disk, whatever is loaded. */
609
+ markSeen(frameIds: readonly string[]): void
610
+ /** You looked at these nodes (or 'stage'): each clears its frame's "new" up to the revision it shows -
611
+ * one whose new version is not up yet waits for it (`rearm` false: a check, not a new look). */
612
+ look(keys: readonly string[], rearm?: boolean): void
613
+ /** A node's document reported the revision it shows (sh:ready). */
614
+ setShown(key: string, shown: string): void
615
+ /** A stale node's turn: it reloads now, its height held until it settles (canvas/updates.ts). */
616
+ startReload(key: string): void
532
617
  /** Boards showing a working frame - their sidebar icon shimmers while an agent works. */
533
618
  workingBoards: string[]
534
619
  /** The place in the server's order of the activity last applied - an older answer is dropped. */
535
620
  workingSeq: number
536
621
  spawn(frameId: string): Node | null
622
+ /** The Not on a board view follows its list in place: frames that left go, new ones join - the
623
+ * frames that stay keep their documents (no reload, no lost input). */
624
+ syncUnplaced(ids: readonly string[]): void
537
625
  save(): Promise<boolean>
538
626
  }
539
627
 
540
628
  /** A6: is any node of this frame in active use, so a hot update must DEFER? Frame-scoped -
541
629
  * if the same frame is placed twice and one copy is active, both stay on the same revision. */
542
- function frameIsLeased(frameId: string, s: State): boolean {
630
+ export function frameIsLeased(frameId: string, s: State): boolean {
543
631
  return s.nodes.some((n) =>
544
632
  n.frame === frameId && n.status !== 'error' && (
545
633
  s.interact === n.key ||
@@ -599,6 +687,8 @@ export const useStore = create<State>((set, get) => {
599
687
  const since = cameraSince ?? Date.now()
600
688
  if (canvasCtl.cameraBusy() && Date.now() - since < REFLOW_CAMERA_WAIT) { scheduleReflow(check ?? undefined, 60, since); return }
601
689
  if (check && !check()) return
690
+ for (const k of [...holds.keys()]) if (!s.nodes.some((n) => n.key === k && !n.missing)) letGo(k, false) // gone: no longer in the batch
691
+ if (holds.size) { reflowOwed = true; return } // a batch is reloading: the rows move once, when it lets go
602
692
  // content moved the rows, not the human: hold what they are looking at still (Canvas.tsx)
603
693
  if (composed(s)) { canvasCtl.holdView(); s.runTidy() }
604
694
  }, delay)
@@ -607,6 +697,63 @@ export const useStore = create<State>((set, get) => {
607
697
  * note is made here; a board the human placed by hand is never moved (spec 18, 0.19.1). */
608
698
  const composed = (s: { layout: BoardLayout | null; sceneRows: string[][] | null; boardAuto: boolean }) => !!(s.layout || s.sceneRows?.length || s.boardAuto)
609
699
  const cramped = () => { const s = get(); return !!s.manifest && notesCramped(s.nodes, s.manifest) }
700
+ // Calm updates (spec 26): a node reloading keeps its height until its frame says it has settled
701
+ // (or HOLD_MS pass); a provisional measure in either direction waits, the last one is kept. The
702
+ // board reflows once, when the last held node lets go - never once per frame of a burst.
703
+ const HOLD_MS = 4000
704
+ const holds = new Map<string, { timer: ReturnType<typeof setTimeout>; at: number; last?: Parameters<State['measureNode']> }>()
705
+ let reflowOwed = false
706
+ holdHeight = (key) => {
707
+ const was = holds.get(key)
708
+ if (was) clearTimeout(was.timer)
709
+ holds.set(key, { timer: setTimeout(() => letGo(key, true), HOLD_MS), at: performance.now() })
710
+ }
711
+ const letGo = (key: string, apply: boolean) => {
712
+ const h = holds.get(key)
713
+ if (!h) return
714
+ clearTimeout(h.timer)
715
+ holds.delete(key)
716
+ if (apply && h.last) get().measureNode(...h.last)
717
+ if (!holds.size && reflowOwed) { reflowOwed = false; scheduleReflow() }
718
+ }
719
+ const dropHolds = () => { for (const h of holds.values()) clearTimeout(h.timer); holds.clear(); reflowOwed = false }
720
+ /** A content measure moved the rows: once, after the last held node lets go. */
721
+ const reflowAfterHolds = () => { if (holds.size) reflowOwed = true; else scheduleReflow() }
722
+
723
+ // Marks (spec 26): a node that shows an older revision than its frame's `doc` has missed an update
724
+ // (an event lost while disconnected, an edit that landed while it loaded): it goes stale. The
725
+ // snapshot is the truth; events only make it faster.
726
+ reconcile = () => {
727
+ const s = get(), m = s.marks
728
+ if (!m) return
729
+ let any = false
730
+ const nodes = s.nodes.map((n) => {
731
+ if (n.stale || n.status !== 'ready' || n.missing || !n.shown) return n
732
+ if (shownRev(n, m) >= (m.doc[n.frame] ?? 0)) return n
733
+ any = true
734
+ return { ...n, stale: true, want: later(n.want, `${m.epoch}:${m.doc[n.frame] ?? 0}`) }
735
+ })
736
+ if (any) { set({ nodes }); pumpUpdates() }
737
+ // the stage too: one that missed an update (a lost event) offers Update
738
+ const st = s.stageShown, f = st?.at
739
+ if (s.play && st && f && !s.playUpdateRevision) {
740
+ const [e, r] = st.shown.split(':')
741
+ if (e !== m.epoch || Number(r) < (m.doc[f] ?? 0)) set({ playUpdateRevision: 'missed' })
742
+ }
743
+ }
744
+
745
+ /** Acknowledge these revisions: here at once, and on disk - refused there from another epoch. */
746
+ const ack = (seen: Record<string, number>) => {
747
+ const m = get().marks
748
+ if (!m || !Object.keys(seen).length) return
749
+ Object.assign(pendingSeen, seen)
750
+ set({ marks: { ...m, seen: { ...m.seen, ...seen } } })
751
+ void postOwner('marks/seen', { epoch: m.epoch, frames: seen })
752
+ // kept once confirmed too (revisions only ever rise): an answer that left before this one cannot undo it
753
+ .then((r) => { if (!r.ok) throw new Error(String(r.status)) })
754
+ .catch(() => { for (const [id, at] of Object.entries(seen)) if (pendingSeen[id] === at) delete pendingSeen[id]; void get().syncMarks() })
755
+ }
756
+
610
757
  /** A note may have landed with no room (a frame note via the manifest, a scene note via
611
758
  * sh:scenes, either merged late by boot/switch): a composed board re-applies its layout. */
612
759
  const roomForNotes = () => { if (composed(get()) && cramped()) scheduleReflow(cramped) }
@@ -703,7 +850,7 @@ export const useStore = create<State>((set, get) => {
703
850
  }
704
851
  let nodes: Node[] = []
705
852
  let boardHash: string | null = null
706
- let boardAuto = boardName === 'all-scenes'
853
+ let boardAuto = false
707
854
  let deviceView: string | null = null
708
855
  let sceneRows: string[][] | null = null
709
856
  let layout: BoardLayout | null = null
@@ -715,7 +862,13 @@ export const useStore = create<State>((set, get) => {
715
862
  // published build: boards come from the inlined data; absent = fresh (the 404 path)
716
863
  let loaded: { board: any; sha256: string } | 'fresh' | null
717
864
  if (DATA) loaded = DATA.boards[boardName] ? { board: DATA.boards[boardName], sha256: 'published' } : 'fresh'
718
- else {
865
+ // the Not on a board view: a board of the frames no board shows, never saved - laid out
866
+ // fresh on every load (no hash) in one band of their scenes, its keys minted like any keyless node's
867
+ else if (boardName === UNPLACED) {
868
+ const m = await fetchMembership().catch(() => null)
869
+ const scenes = [...new Set(manifest.frames.filter((f) => m?.unplaced.includes(f.id)).map((f) => f.scene))]
870
+ loaded = m ? { board: { nodes: m.unplaced.map((frame) => ({ frame })), ...(scenes.length ? { layout: { rows: [scenes] } } : {}) }, sha256: '' } : null
871
+ } else {
719
872
  const res = await fetch(`${ROUTE}/api/boards/${boardName}`)
720
873
  if (res.ok) {
721
874
  const body = await res.json()
@@ -809,11 +962,11 @@ export const useStore = create<State>((set, get) => {
809
962
  // frames not on the board yet → auto boards only (a curated board shows exactly its list).
810
963
  // Grouped newcomers land beside their siblings (like the live JOIN); ungrouped ones
811
964
  // go past the board's right edge (the live JOIN flows them below) - NEVER at (0,0)
812
- // (the published all-scenes bug: frames created after the board file was last
965
+ // (the old published everything-board bug: frames created after the board file was last
813
966
  // saved piled up at the origin)
814
967
  if (boardAuto) {
815
968
  const placed = new Set(nodes.map((n) => n.frame))
816
- // newcomers get deterministic keys too - on published auto boards (all-scenes)
969
+ // newcomers get deterministic keys too - on a published auto board
817
970
  // this path mints EVERY key, every visit, and comments anchor to them
818
971
  const haveKeys = new Set(nodes.map((n) => n.key))
819
972
  const mint = (frame: string) => {
@@ -877,9 +1030,9 @@ export const useStore = create<State>((set, get) => {
877
1030
 
878
1031
  return {
879
1032
  manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
880
- 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,
1033
+ board: DATA?.default ?? UNPLACED, boardAuto: false, deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null, laidOut: null, baseLaidOut: null,
881
1034
  panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, workingBoards: [], workingSeq: -1, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
882
- pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
1035
+ externalLeases: {}, playUpdateRevision: null, stageShown: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
883
1036
 
884
1037
  async boot(mayCommit) {
885
1038
  const seq = ++loadSeq
@@ -892,7 +1045,7 @@ export const useStore = create<State>((set, get) => {
892
1045
  if (get().board !== boardName || editRev !== revAtStart || (mayCommit && !mayCommit())) return false
893
1046
  const live = get().manifest // a WS manifest update may have landed mid-fetch
894
1047
  set(next)
895
- cancelReflow()
1048
+ cancelReflow(); dropHolds(); reloadCause.clear()
896
1049
  if (next.dirty) scheduleSave() // load-time prune must reach the disk
897
1050
  if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
898
1051
  else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } }) // an sh:scenes that landed mid-fetch outranks the file we read
@@ -929,7 +1082,7 @@ export const useStore = create<State>((set, get) => {
929
1082
  ++loadSeq // invalidate any in-flight boot of the old board
930
1083
  const live = get().manifest // a WS manifest update may have landed mid-load
931
1084
  set({ board: name, interact: null, ...next })
932
- cancelReflow()
1085
+ cancelReflow(); dropHolds(); reloadCause.clear()
933
1086
  if (next.dirty) scheduleSave() // load-time prune must reach the disk
934
1087
  if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
935
1088
  else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })
@@ -1123,6 +1276,10 @@ export const useStore = create<State>((set, get) => {
1123
1276
  n.h = vp?.height ?? d.h
1124
1277
  }
1125
1278
  if (arrived) { delete n.sizeFallback; n.readyRetried = false } // a fresh mount earns a fresh allowance
1279
+ // gone or back, the node has no document: an update waiting for the old one is void, and the
1280
+ // next document boots fresh through admission (a reload job must never stand in for it)
1281
+ delete n.stale; delete n.shown; delete n.want
1282
+ if (missing) letGo(n.key, false)
1126
1283
  n.missing = missing
1127
1284
  changed = true
1128
1285
  }
@@ -1164,6 +1321,7 @@ export const useStore = create<State>((set, get) => {
1164
1321
  },
1165
1322
 
1166
1323
  removeNode(key) {
1324
+ letGo(key, false) // a node that goes holds no batch
1167
1325
  set((s) => ({
1168
1326
  nodes: s.nodes.filter((n) => n.key !== key),
1169
1327
  selection: s.selection.filter((k) => k !== key),
@@ -1240,6 +1398,14 @@ export const useStore = create<State>((set, get) => {
1240
1398
  // a Doc that reports IS one, whatever the last load's scan said (it arrived since): its heights
1241
1399
  // count until the next load re-reads the sources
1242
1400
  measuring?.add(f.id)
1401
+ // held while it reloads (spec 26): only a settled measure lands now; the last other one waits
1402
+ const held = holds.get(key)
1403
+ if (held) {
1404
+ if (settled !== true) { held.last = [key, frameId, ownWidth, measuredWidth, height, settled]; return }
1405
+ holds.delete(key); clearTimeout(held.timer)
1406
+ logReload({ kind: 'settled', node: key, frame: frameId, ms: performance.now() - held.at })
1407
+ if (!holds.size && reflowOwed) { reflowOwed = false; scheduleReflow() }
1408
+ }
1243
1409
  // Generous cap: a reference doc with many screenshots is legitimately very tall and must fit in
1244
1410
  // FULL (this was 2.5x a viewport ~= 2700px, which clipped image-heavy docs). Still bounded so a
1245
1411
  // broken measurement can't mint an infinite frame.
@@ -1263,7 +1429,7 @@ export const useStore = create<State>((set, get) => {
1263
1429
  // Doc layout changed (document<->wide): adopt the new own width first; the
1264
1430
  // iframe resizes, remeasures, and the height commits on the next message
1265
1431
  set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
1266
- scheduleReflow()
1432
+ reflowAfterHolds()
1267
1433
  return
1268
1434
  }
1269
1435
  }
@@ -1273,7 +1439,7 @@ export const useStore = create<State>((set, get) => {
1273
1439
  if (settled === true && node.sizeMode !== 'manual') persistHeight(mKey, H)
1274
1440
  if (Math.round(node.h) === H) return
1275
1441
  set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
1276
- scheduleReflow()
1442
+ reflowAfterHolds()
1277
1443
  },
1278
1444
  noteMeasured(key, height) {
1279
1445
  // the column's height is its content's - the layout learns it here, and a composed board
@@ -1323,6 +1489,8 @@ export const useStore = create<State>((set, get) => {
1323
1489
  // any real ready/error resets the one-shot retry allowance, so a later manual reload or a
1324
1490
  // fresh manifest earns its own auto-retry again
1325
1491
  set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, status, error, readyRetried: false } : n)) }))
1492
+ if (status === 'error') letGo(key, false) // an error holds no batch
1493
+ if (status !== 'loading') pumpUpdates() // a slot, or a lease, may be free
1326
1494
  },
1327
1495
  // Reload a frame on a fresh rev-stamped URL (dodges a poisoned-cache document, #20). The
1328
1496
  // watchdog calls this with automatic=true after a silent deadline: it fires at most once per
@@ -1332,6 +1500,7 @@ export const useStore = create<State>((set, get) => {
1332
1500
  const n = get().nodes.find((x) => x.key === key)
1333
1501
  if (!n) return
1334
1502
  if (automatic && !canAutoReload(n)) return
1503
+ reloadCause.set(key, automatic ? 'retry' : 'manual')
1335
1504
  bumpManifestRev()
1336
1505
  set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
1337
1506
  ? { ...x, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: automatic }
@@ -1348,6 +1517,8 @@ export const useStore = create<State>((set, get) => {
1348
1517
  : [key]
1349
1518
  return { selection, interact: s.interact && selection.includes(s.interact) ? s.interact : null }
1350
1519
  })
1520
+ // selecting a frame is looking at it, every time - even one already selected (spec 25)
1521
+ if (key != null) get().look([key])
1351
1522
  },
1352
1523
  // scoped device sizing: only the selected frames change; null restores their defaults.
1353
1524
  // Always followed by a tidy - a preset change must never scramble the layout.
@@ -1384,6 +1555,8 @@ export const useStore = create<State>((set, get) => {
1384
1555
  const valid = keys.filter((k) => s.nodes.some((n) => n.key === k))
1385
1556
  return { selection: valid, interact: s.interact && valid.includes(s.interact) ? s.interact : null }
1386
1557
  })
1558
+ // a frame link, a scene's name: the frames brought in front of you are looked at (⌘A is selectAll - not a look)
1559
+ get().look(get().selection)
1387
1560
  },
1388
1561
  // interact is a ONE-frame mode: entering it collapses any multi-selection to the
1389
1562
  // interacted frame (a 4-frame selection double-clicked otherwise leaves all four
@@ -1415,32 +1588,43 @@ export const useStore = create<State>((set, get) => {
1415
1588
  }
1416
1589
  if (!gesture) get().flushFrameUpdates() // A6: gesture end is a safe point for deferred updates
1417
1590
  },
1418
- // A6/A7: apply a controlled hot update. A leased frame's revision is deferred (coalesced to
1419
- // the latest) and applied at the next safe point; an idle frame reloads now via its nav nonce.
1420
- invalidateFrames(frameIds, revision) {
1591
+ // Calm updates (spec 26): an edit reached these frames. Their nodes that show a document go
1592
+ // stale and reload through the boot queue - on screen first, never while in use; one still loading
1593
+ // its first document is checked against the marks when it is ready (setShown).
1594
+ invalidateFrames(frameIds, revision, docs) {
1421
1595
  const ids = new Set(frameIds.filter((x) => typeof x === 'string'))
1422
1596
  if (!ids.size) return
1423
- bumpManifestRev()
1424
1597
  const s = get()
1425
- const pending = { ...s.pendingFrameRevisions }
1426
- const nodes = s.nodes.map((n) => {
1427
- if (!ids.has(n.frame)) return n
1428
- if (frameIsLeased(n.frame, s)) { pending[n.frame] = revision; return n }
1429
- return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false }
1430
- })
1431
- set({ nodes, pendingFrameRevisions: pending, ...(s.play ? { playUpdateRevision: revision } : {}) })
1598
+ // every document of these frames is behind - one loading too (one running, one waiting): a document
1599
+ // that shows the revision the edit made clears it when it is ready (setShown)
1600
+ const want = (f: string) => (docs?.epoch && typeof docs.docs?.[f] === 'number' ? `${docs.epoch}:${docs.docs[f]}` : undefined)
1601
+ const nodes = s.nodes.map((n) => (ids.has(n.frame) && !n.missing ? { ...n, stale: true, want: later(n.want, want(n.frame)) } : n))
1602
+ set({ nodes, ...(s.play ? { playUpdateRevision: revision } : {}) })
1603
+ pumpUpdates()
1432
1604
  },
1433
- flushFrameUpdates(frameIds) {
1434
- const s = get()
1435
- const ids = (frameIds ?? Object.keys(s.pendingFrameRevisions)).filter((id) => s.pendingFrameRevisions[id] && !frameIsLeased(id, s))
1436
- if (!ids.length) return
1605
+ flushFrameUpdates() { pumpUpdates() },
1606
+ startReload(key) {
1607
+ const n = get().nodes.find((x) => x.key === key)
1608
+ if (!n) return
1609
+ reloadCause.set(key, 'job')
1437
1610
  bumpManifestRev()
1438
- const apply = new Set(ids)
1439
- const pending = { ...s.pendingFrameRevisions }
1440
- for (const id of ids) delete pending[id]
1441
- const nodes = s.nodes.map((n) => apply.has(n.frame)
1442
- ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false } : n)
1443
- set({ nodes, pendingFrameRevisions: pending })
1611
+ holdHeight(key)
1612
+ set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
1613
+ ? { ...x, stale: false, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: false }
1614
+ : x)) }))
1615
+ },
1616
+ setShown(key, shown) {
1617
+ set((s) => ({ nodes: s.nodes.map((x) => {
1618
+ if (x.key !== key) return x
1619
+ // a document that shows the revision its node waits for (or later) clears the wait; an older
1620
+ // one - a reload that started before the edit - keeps it, so the edit still lands
1621
+ const n = { ...x, shown }
1622
+ if (n.want) { if (atLeast(shown, n.want)) { n.stale = false; delete n.want } else n.stale = true }
1623
+ return n
1624
+ }) }))
1625
+ pumpUpdates()
1626
+ reconcile()
1627
+ if (armed.has(key)) get().look([key], false) // a look you made while it loaded
1444
1628
  },
1445
1629
  setExternalLease(nodeKey, reason, on) {
1446
1630
  set((s) => {
@@ -1455,7 +1639,11 @@ export const useStore = create<State>((set, get) => {
1455
1639
  applyPlayUpdate() {
1456
1640
  if (!get().playUpdateRevision) return
1457
1641
  bumpManifestRev()
1458
- set((s) => ({ playUpdateRevision: null, playNav: s.playNav + 1 }))
1642
+ set((s) => ({ playUpdateRevision: null, playNav: s.playNav + 1, stageShown: null })) // counted again once the new stage commits
1643
+ // pending until the new stage commits: one that never reports (its document failed before it
1644
+ // could) offers Update again
1645
+ const nav = get().playNav
1646
+ setTimeout(() => { const s = get(); if (s.play && s.playNav === nav && !s.stageShown && !s.playUpdateRevision) set({ playUpdateRevision: 'retry' }) }, 15_000)
1459
1647
  },
1460
1648
  setScale(scale) { set({ scale }) },
1461
1649
  pulsePath() { set((s) => ({ pathPulse: s.pathPulse + 1 })) },
@@ -1544,9 +1732,30 @@ export const useStore = create<State>((set, get) => {
1544
1732
  jamToast(note) {
1545
1733
  const id = ++toastSeq
1546
1734
  const text = note.kind === 'mention' ? 'You were mentioned' : note.kind === 'reply' ? 'New reply' : 'Marver replied'
1547
- set((s) => ({ toasts: [...s.toasts.filter((t) => t.jam?.threadId !== note.threadId), { id, text, jam: note }].slice(-8) }))
1735
+ set((s) => {
1736
+ // one notice per board per round: an agent reply folds into that board's open notice (spec 25)
1737
+ // a round ends after ten quiet minutes: a later reply opens a fresh notice
1738
+ const prev = note.round ? s.toasts.find((t) => t.jam?.round && t.jam.board === note.board && note.ts - t.jam.ts < 600_000) : undefined
1739
+ const jam = prev ? { ...note, stack: [...(prev.jam!.stack ?? []), { ...prev.jam!, stack: undefined }].filter((n) => n.threadId !== note.threadId) } : note
1740
+ // a notice whose top reply is this thread steps down to the replies under it, never loses them
1741
+ const others = s.toasts.flatMap((t) => {
1742
+ if (t === prev) return []
1743
+ const rest = (t.jam?.stack ?? []).filter((n) => n.threadId !== note.threadId)
1744
+ if (t.jam?.threadId !== note.threadId) return [t.jam?.stack ? { ...t, jam: { ...t.jam, stack: rest } } : t]
1745
+ return rest.length ? [{ ...t, jam: { ...rest[rest.length - 1], stack: rest.slice(0, -1) } }] : []
1746
+ })
1747
+ return { toasts: [...others, { id, text, jam }].slice(-8) }
1748
+ })
1548
1749
  },
1549
1750
  dismissToast(id) { set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) })) },
1751
+ advanceToast(id) {
1752
+ // a merged round notice steps to its next reply; any other notice goes
1753
+ set((s) => ({ toasts: s.toasts.flatMap((t) => {
1754
+ if (t.id !== id) return [t]
1755
+ const rest = t.jam?.stack ?? []
1756
+ return rest.length ? [{ ...t, jam: { ...rest[rest.length - 1], stack: rest.slice(0, -1) } }] : []
1757
+ }) }))
1758
+ },
1550
1759
  clearJamToasts() { set((s) => ({ toasts: s.toasts.filter((t) => !t.jam) })) },
1551
1760
  setWorkingFrom(m) {
1552
1761
  const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x: unknown): x is string => typeof x === 'string') : [])
@@ -1557,6 +1766,77 @@ export const useStore = create<State>((set, get) => {
1557
1766
  if (seq !== undefined) set({ workingSeq: seq })
1558
1767
  get().setWorking(strings(o.frames), strings(o.boards))
1559
1768
  },
1769
+ marks: null,
1770
+ // one fetch per burst (activity, board edits, file changes), and only the newest answer lands;
1771
+ // acknowledgements still in flight are kept over any answer that predates them
1772
+ async syncMarks() {
1773
+ if (PUBLISHED) return
1774
+ clearTimeout(marksTimer)
1775
+ await new Promise<void>((done) => { marksTimer = setTimeout(done, 200) })
1776
+ const seq = ++marksSeq
1777
+ try {
1778
+ for (let i = 0; i < 2; i++) { // the first ask may prime the CSRF cookie (as syncWorking)
1779
+ const r = await fetch(`${ROUTE}/api/marks`, { headers: { 'x-mv-c': csrf() } })
1780
+ if (seq !== marksSeq) return
1781
+ if (r.ok) {
1782
+ const m = await r.json() as Marks | null
1783
+ if (seq !== marksSeq || !m) return
1784
+ // a new epoch (the marks started over): what this page held belongs to the old one
1785
+ if (m.epoch !== pendingEpoch) { for (const id of Object.keys(pendingSeen)) delete pendingSeen[id]; armed.clear(); pendingEpoch = m.epoch }
1786
+ const seen = { ...m.seen }
1787
+ for (const [id, at] of Object.entries(pendingSeen)) seen[id] = Math.max(seen[id] ?? 0, at)
1788
+ set({ marks: { ...m, seen } })
1789
+ reconcile()
1790
+ if (lookedEarly.size) { const early = [...lookedEarly]; lookedEarly.clear(); get().look(early) }
1791
+ if (armed.size) get().look([...armed.keys()], false) // a look that waited on a newer version than the page knew
1792
+ return
1793
+ }
1794
+ if (r.status !== 403) return
1795
+ }
1796
+ } catch { /* the next broadcast heals it */ }
1797
+ },
1798
+ markSeen(frameIds) {
1799
+ const m = get().marks
1800
+ if (!m) return
1801
+ ack(Object.fromEntries(frameIds.filter((id) => isNew(m, id)).map((id) => [id, m.changed[id] ?? 0])))
1802
+ },
1803
+ look(keys, rearm = true) {
1804
+ const s = get(), m = s.marks
1805
+ if (!m) { if (!PUBLISHED) for (const k of keys) lookedEarly.add(k); return }
1806
+ // the revision a node (or the stage) shows of its frame: -1 while it does not show the frame's last
1807
+ // edit (stale, loading, an older document) - a look counts up to it, never past it
1808
+ const upTo = (k: string, f: string): number => {
1809
+ const doc = m.doc[f] ?? 0
1810
+ if (k === 'stage') {
1811
+ const st = s.stageShown
1812
+ if (!s.play || s.playUpdateRevision || !st) return -1
1813
+ const [e, r] = st.shown.split(':')
1814
+ return e === m.epoch && Number(r) >= doc ? Number(r) : -1
1815
+ }
1816
+ const n = s.nodes.find((x) => x.key === k)
1817
+ if (!n || n.status !== 'ready' || n.stale) return -1
1818
+ const r = shownRev(n, m)
1819
+ return r >= doc ? r : -1
1820
+ }
1821
+ const now = Date.now(), seen: Record<string, number> = {}
1822
+ for (const k of keys) {
1823
+ const f = k === 'stage' ? s.stageShown?.at : s.nodes.find((n) => n.key === k)?.frame
1824
+ const a = armed.get(k)
1825
+ // a remembered look holds for its own frame, on its own board, for ARMED_MS
1826
+ if (a && (a.until <= now || a.board !== s.board || a.frame !== f)) armed.delete(k)
1827
+ if (!rearm && !armed.has(k)) continue
1828
+ if (!f) { armed.delete(k); continue }
1829
+ const r = upTo(k, f)
1830
+ // what you saw: the last change as the page knows it - or the revision on screen when the document
1831
+ // already shows one the page has not heard of yet (everything up to it is there)
1832
+ const saw = Math.max(m.changed[f] ?? 0, r)
1833
+ if (saw <= (m.seen[f] ?? 0)) { armed.delete(k); continue }
1834
+ if (r < 0) { if (rearm) armed.set(k, { until: now + ARMED_MS, board: s.board, frame: f }); continue } // not up yet: the look waits for it
1835
+ armed.delete(k)
1836
+ seen[f] = Math.max(seen[f] ?? 0, saw)
1837
+ }
1838
+ ack(seen)
1839
+ },
1560
1840
  async syncWorking() {
1561
1841
  if (PUBLISHED) return
1562
1842
  try {
@@ -1595,6 +1875,26 @@ export const useStore = create<State>((set, get) => {
1595
1875
  return node
1596
1876
  },
1597
1877
 
1878
+ syncUnplaced(ids) {
1879
+ const s = get()
1880
+ if (s.board !== UNPLACED || !s.manifest) return
1881
+ const want = new Set(ids)
1882
+ const keep = s.nodes.filter((n) => want.has(n.frame))
1883
+ const add = ids.filter((id) => !keep.some((n) => n.frame === id))
1884
+ if (keep.length === s.nodes.length && !add.length) return
1885
+ for (const n of s.nodes) if (!want.has(n.frame)) letGo(n.key, false)
1886
+ const joined: Node[] = add.flatMap((id) => {
1887
+ const f = s.manifest!.frames.find((x) => x.id === id)
1888
+ if (!f) return []
1889
+ const d = defaultSize(f)
1890
+ return [{ key: nodeKey(), frame: f.id, x: 0, y: 0, w: d.w, h: d.h, theme: resolveTheme(f), status: 'loading' as const, ...(f.contentWidth ? { sizeMode: 'auto' as const } : {}) }]
1891
+ })
1892
+ const nodes = [...keep, ...joined]
1893
+ const scenes = [...new Set(nodes.map((n) => s.manifest!.frames.find((f) => f.id === n.frame)?.scene).filter((x): x is string => !!x))]
1894
+ set({ nodes, selection: s.selection.filter((k) => nodes.some((n) => n.key === k)), layout: scenes.length ? { rows: [scenes] } : null })
1895
+ get().runTidy() // one band of its scenes again; the view is never saved
1896
+ },
1897
+
1598
1898
  save() {
1599
1899
  // a rename is moving this board's file - defer every save so nothing writes to the OLD
1600
1900
  // name mid-move (renameBoard reschedules once the move commits under the new name)
@@ -1610,6 +1910,8 @@ export const useStore = create<State>((set, get) => {
1610
1910
  set({ dirty: false })
1611
1911
  return Promise.resolve(true)
1612
1912
  }
1913
+ // the Not on a board view is never saved: what is moved there lasts the visit
1914
+ if (get().board === UNPLACED) { set({ dirty: false }); return Promise.resolve(true) }
1613
1915
  const p = saveChain.then(async () => {
1614
1916
  // recheck INSIDE the serialized chain: a save queued behind an in-flight PUT
1615
1917
  // may only execute after a resize gesture began - the entry guard above ran
@@ -1683,5 +1985,13 @@ export const useStore = create<State>((set, get) => {
1683
1985
  }
1684
1986
  })
1685
1987
 
1988
+ // a frame shown in focus or play is looked at (spec 25): the stage reports each frame it commits,
1989
+ // with the revision it shows (Play.tsx sets stageShown) - selecting one is handled in select()
1990
+ useStore.subscribe((s, prev) => {
1991
+ if (s.stageShown && s.stageShown !== prev.stageShown) { reconcile(); s.look(['stage']) } // a late commit of an older stage offers Update
1992
+ // the canvas is in view again; an Update the closed stage held goes with it (the next one is served fresh)
1993
+ if (!s.play && prev.play) { useStore.setState({ stageShown: null, playUpdateRevision: null }); pumpUpdates() }
1994
+ })
1995
+
1686
1996
  // dev-only inspection hook for tests/debugging (never installed in published builds)
1687
1997
  if (import.meta.env.DEV) (window as unknown as { __mvStore: unknown }).__mvStore = useStore