@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,11 +1,11 @@
1
1
  import { r as NAME } from "./cli.mjs";
2
- import { WORK_TTL_DEFAULT, WORK_TTL_MAX, readDevInfo } from "./work-CLrmY-vQ.mjs";
2
+ import { i as readDevInfo, n as WORK_TTL_MAX, t as WORK_TTL_DEFAULT } from "./work-CiUvBVa6.mjs";
3
3
  //#region src/cli/work.ts
4
4
  /**
5
5
  * `marver work` - the coding agent's hand on the canvas working state.
6
6
  *
7
7
  * work start <scene/frame ...> [--ttl <minutes>] mark frames actively working
8
- * work done <scene/frame ...> | --all clear the glow
8
+ * work done <scene/frame ...> | --all clear the glow; print the canvas link to them
9
9
  * work list what is glowing right now
10
10
  *
11
11
  * The intended choreography (taught in design/AGENTS.md): on accepting a request,
@@ -43,17 +43,20 @@ async function workCommand(root, action, frames, opts) {
43
43
  if (!frames.length) throw new Error("name the frames: work start <scene/frame ...>");
44
44
  const min = Number(opts.ttl);
45
45
  const ttlMs = Number.isFinite(min) && min > 0 ? Math.min(Math.max(min * 6e4, 1e4), WORK_TTL_MAX) : WORK_TTL_DEFAULT;
46
- const { frames: active } = await call("POST", {
46
+ const { frames: active, behind = [], context } = await call("POST", {
47
47
  frames,
48
48
  on: true,
49
49
  ttlMs
50
50
  });
51
51
  const pretty = ttlMs >= 6e4 ? `${Math.round(ttlMs / 6e4)} min` : `${Math.round(ttlMs / 1e3)} s`;
52
52
  console.log(`working: ${active.join(", ")} (auto-expires in ${pretty} - re-run to extend, \`work done\` to clear)`);
53
+ const label = (st) => st === "todo" ? "To do" : "Backlog";
54
+ for (const b of behind) console.log(context ? `note: board "${b.board}" still reads ${label(b.status)} - you are working on it, so make it In progress: a plan in context/plans/ that opens with front matter naming it - "---" / "state: proposed" / "capability: ${b.capability}" / "---" - then what you are building and why, a few lines (follow the form of the plans already there). Once its code starts, add "stage: build" to that front matter (Building). design/AGENTS.md, "Show the work".` : `note: board "${b.board}" reads ${label(b.status)} - with no context/ its status is set by hand: once the human has answered the context line (design/AGENTS.md), "status": "in-progress" on the board says it is being worked on ("building" once its code starts).`);
53
55
  return;
54
56
  }
55
57
  case "done": {
56
58
  if (!frames.length && !opts.all) throw new Error("name the frames (or --all): work done <scene/frame ...>");
59
+ const before = opts.all ? (await call("GET")).frames : frames;
57
60
  const { frames: active } = await call("POST", opts.all ? {
58
61
  on: false,
59
62
  all: true
@@ -62,6 +65,9 @@ async function workCommand(root, action, frames, opts) {
62
65
  on: false
63
66
  });
64
67
  console.log(active.length ? `still working: ${active.join(", ")}` : "nothing working - all clear");
68
+ const done = before.filter((f) => !active.includes(f));
69
+ const link = done.length ? await (await import("./link-CcfAfKY-.mjs")).linkLine(root, done) : null;
70
+ if (link) console.log(`on the canvas: ${link}`);
65
71
  return;
66
72
  }
67
73
  case "list": {
@@ -1,3 +1,5 @@
1
+ import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
2
+ import { s as listBoardFiles } from "./boards-DbVJlbd5.mjs";
1
3
  import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2
4
  import { join } from "node:path";
3
5
  import { randomBytes } from "node:crypto";
@@ -28,6 +30,10 @@ function createActivity(ttlMs = 9e4) {
28
30
  if (changed) emit();
29
31
  },
30
32
  active: frames,
33
+ has(frame, src) {
34
+ const until = m.get(`${src}|${frame}`);
35
+ return until !== void 0 && until > Date.now();
36
+ },
31
37
  sweep() {
32
38
  const now = Date.now();
33
39
  let changed = false;
@@ -60,8 +66,26 @@ function createActivity(ttlMs = 9e4) {
60
66
  * process that can read the repo - the owner's own tools - is trusted by definition.
61
67
  * Presence itself NEVER touches disk (activity.ts).
62
68
  */
