@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
@@ -1,6 +1,6 @@
1
1
  import { useEffect, useRef, useState, type CSSProperties, type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react'
2
2
  import { useStore, HAS_ALL_SCENES, PUBLISHED, STATUS_AS_OF, fetchBoardTree, rememberMeta, rememberTitles, type BoardMeta, type TreeBase } from './store.ts'
3
- import { StatusIcon, TypeIcon } from './board-icons.tsx'
3
+ import { LiveIcon, StatusIcon, TypeIcon } from './board-icons.tsx'
4
4
  import { StatusPicker } from './StatusPicker.tsx'
5
5
  import type { StatusWord } from '../../shared/board-types.ts'
6
6
  import { PHASE_LABEL, STATUS_LABEL } from '../../shared/status.ts'
@@ -31,11 +31,18 @@ const readClosed = (): Record<string, true> => { try { return JSON.parse(localSt
31
31
  * yet - drawn at `index` in `parent`'s items (null = the root), optionally with `board`
32
32
  * already inside it. */
33
33
  /** A status's tooltip: what it is, how far along, why, and the evidence that decided it. */
34
- function statusTip(m: BoardMeta): string {
34
+ /** A status, said: the status (and its phase), then why - the reason, each piece of evidence, as of when. */
35
+ function statusLines(m: BoardMeta): [string, string[]] {
35
36
  const st = m.status!
36
37
  const head = STATUS_LABEL[st.status] + (st.fill ? ` - ${PHASE_LABEL[st.fill]}` : '')
37
38
  const asOf = STATUS_AS_OF ? `as of ${new Date(STATUS_AS_OF).toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' })}` : null
38
- return [head, st.reason, ...(st.evidence ?? []), asOf].filter(Boolean).join('\n')
39
+ return [head, [st.reason, ...(st.evidence ?? []), asOf].filter((x): x is string => !!x)]
40
+ }
41
+ const statusTip = (m: BoardMeta): string => { const [head, rest] = statusLines(m); return [head, ...rest].join('\n') }
42
+ /** The house tooltip for it (Tip), never the browser's: the status in bold, its evidence beneath. */
43
+ function StatusTipLabel({ m }: { m: BoardMeta }) {
44
+ const [head, rest] = statusLines(m)
45
+ return <div className="sh-tip-lines"><b>{head}</b>{rest.map((l, i) => <small key={i}>{l}</small>)}</div>
39
46
  }
40
47
 
41
48
  type Naming = { kind: 'board' | 'folder'; name: string } | { kind: 'new'; index: number; board?: string; parent: string | null }
@@ -44,6 +51,7 @@ type Intent = (tree: TreeItem[]) => TreeItem[] | null
44
51
 
45
52
  export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
46
53
  const board = useStore((s) => s.board)
54
+ const working = useStore((s) => s.workingBoards) // boards an agent is working on right now
47
55
  const titles = useStore((s) => s.boardTitles) // board slug → title, off the last tree read
48
56
  const meta = useStore((s) => s.boardMeta) // board slug → type and status (spec 20)
49
57
  const label = (n: string) => labelOf(n, titles[n]) // a board's label; a folder's is labelOf(name, item.title)
@@ -449,9 +457,15 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
449
457
  onPointerUp={canDrag ? onPointerUp : undefined}
450
458
  onPointerCancel={canDrag ? () => resetPointer() : undefined}
451
459
  onLostPointerCapture={canDrag ? (e) => { if (gestureRef.current?.pointerId === e.pointerId) resetPointer() } : undefined}>
452
- {n === 'all-scenes' ? <CardsThreeIcon size={14} /> : meta[n]?.type ? <TypeIcon type={meta[n].type!} /> : <CardsIcon size={14} />}
460
+ <LiveIcon live={working.includes(n)}>{n === 'all-scenes' ? <CardsThreeIcon size={14} /> : meta[n]?.type ? <TypeIcon type={meta[n].type!} /> : <CardsIcon size={14} />}</LiveIcon>
453
461
  <span>{label(n)}</span>
454
- {meta[n]?.status && <i className="st" data-status={meta[n].status!.status} title={statusTip(meta[n])}><StatusIcon status={meta[n].status!.status} fill={meta[n].status!.fill} /></i>}
462
+ {/* the status for a screen reader, part of the board button's own name: the glyph is the eye's */}
463
+ {meta[n]?.status && <span className="sh-sr" data-status-text>{`, ${statusTip(meta[n]).replace(/\n/g, '; ')}`}</span>}
464
+ {meta[n]?.status && (
465
+ <Tip side="right" label={<StatusTipLabel m={meta[n]} />}>
466
+ <i className="st" data-status={meta[n].status!.status} aria-hidden="true"><StatusIcon status={meta[n].status!.status} fill={meta[n].status!.fill} /></i>
467
+ </Tip>
468
+ )}
455
469
  </button>
456
470
  )
457
471
  }
@@ -496,7 +510,8 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
496
510
  onPointerUp={!PUBLISHED ? onPointerUp : undefined}
497
511
  onPointerCancel={!PUBLISHED ? () => resetPointer() : undefined}
498
512
  onLostPointerCapture={!PUBLISHED ? (e) => { if (gestureRef.current?.pointerId === e.pointerId) resetPointer() } : undefined}>
499
- {open ? <FolderOpenIcon size={14} /> : <FolderIcon size={14} />}
513
+ {/* a closed folder carries the live signal of the boards it hides */}
514
+ <LiveIcon live={!open && boards.some((b) => working.includes(b))}>{open ? <FolderOpenIcon size={14} /> : <FolderIcon size={14} />}</LiveIcon>
500
515
  <span>{labelOf(f, it.title)}</span>
501
516
  <small>{boards.length}</small>
502
517
  </button>,
@@ -10,7 +10,7 @@
10
10
  * within what the lock allows.
11
11
  */
12
12
  import { Component, useEffect, useRef, type ReactNode } from 'react'
13
- import { useStore, boardLabel, landingMode } from './store.ts'
13
+ import { useStore, landingMode, tabTitle } from './store.ts'
14
14
  import { enterFocus, enterPlay, enterSlides, PlayOverlay, playCtl } from './Play.tsx'
15
15
  import { bootHash, parseHash, writeHash } from './hash.ts'
16
16
  import { useComments } from './comments-store.ts'
@@ -108,7 +108,7 @@ export function App() {
108
108
  }, [board])
109
109
 
110
110
  const titles = useStore((s) => s.boardTitles)
111
- useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board, titles])
111
+ useEffect(() => { document.title = tabTitle(board) }, [board, titles])
112
112
 