69
+ var work_exports = /* @__PURE__ */ __exportAll({
70
+ WORK_TTL_DEFAULT: () => WORK_TTL_DEFAULT,
71
+ WORK_TTL_MAX: () => WORK_TTL_MAX,
72
+ activityClock: () => activityClock,
73
+ boardsChanged: () => boardsChanged,
74
+ boardsShowing: () => boardsShowing,
75
+ nextActivitySeq: () => nextActivitySeq,
76
+ onBoardsChanged: () => onBoardsChanged,
77
+ readDevInfo: () => readDevInfo,
78
+ removeDevInfo: () => removeDevInfo,
79
+ workActivity: () => workActivity,
80
+ writeDevInfo: () => writeDevInfo
81
+ });
63
82
  /** One per process - the dev server, the jam daemon, and the API all share it. */
64
83
  const workActivity = createActivity();
84
+ /** The order of what the shell is told about activity: each broadcast takes the next number, and the
85
+ * snapshot a page asks for carries the latest - so a slow snapshot never undoes a newer broadcast.
86
+ * Time-based, so a restarted server never counts backwards past a page that outlived it. */
87
+ const activityClock = { seq: 0 };
88
+ const nextActivitySeq = () => activityClock.seq = Math.max(activityClock.seq + 1, Date.now());
65
89
  /** The longest a CLI mark may glow unrefreshed - a forgotten `done` self-heals. */
66
90
  const WORK_TTL_MAX = 18e5;
67
91
  const WORK_TTL_DEFAULT = 6e5;
@@ -93,5 +117,52 @@ function readDevInfo(root) {
93
117
  return null;
94
118
  }
95
119
  }
120
+ const indexes = /* @__PURE__ */ new Map();
121
+ const boardListeners = /* @__PURE__ */ new Set();
122
+ function indexOf(root) {
123
+ let ix = indexes.get(root);
124
+ if (ix) return ix;
125
+ ix = {
126
+ byFrame: /* @__PURE__ */ new Map(),
127
+ auto: []
128
+ };
129
+ try {
130
+ for (const b of listBoardFiles(join(root, "design", "boards")).boards) {
131
+ const j = b.json;
132
+ if (j?.auto === true) ix.auto.push(b.name);
133
+ if (!Array.isArray(j?.nodes)) continue;
134
+ for (const n of j.nodes) {
135
+ const f = n && typeof n === "object" ? n.frame : void 0;
136
+ if (typeof f !== "string") continue;
137
+ let set = ix.byFrame.get(f);
138
+ if (!set) ix.byFrame.set(f, set = /* @__PURE__ */ new Set());
139
+ set.add(b.name);
140
+ }
141
+ }
142
+ } catch {}
143
+ indexes.set(root, ix);
144
+ return ix;
145
+ }
146
+ /** A board file changed (the dev server's boards watcher): forget the index, tell who is listening. */
147
+ function boardsChanged(root) {
148
+ indexes.delete(root);
149
+ for (const l of boardListeners) l(root);
150
+ }
151
+ function onBoardsChanged(fn) {
152
+ boardListeners.add(fn);
153
+ return () => {
154
+ boardListeners.delete(fn);
155
+ };
156
+ }
157
+ /** The boards that show any of these frames - what the sidebar lights while an agent works (the
158
+ * board's type icon shimmers): every board pinning one, every auto board, and all-scenes, which
159
+ * holds every frame. Sorted, so an unchanged answer compares equal. */
160
+ function boardsShowing(root, frames) {
161
+ if (!frames.length) return [];
162
+ const ix = indexOf(root);
163
+ const out = /* @__PURE__ */ new Set(["all-scenes", ...ix.auto]);
164
+ for (const f of frames) for (const b of ix.byFrame.get(f) ?? []) out.add(b);
165
+ return [...out].sort();
166
+ }
96
167
  //#endregion
97
- export { WORK_TTL_DEFAULT, WORK_TTL_MAX, readDevInfo, removeDevInfo, workActivity, writeDevInfo };
168
+ export { workActivity as a, readDevInfo as i, WORK_TTL_MAX as n, work_exports as o, boardsChanged as r, WORK_TTL_DEFAULT as t };
@@ -78,6 +78,33 @@ nests a sub-folder with `parent`:
78
78
  with its rank, the landing board - and `--json` gives the same tree. The landing board is the first
79
79
  board in that reading order, down through folders.
80
80
 
81
+ ### Sizes
82
+
83
+ A content frame - a `Doc` of markdown, diagrams and images - is as tall as its content, which only a
84
+ render can tell. **`design/boards/_sizes.json` remembers it**: the height each one measured at its
85
+ own width, one line per frame.
86
+
87
+ ```json
88
+ { "about": "Written by marver dev: ...",
89
+ "heights": {
90
+ "spec/checkout@760": 1834,
91
+ "spec/pricing@1280": 1210 } }
92
+ ```
93
+
94
+ So a board opens with every frame at its real size - the content fills in, nothing moves - in
95
+ `marver dev` and on a published canvas alike (`marver build` ships the heights of the published
96
+ frames). `marver dev` writes it when a frame settles at a new height; commit it with the rest of
97
+ `design/`, and never edit it. A stale height is only a first guess: the frame measures, and the file
98
+ follows. A merge conflict in it is safe to resolve either way.
99
+
100
+ A board with a layout recipe also notes, as `laidOut`, which heights its rows were laid out around.
101
+ When a doc on it changed while the board was closed, the board re-runs its recipe as it opens; a
102
+ frame you dragged, at heights that did not change, stays where you put it.
103
+
104
+ When content does change the layout - an agent makes a doc taller, and the rows below move down -
105
+ the canvas holds the frame you are looking at in place: the selected one when it is on screen, else
106
+ the one in the middle of the view.
107
+
81
108
  ## Descriptions
82
109
 
83
110
  Every folder, board, scene and frame takes one `description`: a sentence for agents - what it is
@@ -109,19 +136,28 @@ but `marver build` suggests a publish type from it - `slides` for a deck, `refs`
109
136
  ## Status
110
137
 
111
138
  Feature and project boards also wear a status, read from the project's `context/` - Backlog, To do,
112
- In progress (filling by phase), Done, Done reported, Unknown - or decided on the board itself:
139
+ In progress (filling by phase), Building (the design agreed, the code underway: `stage: build` in the
140
+ open plan), Done, Done reported, Unknown - or decided on the board itself:
113
141
  `"status": "archived"`, `"paused"`, or `"blocked"` with a `"reason"`. **Done is never set by hand.**
114
142
  The tooltip says what decided it. [Context](context.md) has the rules.
115
143
 
116
144
  **Set it from the sidebar:** right-click a feature or project board, **Change status…**. The picker
117
145
  shows what the evidence says and offers only what a person decides - Blocked (it asks why), Paused,
118
- Archived, and **Back to the evidence** to undo a decision; without `context/`, Backlog, To do and In
119
- progress as well. Type to filter, or press a number. It writes `status` and `reason` into the board
120
- file and nothing else.
146
+ Archived, and **Back to the evidence** to undo a decision; where an open plan names the capability,
147
+ In progress and Building too, which write that plan's `stage` (no plan: "Building needs an open
148
+ plan"); without `context/`, Backlog, To do, In progress and Building as well. Type to filter, or press
149
+ a number. It writes `status` and `reason` into the board file, or the `stage` into the plan, and
150
+ nothing else.
121
151
 
122
152
  One rule draws them: a status still open is an outline in its colour - grey, yellow filling by phase,
123
- red for blocked - and a settled one is filled: Done a green disc, Archived a solid brown box. Done,
124
- reported is the green outline - a written claim, not yet confirmed.
153
+ the code in accent blue for Building, red for blocked - and a settled one is filled: Done a green
154
+ disc, Archived a solid brown box. Done, reported is the green outline - a written claim, not yet
155
+ confirmed.
156
+
157
+ **An agent at work.** While an agent works on a board's frames (`marver work start`, or a Live Jam
158
+ job), that board's icon in the sidebar turns accent blue with a highlight sweeping across it - the
159
+ frames' working shimmer, in miniature - and so does a closed folder holding it. It lasts exactly as
160
+ long as the work, so nobody sets it.
125
161
 
126
162
  ## Starting points
127
163
 
@@ -146,6 +182,18 @@ teaches each one - creating a sub-folder, moving a folder in or out, renaming a
146
182
  refuses a write that would overwrite an edit it has not seen, so an agent's file write and a
147
183
  person's drag never silently erase each other.
148
184
 
185
+ ## Links to frames
186
+
187
+ `npx marver link <scene/frame | scene ...>` prints the canvas link that lands on those frames: the
188
+ board they sit on, in canvas mode, with them selected and the camera fitted to them - not the
189
+ full-screen focus view. The board is the first in sidebar order that shows them all, else
190
+ `all-scenes`; `--board` picks one. The link reads `#/b/<board>?f=<scene/frame>,...` (or
191
+ `?s=<scene>` for a whole scene), and a link naming a frame its board does not show follows the
192
+ frame to where it lives. `npx marver work done` prints the same link for the frames it clears, so an
193
+ agent's reply ends with it. A focus link (`#/f/<frame>`) opened on your dev canvas now has its way
194
+ back to the canvas (the grid button, or Esc); on a published canvas a focus link stays a page of
195
+ its own.
196
+
149
197
  ## Publishing
150
198
 
151
199
  A published canvas shows the folders of the published boards only - a sub-folder's parent included,
package/docs/context.md CHANGED
@@ -21,6 +21,14 @@ project this was run on, a blind eval answered the same 16 questions correctly b
21
21
 
22
22
  ## Start
23
23
 