113
113
  return (
114
114
  <div tabIndex={-1} className="sh-app dark">
@@ -18,6 +18,7 @@ import { isNoteAnchor } from './notes.ts'
18
18
  import { ROUTE, slideSize } from '../const.ts'
19
19
  import { poweredByUrl } from '../../shared/utm.ts'
20
20
  import { canvasCtl } from './canvas/ctl.ts'
21
+ import { revealFrame } from './goto.ts'
21
22
  import { Tip } from './Tip.tsx'
22
23
  import { CommentButton, DevicePicker, HideUIButton, isHideUI, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
23
24
  import { DraftComposer, hueVars, MarkerFace, ThreadCard } from './Comments.tsx'
@@ -322,7 +323,9 @@ function PlayInner() {
322
323
  const trimmed = slides && deckChrome !== 'full' // minimal|none: strip the present tools
323
324
  const docPreset = focus && BOARD_POLICY[board]?.type === 'doc'
324
325
  const locked = boardLocked(board)
325
- const noDoor = locked || !!play?.deep
326
+ // a frame deep link is presentation, not access (01-sharing §3.5) - on a PUBLISHED canvas. In dev
327
+ // the visitor is the owner, who followed an agent's link: the way back to the canvas stays.
328
+ const noDoor = locked || (!!play?.deep && PUBLISHED)
326
329
 
327
330
  // the stage is same-origin (/__mv/stage/); a fixed target origin keeps anchor bundles
328
331
  // from leaking if a link ever navigates the iframe cross-origin
@@ -354,6 +357,7 @@ function PlayInner() {
354
357
  // land back on the canvas at the frame you ended on
355
358
  const n = useStore.getState().nodes.find((x) => x.frame === at && !x.missing)
356
359
  if (n) { useStore.getState().select(n.key); setTimeout(() => canvasCtl.fitNode(n.key), 30) }
360
+ else if (at) void revealFrame(at) // a deep link's frame need not be on the board that booted
357
361
  }
358
362
 
359
363
  const setDevice = (name: string) => {
@@ -7,9 +7,10 @@ import type { BoardMeta } from './store.ts'
7
7
  /**
8
8
  * A board's status, from its right-click menu - Linear's picker, on Marver's rule (spec 20): a
9
9
  * person decides only what the evidence cannot. With `context/` that is Blocked (with a reason),
10
- * Paused and Archived, and "Back to the evidence" undoes the decision; without it, Backlog, To do
11
- * and In progress as well. Done is never offered - it comes from the shipped record. The status
12
- * the evidence gives shows read-only at the top, with where it came from.
10
+ * Paused and Archived, and "Back to the evidence" undoes the decision - plus In progress and Building
11
+ * where an open plan names the capability (they write the plan's `stage`, the evidence itself);
12
+ * without it, Backlog, To do, In progress and Building as well. Done is never offered - it comes from
13
+ * the shipped record. The status the evidence gives shows read-only at the top, with where it came from.
13
14
  *
14
15
  * Type to filter, arrows and Enter, or a number. Blocked asks why before it writes.
15
16
  */
@@ -70,7 +71,9 @@ export function StatusPicker({ meta, onPick }: { meta: BoardMeta; onPick: (statu
70
71
  )}
71
72
  <div className="sp-list">
72
73
  {shown.map((o, i) => {
73
- const isCurrent = o.status !== null && o.status === current?.status && (decided || !hasContext)
74
+ // with context/, In progress and Building are the plan's - current when the evidence says so
75
+ const fromPlan = o.status === 'in-progress' || o.status === 'building'
76
+ const isCurrent = o.status !== null && o.status === current?.status && (decided || !hasContext || fromPlan)
74
77
  return (
75
78
  <button key={o.key} data-status-option={o.key} className={i === hi ? 'hi' : undefined}
76
79
  onMouseEnter={() => setHi(i)} onClick={() => choose(o)}>
@@ -85,7 +88,11 @@ export function StatusPicker({ meta, onPick }: { meta: BoardMeta; onPick: (statu
85
88
  })}
86
89
  {!shown.length && <div className="sp-empty">No status matches</div>}
87
90
  </div>
88
- <div className="sp-foot">{hasContext ? 'Backlog, To do, In progress and Done are read from context/' : 'Done needs a record - context/shipped.md'}</div>
91
+ <div className="sp-foot">{!hasContext
92
+ ? 'Done needs a record - context/shipped.md'
93
+ : settable.includes('building')
94
+ ? 'Building and In progress write the plan’s stage · Done needs a record'
95
+ : 'Building needs an open plan - context/plans/'}</div>
89
96
  </div>
90
97
  )
91
98
  }
@@ -5,13 +5,14 @@ import { createPortal } from 'react-dom'
5
5
  * Portaled to the app root - glass never nests, and neither do overlays. `inv` pins the
6
6
  * flipped (light) bubble for surfaces with fixed dark chrome (play mode), where the
7
7
  * theme-following default would sit dark-on-dark. */
8
- export function Tip({ label, side = 'top', inv = false, children }: { label: ReactNode; side?: 'top' | 'bottom'; inv?: boolean; children: ReactElement }) {
8
+ export function Tip({ label, side = 'top', inv = false, children }: { label: ReactNode; side?: 'top' | 'bottom' | 'right'; inv?: boolean; children: ReactElement }) {
9
9
  const [pos, setPos] = useState<{ x: number; y: number } | null>(null)
10
10
  const timer = useRef<number | undefined>(undefined)
11
11
  const show = (e: React.MouseEvent) => {
12
12
  const r = (e.currentTarget as HTMLElement).getBoundingClientRect()
13
- const y = side === 'top' ? r.top - 7 : r.bottom + 7
14
- timer.current = window.setTimeout(() => setPos({ x: r.left + r.width / 2, y }), 150)
13
+ // right: beside the trigger, centred on it - a sidebar row's glyph, read toward the canvas
14
+ const at = side === 'right' ? { x: r.right + 9, y: r.top + r.height / 2 } : { x: r.left + r.width / 2, y: side === 'top' ? r.top - 7 : r.bottom + 7 }
15
+ timer.current = window.setTimeout(() => setPos(at), 150)
15
16
  }
16
17
  const hide = () => { window.clearTimeout(timer.current); setPos(null) }
17
18
  const app = document.querySelector('.sh-app')
@@ -22,10 +23,29 @@ export function Tip({ label, side = 'top', inv = false, children }: { label: Rea
22
23
  const el = tipRef.current
23
24
  if (!el) return
24
25
  el.style.marginLeft = '0px'
25
- const r = el.getBoundingClientRect()
26
+ el.style.marginTop = '0px'
27
+ if (!pos) return
28
+ // the box it settles into, from its unscaled size - not the rect mid-animation (scaled .95, it
29
+ // reads smaller than it lands): top centres above, below centres under, right centres beside
30
+ const w = el.offsetWidth, h = el.offsetHeight
31
+ const left = side === 'right' ? pos.x : pos.x - w / 2
32
+ const top = side === 'right' ? pos.y - h / 2 : side === 'top' ? pos.y - h : pos.y
33
+ const r = { left, right: left + w, top, bottom: top + h }
26
34
  const over = r.right - (window.innerWidth - 8)
27
35
  if (over > 0) el.style.marginLeft = `${-over}px`
28
36
  else if (r.left < 8) el.style.marginLeft = `${8 - r.left}px`
37
+ // and up and down: a tall tip beside a row near the bottom (a status and its evidence) stays whole
38
+ const below = r.bottom - (window.innerHeight - 8)
39
+ if (below > 0) el.style.marginTop = `${-below}px`
40
+ else if (r.top < 8) el.style.marginTop = `${8 - r.top}px`
41
+ }, [pos])
42
+ // a tip is placed once, where its trigger was: anything that scrolls under it puts it away
43
+ useLayoutEffect(() => {
44
+ if (!pos) return
45
+ const away = () => hide()
46
+ window.addEventListener('scroll', away, true)
47
+ window.addEventListener('resize', away)
48
+ return () => { window.removeEventListener('scroll', away, true); window.removeEventListener('resize', away) }
29
49
  }, [pos])
30
50
  return (
31
51
  <>
@@ -35,7 +55,7 @@ export function Tip({ label, side = 'top', inv = false, children }: { label: Rea
35
55
  onClick: (e: React.MouseEvent) => { child.props.onClick?.(e); hide() },
36
56
  })}
37
57
  {pos && app && createPortal(
38
- <div ref={tipRef} className={`sh-tip${side === 'bottom' ? ' below' : ''}${inv ? ' inv' : ''}`} style={{ left: pos.x, top: pos.y }}>{label}</div>,
58
+ <div ref={tipRef} className={`sh-tip${side === 'bottom' ? ' below' : side === 'right' ? ' right' : ''}${inv ? ' inv' : ''}`} style={{ left: pos.x, top: pos.y }}>{label}</div>,
39
59
  app,
40
60
  )}
41
61
  </>
@@ -35,6 +35,9 @@ const RED = '#e5484d'
35
35
  // done is the content palette's green (Apple's systemGreen, per theme - styles.css), the green Marver
36
36
  // keeps for done alone; archived is Apple's brown - a cardboard box - per theme as well
37
37
  const GREEN = 'var(--status-done, #34c759)'
38
+ // Building is Marver's blue: yellow is being shaped, blue is being built, green is shipped. Its own
39
+ // token, not the accent - interact mode re-tints the accent, and a status does not change with a mode
40
+ const BLUE = 'var(--status-building, #0088ff)'
38
41
  const ARCHIVED = 'var(--status-archived, #956d51)'
39
42
 
40
43
  /** A pie wedge of the ring's interior, `f` of the way round from twelve o'clock. */
@@ -45,7 +48,8 @@ const pie = (f: number, r = 3.4) => {
45
48
  }
46
49
 
47
50
  /** A status glyph, on one rule: a status still open is an outline in its colour (a ring - In progress
48
- * fills it by phase: a quarter at spec, half at lo-fi, three quarters at hi-fi); a settled one is
51
+ * fills it by phase: a quarter at spec, half at lo-fi, three quarters at hi-fi; Building is the code
52
+ * inside a blue ring, the design agreed and the code underway); a settled one is
49
53
  * filled - Done a green disc, Archived a solid archive box (no ring: it is out of the flow, not a
50
54
  * step in it). Done, reported stays an outline: a written claim is not settled until confirmed. */
51
55
  export function StatusIcon({ status, fill, size = 14 }: { status: Status; fill?: Phase; size?: number }) {
@@ -58,6 +62,7 @@ export function StatusIcon({ status, fill, size = 14 }: { status: Status; fill?:
58
62
  {status === 'backlog' && ring(GRAY, '1.3 1.75')}
59
63
  {status === 'todo' && ring(GRAY)}
60
64
  {status === 'in-progress' && (<>{ring(YELLOW)}{fill && <path d={pie(fill / 4)} fill={YELLOW} />}</>)}
65
+ {status === 'building' && (<>{ring(BLUE)}<path d="M5.6 4.9 L3.8 7 L5.6 9.1 M8.4 4.9 L10.2 7 L8.4 9.1" fill="none" stroke={BLUE} strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" /></>)}
61
66
  {status === 'blocked' && (<>{ring(RED)}<circle cx="7" cy="7" r="3.2" fill={RED} /></>)}
62
67
  {status === 'done' && (<>
63
68
  <mask id={cut}><rect width="14" height="14" fill="#fff" /><path d="M4.3 7.2 L6.2 9.1 L9.8 5.2" fill="none" stroke="#000" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" /></mask>
@@ -73,3 +78,12 @@ export function StatusIcon({ status, fill, size = 14 }: { status: Status; fill?:
73
78
  </svg>
74
79
  )
75
80
  }
81
+
82
+ /** A sidebar icon while an agent works on what it holds (spec 20, the live signal): accent blue, with
83
+ * a highlight sweeping across it - the canvas's working shimmer in miniature, so the sidebar and the
84
+ * frames read as one signal. The highlight is the same icon again, masked to a moving band; it stops
85
+ * for reduced motion, leaving the blue. Automatic only - it lasts exactly as long as the work. */
86
+ export function LiveIcon({ live, children }: { live: boolean; children: ReactNode }) {
87
+ if (!live) return <>{children}</>
88
+ return <span className="sh-live-ic" data-live-icon>{children}<span className="glint" aria-hidden>{children}</span></span>
89
+ }
@@ -1,7 +1,8 @@
1
- import { useEffect, useRef } from 'react'
1
+ import { useEffect, useLayoutEffect, useRef } from 'react'
2
2
  import { TransformWrapper, TransformComponent, type ReactZoomPanPinchContentRef } from 'react-zoom-pan-pinch'
3
3
  import { CONFIG, useStore } from '../store.ts'
4
- import { bootHash } from '../hash.ts'
4
+ import { bootHash, linkTargets } from '../hash.ts'
5
+ import { revealFrame } from '../goto.ts'
5
6
  import { startPerf } from '../perf.ts'
6
7
  import { FrameNode, HEADER } from './FrameNode.tsx'
7
8
  import { NOTE_GAP } from '../notes.ts'
@@ -90,6 +91,9 @@ export function animateLayout(ms = 360) {
90
91
  // implementations below when it mounts
91
92
  import { canvasCtl, type CanvasWheelInput } from './ctl.ts'
92
93
  export { canvasCtl, type CanvasWheelInput }
94
+ import { anchorNode, anchoredCamera, type Held } from './anchor.ts'
95
+ /** The node a content-driven reflow must not move on screen (holdView -> the layout effect). */
96
+ let heldView: Held | null = null
93
97
 
94
98
  /** Variant-group captions: "Landing · 3 variants" above each group with
95
99
  * 2+ members on this board. World-space (scales with the canvas); min screen size via
@@ -199,22 +203,40 @@ export function Canvas() {
199
203
  const k = target / scale // zoom about the viewport center
200
204
  inst.setTransform(cx - (cx - positionX) * k, cy - (cy - positionY) * k, target, 250, 'easeOut')
201
205
  }
206
+ canvasCtl.cameraBusy = () => !!ref.current?.instance.animation
207
+ canvasCtl.holdView = () => {
208
+ heldView = null
209
+ const el = wrap(), inst = ref.current
210
+ // a camera already in flight (a fit, a zoom) lands where it was sent; a pan in progress is
211
+ // the human's own motion - neither is ours to correct
212
+ if (!el || !inst || inst.instance.animation || inst.instance.isPanning) return
213
+ const held = anchorNode(useStore.getState(), inst.instance.transformState, el.clientWidth, el.clientHeight)
214
+ if (!held) return
215
+ heldView = held
216
+ // the reflow commits before the next frame; an anchor nothing consumed must never steer a later change
217
+ requestAnimationFrame(() => { if (heldView === held) heldView = null })
218
+ }
202
219
  }, [])
203
220
 
204
221
  // first load opens on the whole board (same as ⇧1) - the default 100% transform is an
205
- // arbitrary top-left crop. A deep link with a selection (#/b/x?n=...) restores it and
206
- // fits the camera to it instead. Runs once, on the first frame batch; board switches
222
+ // arbitrary top-left crop. A deep link with a selection (#/b/x?n=..., or by frame id
223
+ // ?f=scene/frame, or a whole scene ?s=scene) restores it and fits the camera to it instead. Runs once, on the first frame batch; board switches
207
224
  // refit through their own path.
208
225
  const booted = useRef(false)
209
226
  useEffect(() => {
210
227
  if (booted.current || nodes.length === 0) return
228
+ let revealed = false
211
229
  booted.current = true
212
230
  const fit = () => {
213
- const keys = (bootHash.n ?? []).filter((k) => useStore.getState().nodes.some((n) => n.key === k))
231
+ const keys = linkTargets(bootHash, useStore.getState().nodes)
214
232
  if (keys.length) {
215
233
  useStore.setState({ selection: keys })
216
234
  canvasCtl.fitNodes(keys)
217
- } else canvasCtl.fitAll()
235
+ } else {
236
+ canvasCtl.fitAll()
237
+ // a link naming a frame this board does not show follows the frame where it lives
238
+ if (bootHash.f?.length && !revealed) { revealed = true; void revealFrame(bootHash.f[0]) }
239
+ }
218
240
  }
219
241
  requestAnimationFrame(() => {
220
242
  fit()
@@ -243,6 +265,20 @@ export function Canvas() {
243
265
  return () => el.removeEventListener('pointerdown', down)
244
266
  }, [])
245
267
 
268
+ // scroll anchoring, the commit half (holdView above): in the SAME commit that moved the nodes,
269
+ // before paint, shift the camera by the held node's displacement - it never visibly moves
270
+ useLayoutEffect(() => {
271
+ const held = heldView
272
+ if (!held) return
273
+ heldView = null
274
+ const inst = ref.current
275
+ const n = nodes.find((x) => x.key === held.key)
276
+ if (!inst || !n || inst.instance.animation) return
277
+ const { positionX, positionY, scale } = inst.instance.transformState
278
+ const [x, y] = anchoredCamera(held, n, positionX, positionY, scale)
279
+ if (x !== positionX || y !== positionY) inst.setTransform(x, y, scale, 0)
280
+ }, [nodes])
281
+
246
282
  // B0.2: the shell is the SINGLE wheel-camera owner. rzpp's wheel-pan is disabled (below);
247
283
  // both entry paths - a shell-document wheel over the canvas, and a wheel forwarded from a
248
284
  // passive frame's iframe (sh:wheel) - feed one applyCanvasWheel. Plain wheel pans (mirrors
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Scroll anchoring for the canvas - the browser's `overflow-anchor`, for a board.
3
+ *
4
+ * A content frame that measures taller re-flows the rows below it (store.ts scheduleReflow). The
5
+ * human did not ask for that, so the camera answers it: before the reflow, remember the node they
6
+ * are looking at - the selected one if it is on screen, else the one nearest the middle of the
7
+ * view - and after it, move the camera by exactly that node's displacement. What they were reading
8
+ * stays put; the rest of the board moves around it. Pure math here; Canvas.tsx owns the camera.
9
+ */
10
+
11
+ const HEADER = 28 // FrameNode's header: a node's box is h + HEADER tall on the canvas
12
+
13
+ export interface AnchorNode { key: string; x: number; y: number; w: number; h: number }
14
+ export interface Held { key: string; x: number; y: number }
15
+ export interface Camera { positionX: number; positionY: number; scale: number }
16
+
17
+ /** The node to hold still, or null when nothing of the board is on screen. */
18
+ export function anchorNode(st: { nodes: readonly AnchorNode[]; selection: readonly string[] }, cam: Camera, vw: number, vh: number): Held | null {
19
+ const { positionX: tx, positionY: ty, scale: s } = cam
20
+ const box = (n: AnchorNode) => ({ l: n.x * s + tx, t: n.y * s + ty, r: (n.x + n.w) * s + tx, b: (n.y + n.h + HEADER) * s + ty })
21
+ const onScreen = (n: AnchorNode) => { const r = box(n); return r.l < vw && r.t < vh && r.r > 0 && r.b > 0 }
22
+ const primary = st.nodes.find((n) => n.key === st.selection[st.selection.length - 1])
23
+ let pick: AnchorNode | undefined = primary && onScreen(primary) ? primary : undefined
24
+ if (!pick) {
25
+ let best = Infinity
26
+ for (const n of st.nodes) {
27
+ if (!onScreen(n)) continue
28
+ const r = box(n)
29
+ // distance from the view's middle to the node's box (0 inside it), then its centre for ties
30
+ const dx = Math.max(r.l - vw / 2, 0, vw / 2 - r.r), dy = Math.max(r.t - vh / 2, 0, vh / 2 - r.b)
31
+ const d = Math.hypot(dx, dy) * 1e6 + Math.hypot((r.l + r.r) / 2 - vw / 2, (r.t + r.b) / 2 - vh / 2)
32
+ if (d < best) { best = d; pick = n }
33
+ }
34
+ }
35
+ return pick ? { key: pick.key, x: pick.x, y: pick.y } : null
36
+ }
37
+
38
+ /** The camera position that puts the held node back where it was on screen, at the same zoom. */
39
+ export function anchoredCamera(held: Held, now: { x: number; y: number }, positionX: number, positionY: number, scale: number): [number, number] {
40
+ return [positionX - (now.x - held.x) * scale, positionY - (now.y - held.y) * scale]
41
+ }
@@ -23,4 +23,10 @@ export const canvasCtl = {
23
23
  zoomTo(_scale: number) {},
24
24
  zoom100() { canvasCtl.zoomTo(1) },
25
25
  wheel(_input: CanvasWheelInput) {},
26
+ /** Call right BEFORE a layout change the human did not ask for (a content-driven reflow): the
27
+ * node they are looking at keeps its place on screen through it - scroll anchoring. */
28
+ holdView() {},
29
+ /** Is the camera mid-flight (a fit, a zoom)? A content-driven reflow waits for it to land: a fit
30
+ * aimed at the frames a link names must not land on where they were before the rows moved. */
31
+ cameraBusy(): boolean { return false },
26
32
  }
@@ -104,13 +104,16 @@ export const useComments = create<CommentsState>((set, get) => {
104
104
  // the boot instant: an event younger than the page can never be "history", so it may
105
105
  // notify even before its board's baseline sweep lands (the poke/SSE-beats-load race)
106
106
  const bootTs = Date.now()
107
- // Live Jam: a Marver reply that arrives AFTER the baseline raises a persistent
108
- // bottom-right pill - from ANY board (the store holds every log), keyed on the event id
109
- // via `union`'s fresh filter so it fires exactly once. The pill's board is the THREAD's
110
- // origin board, so View can navigate there.
107
+ // Marver - a Live Jam reply, or a note or reply an agent left from the CLI - arriving AFTER
108
+ // the baseline raises a persistent bottom-right pill - from ANY board (the store holds every
109
+ // log), keyed on the event id via `union`'s fresh filter so it fires exactly once. The pill's
110
+ // board is the THREAD's origin board, so View can navigate there. One ping per batch, like a
111
+ // person's - except for a jam job's opening "On it" line (ids `jam-e<attempt>-…`, daemon.ts): the pill
112
+ // shows it, the ping waits for the answer.
111
113
  const notifyAgent = (fresh: CommentEvent[]) => {
112
- const replies = fresh.filter((e) => e.agent && e.type === 'reply')
114
+ const replies = fresh.filter((e) => e.agent && (e.type === 'reply' || e.type === 'create'))
113
115
  if (!replies.length) return
116
+ if (replies.some((e) => !/^jam-e\d+-/.test(e.id))) playPing()
114
117
  void import('./store.ts').then(({ useStore }) => {
115
118
  const s = useStore.getState()
116
119
  for (const e of replies) {
@@ -12,7 +12,7 @@ export function goTo(target: string, carry = false): void {
12
12
  const s = useStore.getState()
13
13
  const existing = s.nodes.find((n) => n.frame === target && !n.missing)
14
14
  if (existing) {
15
- gotoSeq++ // a local goto supersedes any cross-board one in flight
15
+ navigated() // a local goto supersedes any cross-board one in flight
16
16
  s.select(existing.key)
17
17
  if (carry) s.setInteract(existing.key)
18
18
  setTimeout(() => canvasCtl.fitNode(existing.key), 50)
@@ -28,10 +28,11 @@ export function goTo(target: string, carry = false): void {
28
28
  let gotoSeq = 0
29
29
  async function gotoAcrossBoards(target: string, carry: boolean) {
30
30
  const s = useStore.getState()
31
+ const from = s.board
31
32
  // an id the manifest doesn't know resolves NOWHERE - a tombstone pin on some board
32
33
  // must not send us on a trip that ends in a silent timeout
33
34
  if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`unknown goto target "${target}"`)
34
- const seq = ++gotoSeq
35
+ const seq = navigated()
35
36
  let home: string | null = null
36
37
  try {
37
38
  const names = (await fetchBoardNames()).filter((n) => n !== s.board && n !== 'all-scenes')
@@ -54,7 +55,24 @@ async function gotoAcrossBoards(target: string, carry: boolean) {
54
55
  setTimeout(() => canvasCtl.fitNode(node.key), 50)
55
56
  return
56
57
  }
57
- await s.switchBoard(home)
58
+ await landOn(home, target, carry, seq, from)
59
+ }
60
+
61
+ /** Navigation supersedes any goto or reveal still on its way - its board lookup (gotoSeq) AND a board
62
+ * switch it already started (a switch to the board on screen cancels any pending one: store.ts) - so
63
+ * a slow lookup can never yank the view away from where the human has gone since. Every entry point
64
+ * calls it: a pasted link, back/forward, a goto, a reveal. */
65
+ export function navigated(): number {
66
+ const s = useStore.getState()
67
+ if (s.board) void s.switchBoard(s.board)
68
+ return ++gotoSeq
69
+ }
70
+
71
+ /** Switch to `home` and select + fit `target` there once the board commits - unless the human has
72
+ * moved on: newer navigation, or a board they switched to themselves while the lookup ran. */
73
+ async function landOn(home: string, target: string, carry: boolean, seq: number, from: string) {
74
+ if (seq !== gotoSeq || useStore.getState().board !== from) return
75
+ await useStore.getState().switchBoard(home)
58
76
  for (let i = 0; i < 12; i++) { // the board commits async - retry like viewNote
59
77
  if (seq !== gotoSeq) return
60
78
  const st = useStore.getState()
@@ -70,3 +88,34 @@ async function gotoAcrossBoards(target: string, carry: boolean) {
70
88
  await new Promise((r) => setTimeout(r, 250))
71
89
  }
72
90
  }
91
+
92
+ /** Show a frame where it lives, for a LINK (a pasted canvas link naming a frame the board does
93
+ * not show, the way back from a focus link): this board, else the first curated board that pins
94
+ * it, else the auto board that holds every frame. Unlike a goto it never spawns - opening a link
95
+ * must not edit a board. */
96
+ export async function revealFrame(target: string): Promise<void> {
97
+ const s = useStore.getState()
98
+ const here = s.nodes.find((n) => n.frame === target && !n.missing)
99
+ if (here) {
100
+ navigated()
101
+ s.select(here.key)
102
+ setTimeout(() => canvasCtl.fitNode(here.key), 50)
103
+ return
104
+ }
105
+ if (!s.manifest?.frames.some((f) => f.id === target)) return s.toast(`no frame "${target}" on this canvas`)
106
+ const seq = navigated()
107
+ const from = s.board
108
+ let home: string | null = null
109
+ try {
110
+ const all = await fetchBoardNames()
111
+ for (const name of all.filter((n) => n !== s.board && n !== 'all-scenes')) {
112
+ if ((await boardFrames(name)).includes(target)) { home = name; break }
113
+ }
114
+ if (!home && all.includes('all-scenes')) home = 'all-scenes'
115
+ } catch {
116
+ return useStore.getState().toast(`could not read the boards - try again`)
117
+ }
118
+ if (seq !== gotoSeq) return
119
+ if (!home) return useStore.getState().toast(`"${target}" is not on any board`)
120
+ await landOn(home, target, false, seq, from)
121
+ }
@@ -7,6 +7,9 @@
7
7
  * #/ default board, fit all
8
8
  * #/b/<board> board, fit all
9
9
  * #/b/<board>?n=k1,k2 board with nodes selected, camera fit to selection
10
+ * #/b/<board>?f=<scene/frame>,... the same, by FRAME id - the link an agent can write
11
+ * (node keys are the shell's; `marver link` prints these)
12
+ * #/b/<board>?s=<scene>,... the same for every frame of a scene
10
13
  * #/b/<board>?c=<id> board with a comment thread open
11
14
  * #/i/<token> invite link - opens the claim dialog with the token
12
15
  * #/p/<board>?at=<frame-id>&device=<viewport>&theme=<theme> play mode
@@ -18,6 +21,10 @@
18
21
  export interface HashState {
19
22
  board?: string
20
23
  n?: string[]
24
+ /** Frame ids to select + fit - resolved to node keys once the board is loaded. */
25
+ f?: string[]
26
+ /** Scenes whose frames to select + fit. */
27
+ s?: string[]
21
28
  c?: string
22
29
  invite?: string
23
30
  play?: { at?: string; device?: string; theme?: string; slides?: boolean }
@@ -26,6 +33,17 @@ export interface HashState {
26
33
  }
27
34
 
28
35
  const BOARD_RE = /^[a-z0-9][a-z0-9-]*$/
36
+ const isFrameId = (at: string) => /^[\w./-]{1,200}$/.test(at) && !at.includes('..')
37
+
38
+ /** The node keys a link names on the loaded board: its keys (`n`), the nodes showing its frames
39
+ * (`f`) and every node of its scenes (`s`) - in board order, each once. A name the board does not
40
+ * show resolves to nothing (the caller decides what an empty answer means). */
41
+ export function linkTargets(h: Pick<HashState, 'n' | 'f' | 's'>, nodes: readonly { key: string; frame: string; missing?: boolean }[]): string[] {
42
+ const keys = new Set(h.n ?? [])
43
+ const frames = new Set(h.f ?? [])
44
+ const scenes = h.s ?? []
45
+ return nodes.filter((n) => keys.has(n.key) || (!n.missing && (frames.has(n.frame) || scenes.some((sc) => n.frame.startsWith(`${sc}/`))))).map((n) => n.key)
46
+ }
29
47
 
30
48
  export function parseHash(hash: string = location.hash): HashState {
31
49
  try {
@@ -40,7 +58,7 @@ export function parseHash(hash: string = location.hash): HashState {
40
58
  const mf = path.match(/^\/f\/(.+)$/)
41
59
  if (mf) {
42
60
  const at = decodeURIComponent(mf[1])
43
- if (!/^[\w./-]{1,200}$/.test(at) || at.includes('..')) return {}
61
+ if (!isFrameId(at)) return {}
44
62
  return { focus: { at, device: params.get('device') ?? undefined, theme: params.get('theme') ?? undefined } }
45
63
  }
46
64
  const m = path.match(/^\/(b|p)\/([^/?]+)$/)
@@ -48,9 +66,12 @@ export function parseHash(hash: string = location.hash): HashState {
48
66
  const board = decodeURIComponent(m[2])
49
67
  if (!BOARD_RE.test(board)) return {}
50
68
  if (m[1] === 'b') {
51
- const n = (params.get('n') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
69
+ const list = (k: string) => (params.get(k) ?? '').split(',').map((s) => s.trim()).filter(Boolean)
70
+ const n = list('n')
71
+ const f = list('f').filter(isFrameId)
72
+ const sc = list('s').filter((x) => /^[\w.-]{1,120}$/.test(x) && !x.includes('..'))
52
73
  const c = params.get('c') ?? undefined
53
- return { board, ...(n.length ? { n } : {}), ...(c && /^[\w-]+$/.test(c) ? { c } : {}) }
74
+ return { board, ...(n.length ? { n } : {}), ...(f.length ? { f } : {}), ...(sc.length ? { s: sc } : {}), ...(c && /^[\w-]+$/.test(c) ? { c } : {}) }
54
75
  }
55
76
  return {
56
77
  board,