24
+ On a canvas, the shortest way in is one sentence to your agent: *"Set up our context."* The context
25
+ instruction is the whole recipe - it asks you a few questions, runs `context init` with the right
26
+ kind, drafts from evidence, files your feature boards so they wear a status, and puts the check in ci.
27
+ Until a project has `context/`, an agent that makes or changes a feature board ends its reply with one
28
+ line offering exactly that; say no and it stops asking for the session.
29
+
30
+ By hand:
31
+
24
32
  ```bash
25
33
  npx marver context init
26
34
  ```
@@ -32,7 +40,7 @@ stages a new version beside any you have. `--kind knowledge` keeps a delivered r
32
40
  Project and Delivered columns - and a repository without a canvas gets the conventions themselves as
33
41
  `context/README.md`.
34
42
 
35
- Then ask your agent: *"Read design/instructions/context.md and set up our context."* It interviews
43
+ Then tell your agent: *"Set up our context."* It interviews
36
44
  you first - who is involved, where each relationship happens, what is private - then drafts from
37
45
  evidence: the shipped record from deploy runs and the changelog, the map from the code, contracts
38
46
  for the capabilities that matter now. Where nothing proves a claim, it writes `unknown`.
@@ -96,7 +104,7 @@ Feature and project boards wear a status, read from these files - the first that
96
104
  |---|---|---|
97
105
  | 1-3 | the board says `"status": "archived"`, `"paused"`, or `"blocked"` with a `"reason"` - by hand, or from the sidebar's **Change status…** | Archived · Paused · Blocked |
98
106
  | 4 | the evidence cannot be read | Unknown |
99
- | 5 | an open plan in `context/plans/` names the capability | In progress, filling by phase |
107
+ | 5 | an open plan in `context/plans/` names the capability | Building when the plan says `stage: build`, else In progress, filling by phase |
100
108
  | 6 | `shipped.md` shows it available, `confirmed` - in a clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled back", "planned") and, for a product, no pre-production place (staging, preview, dev, local, testing) unless it also names production | Done |
101
109
  | 7 | ... `reported` only | Done, reported |
102
110
  | 8 | its contract is `state: current` | To do |
package/docs/live-jam.md CHANGED
@@ -152,6 +152,17 @@ model when the agent names one. Claude Code, Cursor, droid, grok, and pi report
152
152
  in the stream; `codex exec` and `opencode run` report none, so their replies carry the
153
153
  harness without a model rather than a guessed one.
154
154
 
155
+ ## Notes from your chat agent
156
+
157
+ Live Jam answers comments; the same voice works the other way. An agent you are chatting with leaves
158
+ a note where it needs you - `npx marver comments new <scene/frame> --body "..." [--on "<words on
159
+ screen>"]` pins it on the frame, or on the element showing those words - and answers your threads
160
+ with `npx marver comments reply`. Both post as Marver, with the same provenance, land on your canvas
161
+ at once, and raise the bottom-right pill with a ping. Reply in a note and it is a jam job like any
162
+ reply to Marver - no tag needed; while the chat agent still has that frame lit (`marver work
163
+ start`), the job waits for it. Notes stay on your machine for now, like jam replies; a reply to a
164
+ collaborator's thread keeps your voice, the one that reaches them on the published canvas.
165
+
155
166
  ## Parallelism
156
167
 
157
168
  Two knobs stack, and they are not the same thing. `jam.concurrency` is how many jobs the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.22.0",
3
+ "version": "0.23.0",
4
4
  "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -11,6 +11,11 @@ import { useEffect, useRef, useState, type ReactNode } from 'react'
11
11
  import { FONT_STACK, THEME_CSS, themeVars } from './palette.ts'
12
12
 
13
13
  let uidSeq = 0
14
+ /** Renders in flight - mermaid loads and lays out asynchronously, so a Doc is not done growing
15
+ * until this is 0 (the Doc's settled measurement reads it; the frame's own innerHTML is set
16
+ * before the count drops). */
17
+ let diagramsBusy = 0
18
+ export const diagramsPending = (): number => diagramsBusy
14
19
 
15
20
  const isDark = () =>
16
21
  document.documentElement.classList.contains('dark') || document.documentElement.dataset.theme === 'dark'
@@ -121,6 +126,7 @@ export function Diagram({ title, children }: { title?: string; children?: ReactN
121
126
  let renderSeq = 0
122
127
  const render = async () => {
123
128
  const mySeq = ++seq
129
+ diagramsBusy++
124
130
  try {
125
131
  // the zero-external-request boundary must hold BEFORE render: mermaid's image
126
132
  // shapes fetch their URL during render(), so post-render SVG sanitizing alone
@@ -145,7 +151,7 @@ export function Diagram({ title, children }: { title?: string; children?: ReactN
145
151
  setError(null)
146
152
  } catch (e) {
147
153
  if (live && mySeq === seq) setError(String((e as Error)?.message ?? e))
148
- }
154
+ } finally { diagramsBusy-- }
149
155
  }
150
156
  render()
151
157
  // the bridge mutates <html data-theme>/.dark with no React event - observe and re-render
@@ -51,6 +51,12 @@ function pick(devicePx: number): number {
51
51
  return 0 // native decode - only past the top bucket
52
52
  }
53
53
 
54
+ /** The event a canvas image fires when its FIRST decode is done, landed or failed. A canvas fed by
55
+ * fetch + createImageBitmap fires no DOM load/error of its own; the Doc listens for this one to
56
+ * know its height is final (content/index.tsx) - after its poll has stopped, too. */
57
+ export const LOD_SETTLED = 'mv-lod-settled'
58
+ const firstDone = (canvas: HTMLCanvasElement) => queueMicrotask(() => canvas.dispatchEvent(new Event(LOD_SETTLED, { bubbles: true })))
59
+
54
60
  async function decode(it: Item, bucket: number): Promise<void> {
55
61
  const token = ++it.token
56
62
  let bmp: ImageBitmap
@@ -59,7 +65,11 @@ async function decode(it: Item, bucket: number): Promise<void> {
59
65
  bmp = bucket
60
66
  ? await createImageBitmap(blob, { resizeWidth: bucket, resizeQuality: 'high' })
61
67
  : await createImageBitmap(blob)
62
- } catch { return } // network / decode failure: keep the last frame
68
+ } catch { // network / decode failure: keep the last frame
69
+ // a first decode that failed will not pin an aspect: the Doc must not wait on it to settle
70
+ if (!it.canvas.style.aspectRatio) { it.canvas.dataset.mvLod = 'failed'; firstDone(it.canvas) }
71
+ return
72
+ }
63
73
  if (it.token !== token || !it.canvas.isConnected) { bmp.close(); return } // superseded or unmounted
64
74
  const ctx = it.canvas.getContext('bitmaprenderer')
65
75
  if (!ctx) { bmp.close(); return }
@@ -68,7 +78,7 @@ async function decode(it: Item, bucket: number): Promise<void> {
68
78
  // the layout box would shift a hair on every resolution switch - the doc reflows, the content frame
69
79
  // auto-resizes, and the frame "jiggles" as you zoom (and the reflow storm helped starve frames to a
70
80
  // ready-timeout). A fixed aspect-ratio makes the box identical across buckets: only pixels sharpen.
71
- if (!it.canvas.style.aspectRatio) it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`
81
+ if (!it.canvas.style.aspectRatio) { it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`; firstDone(it.canvas) }
72
82
  it.canvas.width = bmp.width; it.canvas.height = bmp.height
73
83
  ctx.transferFromImageBitmap(bmp) // zero-copy; consumes + closes the bitmap
74
84
  it.bucket = bucket
@@ -11,13 +11,13 @@ import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
11
11
  import { useInSlide } from './slide.tsx'
12
12
  import { CONTENT_WIDTH } from '../const.ts'
13
13
  import { assetUrl, renderMarkdown, sanitizeMarkdownHtml, FAMILIES } from './md.ts'
14
- import { lodSupported, registerLodImage } from './img-lod.ts'
14
+ import { LOD_SETTLED, lodSupported, registerLodImage } from './img-lod.ts'
15
15
 
16
16
  // D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
17
17
  const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
18
18
  `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
19
19
 
20
- import { Diagram as DiagramRoot } from './diagram.tsx'
20
+ import { Diagram as DiagramRoot, diagramsPending } from './diagram.tsx'
21
21
  export function Diagram(props: Parameters<typeof DiagramRoot>[0]) { ensureStyles(); return <DiagramRoot {...props} /> }
22
22
  import { Slide as SlideRoot } from './slide.tsx'
23
23
  import { Chart as ChartRoot } from './chart.tsx'
@@ -34,6 +34,23 @@ const UNIT = 16 // one gap unit, px - plain adjacency on boards is one gutter;
34
34
 
35
35
  /* ---------------------------------- Doc ---------------------------------- */
36
36
 
37
+ /** How long the first measurement waits for the doc to finish growing before it reports anyway. */
38
+ const SETTLE_CAP = 2000
39
+ /** After the cap, a provisional doc keeps checking (slower) for this long, to report once it IS done. */
40
+ const SETTLE_TAIL = 60_000
41
+
42
+ /** Is anything that still changes this doc's height in flight? Fonts loading, a diagram rendering,
43
+ * an image not decoded yet (an LOD canvas pins its aspect on its first decode - img-lod.ts - and
44
+ * an <img> with no size yet is 0 tall until it loads; a lazy one off-screen may not load at all).
45
+ * A video poster sits in a fixed-ratio box: it never changes the height. */
46
+ export function heightPending(el: HTMLElement, doc: Document = document): boolean {
47
+ if (doc.fonts?.status === 'loading') return true
48
+ if (diagramsPending() > 0) return true
49
+ for (const c of el.querySelectorAll<HTMLCanvasElement>('canvas.mv-img-el')) if (!c.style.aspectRatio && c.dataset.mvLod !== 'failed') return true
50
+ for (const img of el.querySelectorAll('img')) if (!img.complete && !img.closest('.mv-video')) return true
51
+ return false
52
+ }
53
+
37
54
  export function Doc({ layout = 'document', children }: { layout?: 'document' | 'wide'; children?: ReactNode }) {
38
55
  const ref = useRef<HTMLDivElement>(null)
39
56
  useEffect(() => {
@@ -41,8 +58,18 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
41
58
  const el = ref.current
42
59
  if (!el || window.parent === window) return
43
60
  let t: ReturnType<typeof setTimeout> | undefined
61
+ let poll: ReturnType<typeof setTimeout> | undefined
62
+ let reported = false // the first measurement went out - the observer may report from here
63
+ let lastSettled = false
64
+ let tailFrom = 0
44
65
  const params = new URLSearchParams(location.search)
66
+ const height = () => Math.ceil(el.getBoundingClientRect().height)
45
67
  const post = () => {
68
+ reported = true
69
+ lastSettled = !heightPending(el)
70
+ // ANY provisional report - the first, or a later one (an edit that brought a loading image) -
71
+ // is followed by a settled one once the doc is done, even when finishing changes no geometry
72
+ if (!lastSettled && poll === undefined) { tailFrom = performance.now(); poll = setTimeout(check, 500) }
46
73
  window.parent.postMessage({
47
74
  type: 'sh:measure',
48
75
  // identity guards: board files may reuse node keys (frame id must match), and
@@ -52,15 +79,51 @@ export function Doc({ layout = 'document', children }: { layout?: 'document' | '
52
79
  gen: params.get('r') ?? '',
53
80
  ownWidth: CONTENT_WIDTH[layout] ?? CONTENT_WIDTH.document,
54
81
  measuredWidth: window.innerWidth, // the width this height is TRUE at (r3 #1)
55
- height: Math.ceil(el.getBoundingClientRect().height),
82
+ height: height(),
83
+ // settled = the doc is done growing: the shell commits it as THE height (and the dev shell
84
+ // keeps it for the next load - sizes.ts). Provisional = it may still grow (an image to come)
85
+ settled: lastSettled,
56
86
  }, '*')
57
87
  }
88
+ // The FIRST report waits until the doc is done: fonts, diagrams and images, and the height
89
+ // still the same two checks running - otherwise a board that already knows this frame's
90
+ // height (the committed cache) would see it shrink to the half-loaded doc and grow back.
91
+ // Capped: a slow or broken image never holds the frame hostage - it reports provisional,
92
+ // then once more, settled, when the image lands (or the observer sees it).
93
+ const start = performance.now()
94
+ let prevH = -1, quiet = 0
95
+ function check() {
96
+ poll = undefined
97
+ if (!reported) {
98
+ const h = height()
99
+ quiet = !heightPending(el!) && h === prevH ? quiet + 1 : 0
100
+ prevH = h
101
+ if (quiet >= 2 || performance.now() - start >= SETTLE_CAP) post()
102
+ else poll = setTimeout(check, 50)
103
+ return
104
+ }
105
+ if (lastSettled) return
106
+ if (!heightPending(el!)) { post(); return }
107
+ if (performance.now() - tailFrom < SETTLE_TAIL) poll = setTimeout(check, 500)
108
+ }
58
109
  // debounced ~300ms after the last content change; the shell guards staleness
59
110
  // on its side (event.source must map to a mounted iframe; reflow is board-scoped)
60
- const ro = new ResizeObserver(() => { clearTimeout(t); t = setTimeout(post, 300) })
111
+ const ro = new ResizeObserver(() => { if (!reported) return; clearTimeout(t); t = setTimeout(post, 300) })
61
112
  ro.observe(el)
62
- post()
63
- return () => { ro.disconnect(); clearTimeout(t) }
113
+ // an image landing or failing, a font finishing: check again now - the poll stops after its tail,
114
+ // and a size-given image that loads a minute later still owes the settled report
115
+ const onAsset = () => { if (reported && !lastSettled && poll === undefined) poll = setTimeout(check, 50) }
116
+ el.addEventListener('load', onAsset, true)
117
+ el.addEventListener('error', onAsset, true)
118
+ el.addEventListener(LOD_SETTLED, onAsset) // a canvas image's first decode, landed or failed (img-lod.ts)
119
+ document.fonts?.addEventListener?.('loadingdone', onAsset)
120
+ check()
121
+ return () => {
122
+ ro.disconnect(); clearTimeout(t); clearTimeout(poll)
123
+ el.removeEventListener('load', onAsset, true); el.removeEventListener('error', onAsset, true)
124
+ el.removeEventListener(LOD_SETTLED, onAsset)
125
+ document.fonts?.removeEventListener?.('loadingdone', onAsset)
126
+ }
64
127
  }, [layout])
65
128
  return <div ref={ref} className={`mv-doc mv-doc-${layout}`}>{children}</div>
66
129
  }
@@ -290,10 +290,33 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
290
290
  for (const el of document.querySelectorAll(want.tag))
291
291
  if (match(el)) return el
292
292
  }
293
+ // an anchor an agent wrote (`comments new --on "<text>"`) names the words alone: the
294
+ // innermost element showing them
295
+ if (want.quote && !want.tag && !anchor?.el?.cssPath) return byWords(want.quote)
293
296
  } catch { /* malformed semantics must not sink the whole batch */ }
294
297
  return null
295
298
  }
296
299
 
300
+ const norm = (t) => (t ?? '').replace(/\s+/g, ' ').trim()
301
+ const byWords = (quote) => {
302
+ const q = norm(quote).slice(0, 80).toLowerCase()
303
+ if (!q) return null
304
+ // one text node holding the words: its element (the common case, and cheap)
305
+ const walk = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
306
+ for (let n = walk.nextNode(); n; n = walk.nextNode()) {
307
+ const host = n.parentElement
308
+ if (!host || host.closest('script,style,noscript,template')) continue
309
+ if (norm(n.data).toLowerCase().includes(q)) return host
310
+ }
311
+ // words split across inline elements ("Pay <b>now</b>"): walk down from the body to the
312
+ // innermost element whose text still holds them (the first occurrence)
313
+ const holds = (el) => !el.matches('script,style,noscript,template') && norm(el.textContent).toLowerCase().includes(q)
314
+ let el = document.body
315
+ if (!holds(el)) return null
316
+ for (let next = [...el.children].find(holds); next; next = [...el.children].find(holds)) el = next
317
+ return el
318
+ }
319
+
297
320
  // re-resolve + re-apply the shell-driven highlight. Called on set and on every
298
321
  // resolve-anchors pass, so a stage frame swapped in AFTER the highlight arrived
299
322
  // (the DOM had not committed yet) still lights up on the next cycle - and, just as
@@ -1,5 +1,5 @@
1
1
  import { Component, useEffect, useRef, useState, type MouseEvent as ReactMouseEvent, type ReactNode } from 'react'
2
- import { useStore, CONFIG, LOCKED_SHELL, PUBLISHED, SOURCE_REVEALED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, hydrateBoardPolicy, landingMode, playsAsSlides, sceneLabel, type FrameEntry } from './store.ts'
2
+ import { useStore, CONFIG, CANVAS_NAME, LOCKED_SHELL, PUBLISHED, SOURCE_REVEALED, boardLabel, boardFrames, cap, humanize, fetchBoardNames, tabTitle, hydrateBoardPolicy, landingMode, playsAsSlides, sceneLabel, type FrameEntry } from './store.ts'
3
3
  import { BoardList } from './BoardList.tsx'
4
4
  import { ContextMenu, copyToClipboard, framePath, useContextMenu, type MenuItem } from './ContextMenu.tsx'
5
5
  import { Tip } from './Tip.tsx'
@@ -7,13 +7,13 @@ import { PKG, ROUTE } from '../const.ts'
7
7
  import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
8
8
  import { frameByWindow } from './canvas/frame-registry.ts'
9
9
  import { enterFocus, enterPlay, enterSlides, playCtl, PlayOverlay } from './Play.tsx'
10
- import { bootHash, parseHash, writeHash } from './hash.ts'
10
+ import { bootHash, linkTargets, parseHash, writeHash } from './hash.ts'
11
11
  import { CaretIcon, CheckIcon, ColumnsIcon, FrameRectIcon, ImagesSquareIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ParallelogramFillIcon, PencilSimpleIcon, PlayIcon, SignpostIcon, SlideFrameIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
12
12
  import { humanize as slugLabel, readTitle } from '../../shared/board-tree.ts'
13
13
  import { CommentsController, revealThread } from './Comments.tsx'
14
14
  import { poweredByUrl } from '../../shared/utm.ts'
15
15
  import { avatarFallback, useComments } from './comments-store.ts'
16
- import { goTo } from './goto.ts'
16
+ import { goTo, navigated, revealFrame } from './goto.ts'
17
17
  import { useNotes } from './notes.ts'
18
18
  import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
19
19
 
@@ -371,6 +371,9 @@ export function App() {
371
371
  }
372
372
  const ok = await boot()
373
373
  urlReady.current = true
374
+ // a link naming frames on a board with NO nodes: the canvas's boot fit never runs (it waits
375
+ // for the first frame) - follow the frame to where it lives from here
376
+ if (ok && bootHash.f?.length && !bootHash.focus && !useStore.getState().nodes.length) void revealFrame(bootHash.f[0])
374
377
  if (ok && bootHash.focus) {
375
378
  // a frame deep link forces focus for that visit, over every other rule
376
379
  // (01-sharing §6.1 step 3) - the stage mounts any manifest frame, so no
@@ -417,6 +420,7 @@ export function App() {
417
420
  // restores never echo back into history.
418
421
  useEffect(() => {
419
422
  const onPop = async () => {
423
+ navigated() // a reveal still looking up its board must not land after this
420
424
  const h = parseHash()
421
425
  let s = useStore.getState()
422
426
  if (h.board && h.board !== s.board) {
@@ -435,9 +439,10 @@ export function App() {
435
439
  else enterPlay(h.play)
436
440
  } else {
437
441
  if (s.play) s.setPlay(null)
438
- const keys = (h.n ?? []).filter((k) => s.nodes.some((n) => n.key === k))
442
+ const keys = linkTargets(h, s.nodes)
439
443
  useStore.setState({ selection: keys })
440
- setTimeout(() => (keys.length ? canvasCtl.fitNodes(keys) : canvasCtl.fitAll()), 60)
444
+ if (!keys.length && h.f?.length) void revealFrame(h.f[0]) // not on this board - where it lives
445
+ else setTimeout(() => (keys.length ? canvasCtl.fitNodes(keys) : canvasCtl.fitAll()), 60)
441
446
  }
442
447
  }
443
448
  // hashchange too: pasting a link into the same tab or editing the URL bar changes
@@ -452,7 +457,7 @@ export function App() {
452
457
  // page title follows the open board (and its title, when one is set)
453
458
  const board = useStore((s) => s.board)
454
459
  const titles = useStore((s) => s.boardTitles)
455
- useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board, titles])
460
+ useEffect(() => { document.title = tabTitle(board) }, [board, titles])
456
461
 
457
462
  // favicon follows the mode: blue pack in design mode, purple pack in interact.
458
463
  // The links are rebuilt (not toggled) so the set stays deterministic; the .ico is
@@ -507,7 +512,11 @@ export function App() {
507
512
  import.meta.hot.on('sh:scenes', (m: any) => useStore.getState().setScenes(m?.scenes))
508
513
  // Live Jam presence: the daemon broadcasts the set of frames Marver is editing.
509
514
  // Camera-safe by construction - this only toggles a glow class, never moves the view.
510
- import.meta.hot.on('sh:jam-activity', (m: any) => useStore.getState().setWorking(Array.isArray(m?.frames) ? m.frames.filter((x: unknown) => typeof x === 'string') : []))
515
+ import.meta.hot.on('sh:jam-activity', (m: any) => useStore.getState().setWorkingFrom(m))
516
+ // then ask for what is lit now - a broadcast sent before this listener existed is gone - and again
517
+ // after the dev server reconnects
518
+ void useStore.getState().syncWorking()
519
+ import.meta.hot.on('vite:ws:connect', () => void useStore.getState().syncWorking())
511
520
  // Live Jam reply delivery: the daemon just wrote to a board's log - fetch it NOW instead of
512
521
  // waiting out the 30s comment poll, so the reply + notification land within a second.
513
522
  import.meta.hot.on('sh:jam-comment', (m: any) => { if (typeof m?.board === 'string') useComments.getState().poke(m.board) })
@@ -573,7 +582,8 @@ export function App() {
573
582
  if (String(data.gen ?? '') !== gen) return
574
583
  // measureNode does the rest of the admission (content frames only,
575
584
  // frame-id match, finite positive, clamped)
576
- s.measureNode(nodeKey, String(data.frame ?? ''), Number(data.ownWidth), Number(data.measuredWidth), Number(data.height))
585
+ s.measureNode(nodeKey, String(data.frame ?? ''), Number(data.ownWidth), Number(data.measuredWidth), Number(data.height),
586
+ typeof data.settled === 'boolean' ? data.settled : undefined)
577
587
  } else if (data.type === 'sh:laser-copy') {
578
588
  // laser click = copy the element's full address for the agent: WHERE it lives on
579
589
  // the canvas ([board ▸ scene]) + frame source file + css path (+ jsx source loc)
@@ -794,7 +804,7 @@ export function App() {
794
804
  <ParallelogramDuoIcon size={21} className="mark" />
795
805
  </a>
796
806
  </Tip>
797
- <span className="name" title={CONFIG.projectName || 'Marver'}>{CONFIG.projectName ? humanize(CONFIG.projectName) : 'Marver'}</span>
807
+ <span className="name" title={CONFIG.projectName || 'Marver'}>{CANVAS_NAME}</span>
798
808
  <Tip side="bottom" label={<><b>Collapse panel</b><span>⌘\</span></>}><button className="sh-ibtn" onClick={togglePanel} tabIndex={panelOpen ? 0 : -1}><PanelFilledIcon size={17} /></button></Tip>
799
809
  </div>
800
810
  <div className="sh-panel-scroll">