@marver-design/marver 0.24.0 → 0.25.1

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 +56 -0
  2. package/README.md +1 -1
  3. package/dist/anchor-DVV732zR.mjs +33 -0
  4. package/dist/anchor-check-DGZnYviN.mjs +135 -0
  5. package/dist/{bake-ZhXq-X9f.mjs → bake-BpxMZfij.mjs} +45 -6
  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-ckcinlWH.mjs → build-DKaGhoVN.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-Dx1hCVOT.mjs → comments-pTLlhjh4.mjs} +150 -20
  14. package/dist/{config-BUKprFAp.mjs → config-cKgZBRj0.mjs} +1 -1
  15. package/dist/{context-BncTXjLB.mjs → context-D2ugHqwO.mjs} +17 -123
  16. package/dist/{daemon-CQv73-jM.mjs → daemon-Cl8KXGW4.mjs} +146 -64
  17. package/dist/{dev-gv4NS6Fk.mjs → dev-Diqx1Rt8.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--3Moc4J7.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-Sa08E7wO.mjs → plugin-dTF5reck.mjs} +425 -207
  29. package/dist/{poster-B2QPvKOq.mjs → poster-D-zjYpgk.mjs} +1 -1
  30. package/dist/{profile-CrZohD6g.mjs → profile-Do0nGkXO.mjs} +1 -1
  31. package/dist/{publish-bakes-BJR3huhu.mjs → publish-bakes-C_9VZ-Mq.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-Cw96h5Kk.mjs → shot-CUlmkqFX.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-CBUfsOOT.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 +62 -21
  41. package/docs/live-jam.md +10 -5
  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 +66 -22
  48. package/src/client/shell/BoardList.tsx +54 -11
  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 -34
  53. package/src/client/shell/Toolbar.tsx +3 -1
  54. package/src/client/shell/canvas/Canvas.tsx +1 -1
  55. package/src/client/shell/canvas/FrameNode.tsx +10 -5
  56. package/src/client/shell/canvas/sleep.ts +23 -4
  57. package/src/client/shell/canvas/updates.ts +55 -0
  58. package/src/client/shell/comments-store.ts +48 -19
  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 +17 -19
  64. package/src/client/shell/pin-layout.ts +37 -0
  65. package/src/client/shell/store.ts +312 -92
  66. package/src/client/shell/styles.css +10 -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 +17 -12
  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-vXjxMHTG.mjs +0 -132
  80. package/dist/manifest-cyG3kbhk.mjs +0 -528
package/CHANGELOG.md CHANGED
@@ -2,6 +2,62 @@
2
2
 
3
3
  Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
4
4
 
5
+ ## 0.25.1 - 2026-10-17
6
+
7
+ ### Fixed
8
+
9
+ - **Comments send at once again on canvases full of glass and animation** ([#23](https://github.com/TNEP4/marver/issues/23)).
10
+ While you work, `marver dev` prepares a still copy of each frame with blur effects so resting
11
+ frames cost nothing. A frame with a looping animation (a spinner, a pulsing dot) never held
12
+ still, so its copy failed every time, was asked for again on every rest, and each ask kept a
13
+ connection open. The browser only opens six per site, so comment sends and board saves waited
14
+ behind them, sometimes for minutes. Now a frame with a looping animation simply rests paused
15
+ with no copy, a copy that cannot be made is not tried again until the frame changes, and the
16
+ canvas never waits more than 2.5 s for one.
17
+
18
+ ## 0.25.0 - 2026-10-15
19
+
20
+ ### Added
21
+
22
+ - **Edits land calmly.** When a file changes, the canvas reloads only the frames that read it - a
23
+ few at a time, the ones on screen first. A frame off screen waits until you scroll near it; one
24
+ you are using (typing in it, a laser, a comment) waits until you are done. A content frame keeps
25
+ its height while it reloads, so the rows below stay still, and the board moves once if heights
26
+ did change. The canvas page itself never reloads for a design edit. `npx marver perf` shows what
27
+ each edit reached and reloaded ([Edits land calmly](docs/boards-and-folders.md#edits-land-calmly)).
28
+ - **Comments sit on what they are about.** Every note your agent pins names an element - words it
29
+ shows (`--on`) or a selector (`--at`) - and is checked against the rendered frame while
30
+ `marver dev` runs. Markers never cover each other and stay put while you work; a follow-up goes
31
+ into its thread (`comments reply`, `comments new --thread`), and `npx marver comments move` re-pins
32
+ one ([Notes from your chat agent](docs/live-jam.md#notes-from-your-chat-agent)).
33
+ - **`npx marver marks`** prints what you have not reviewed yet - the frames waiting on you, the
34
+ ones that ask first, then the frames new since you looked - for you, or for your agent at the
35
+ start of a session.
36
+ - **`npx marver boards pin <board> <scene/frame ...>`** puts frames on a board. A frame on no
37
+ board is listed under **Not on a board** in the sidebar, and `work done` says where it belongs.
38
+
39
+ ### Changed
40
+
41
+ - **No more All Scenes.** The built-in board that held every frame is gone - it was heavy, slow
42
+ to open, and always marked. Every frame lives on the board it belongs to; a fresh canvas lands on
43
+ a `welcome` board; old All Scenes links open a real board, and a canvas that published it keeps
44
+ its threads ([Every frame on a board](docs/boards-and-folders.md#every-frame-on-a-board)).
45
+ - **Marks are exact.** They start when `marver dev` starts, so what your agent makes before you open
46
+ the canvas is new when you do. A file every frame reads - a kit, a spec's markdown, a layout -
47
+ lights every frame that reads it, even when it changed while dev was off. A look clears only the
48
+ version on screen, and a frame you opened while its new version loaded clears once it is up.
49
+ Orange now reads "waiting on you": a question comes first for `u` and keeps its own notice,
50
+ because the agent says when a reply asks
51
+ ([What is new, what needs you](docs/boards-and-folders.md#what-is-new-what-needs-you)).
52
+ - **What agents are told.** Pin each point on its element, one thread per topic, `--ask` on a reply
53
+ that asks, `npx marver marks` at the start of a session, and every frame on its board.
54
+ Upgrading: `npx marver init` updates the instructions.
55
+
56
+ ### Fixed
57
+
58
+ - 0.24 counted everything an agent did before you first opened the canvas as already seen.
59
+ - Notes pinned without an element all landed on one spot of the frame, one on top of the other.
60
+
5
61
  ## 0.24.0 - 2026-10-14
6
62
 
7
63
  ### Added
package/README.md CHANGED
@@ -40,7 +40,7 @@ Frames appear on the canvas the moment the files land. That's the loop.
40
40
 
41
41
  ## The canvas
42
42
 
43
- - **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders, two levels deep - a folder holds boards and folders, a sub-folder holds boards: right-click the Boards header (or its `+`) for a new folder, a folder for a new one inside it, name it inline, drag boards in and out at either level (the seam shows exactly where a release lands, indented with the level) and folders among boards or into a folder; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty, ranked or nested folders (a sub-folder names its `"parent"`; `npx marver boards` prints the tree). The [boards and folders guide](docs/boards-and-folders.md) has every move. Boards, folders and scenes take a `title` - any name you like, "MVP", "UI", "Checkout (v2) 🛒" - while their file, key and directory stay the slug agents address; Rename in the sidebar edits the title. Every board wears an icon for its type - start, feature, surface, project, feedback, context, deck, archive - its own or its folder's, and feature boards wear a status read from the project's `context/`. Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
43
+ - **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. Every frame goes on the board it belongs to, and a frame that belongs to two goes on both (`npx marver boards pin <board> <scene/frame ...>`); a frame on no board is listed apart, under Not on a board. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders, two levels deep - a folder holds boards and folders, a sub-folder holds boards: right-click the Boards header (or its `+`) for a new folder, a folder for a new one inside it, name it inline, drag boards in and out at either level (the seam shows exactly where a release lands, indented with the level) and folders among boards or into a folder; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty, ranked or nested folders (a sub-folder names its `"parent"`; `npx marver boards` prints the tree). The [boards and folders guide](docs/boards-and-folders.md) has every move. Boards, folders and scenes take a `title` - any name you like, "MVP", "UI", "Checkout (v2) 🛒" - while their file, key and directory stay the slug agents address; Rename in the sidebar edits the title. Every board wears an icon for its type - start, feature, surface, project, feedback, context, deck, archive - its own or its folder's, and feature boards wear a status read from the project's `context/`. Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
44
44
  - **Devices view.** Hotkeys `1`-`5` (or the Devices menu) size every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
45
45
  - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
46
46
  - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
@@ -0,0 +1,33 @@
1
+ //#region src/shared/anchor.ts
2
+ /** Read a target from untrusted input - CLI flags, a Live Jam block: exactly one of `on` / `at`, an
3
+ * optional whole `nth` from 1. A string is the reason it is not one. */
4
+ function readTarget(raw) {
5
+ const clean = (v) => typeof v === "string" || typeof v === "number" ? String(v).replace(/\s+/g, " ").trim() : "";
6
+ const on = clean(raw.on), at = clean(raw.at);
7
+ if (!on === !at) return "name the element with --on \"<words it shows>\" or --at \"<css selector or data-testid>\" (one of them)";
8
+ if ((on || at).length > MAX_TARGET) return `--on / --at take at most ${MAX_TARGET} characters - name fewer words`;
9
+ const nth = raw.nth === void 0 ? void 0 : Number(raw.nth);
10
+ if (nth !== void 0 && !(Number.isInteger(nth) && nth >= 1)) return "--nth takes a whole number from 1";
11
+ return {
12
+ ...on ? { on } : { at },
13
+ ...nth ? { nth } : {}
14
+ };
15
+ }
16
+ const MAX_TARGET = 200;
17
+ /** The anchor written when the frame cannot be checked (dev off, no Chrome, a frame that throws):
18
+ * the target alone, which the canvas resolves exactly as the check would - by its words, or by
19
+ * `at` (its test id, else its selector). One that does not resolve shows as an orphan;
20
+ * `comments move` fixes it. */
21
+ function uncheckedAnchor(t) {
22
+ const nth = t.nth ? { nth: t.nth } : {};
23
+ return t.on ? { el: {
24
+ semantics: { quote: t.on },
25
+ ...nth
26
+ } } : { el: {
27
+ semantics: {},
28
+ at: t.at,
29
+ ...nth
30
+ } };
31
+ }
32
+ //#endregion
33
+ export { readTarget, uncheckedAnchor };
@@ -0,0 +1,135 @@
1
+ import { MOUNTED, frameUrl, manifestFrame, planShot, withBrowser } from "./shot-CUlmkqFX.mjs";
2
+ //#region src/server/anchor-check.ts
3
+ /**
4
+ * The anchor check (spec 26, Part 6): `comments new --on|--at`, `comments move` and a Live Jam re-pin
5
+ * name an element by its words or a selector; the dev server loads the frame in the headless
6
+ * browser `marver shot` uses - no screenshot - and asks the frame which VISIBLE element that is
7
+ * (inspect.js `__mvAnchorCheck`). What it finds is stored as the full element bundle, so the pin
8
+ * resolves exactly on the canvas.
9
+ *
10
+ * Refused only on evidence: a frame that rendered with no match, or several. Anything that stops
11
+ * the check - no Chrome, a browser that will not start, a frame that throws, the deadline - comes
12
+ * back `unchecked`, and the caller writes the note unchecked with a warning.
13
+ */
14
+ /** End to end, a cold browser start included (most of it). */
15
+ const CHECK_MS = 2e4;
16
+ /** A request the check cannot even start on: an unknown frame, viewport or theme. */
17
+ var CheckInputError = class extends Error {};
18
+ async function checkAnchor(req, deadlineMs = 19e3) {
19
+ const theme = req.theme ?? "light";
20
+ if (!theme.trim() || theme.length > 64) throw new CheckInputError(`invalid theme "${theme}"`);
21
+ const frame = manifestFrame(req.root, req.frameId);
22
+ if (!frame) throw new CheckInputError(`unknown frame "${req.frameId}" - ids are in design/manifest.json`);
23
+ if (req.viewport && !req.viewports[req.viewport]) throw new CheckInputError(`unknown viewport "${req.viewport}" - this canvas has ${Object.keys(req.viewports).join(", ")}`);
24
+ const plan = planShot(frame, req.viewports);
25
+ const size = req.viewport ? req.viewports[req.viewport] : {
26
+ width: plan.width,
27
+ height: plan.initialHeight
28
+ };
29
+ const viewport = req.viewport ?? frame.viewport ?? (frame.slide ? "its slide stage" : frame.contentWidth ? `${size.width}px wide` : "mobile");
30
+ let timer;
31
+ const late = new Promise((done) => {
32
+ timer = setTimeout(() => done({
33
+ ok: false,
34
+ unchecked: `the check passed its ${CHECK_MS / 1e3} s deadline`
35
+ }), deadlineMs);
36
+ });
37
+ const by = Date.now() + deadlineMs;
38
+ const run = withBrowser("check", async (b) => {
39
+ const me = {};
40
+ const stop = setTimeout(() => b.abort(me, "the check timed out"), Math.max(0, by - Date.now()));
41
+ let thrown = "";
42
+ let off = () => {};
43
+ try {
44
+ const send = (method, params = {}, sid) => b.send(method, params, sid, me);
45
+ const targetId = (await send("Target.createTarget", { url: "about:blank" })).targetId;
46
+ const sid = (await send("Target.attachToTarget", {
47
+ targetId,
48
+ flatten: true
49
+ })).sessionId;
50
+ off = b.on((m) => {
51
+ if (m.sessionId === sid && m.method === "Runtime.exceptionThrown") thrown = String(m.params?.exceptionDetails?.exception?.description ?? m.params?.exceptionDetails?.text ?? "").split("\n")[0];
52
+ });
53
+ await send("Emulation.setDeviceMetricsOverride", {
54
+ width: size.width,
55
+ height: size.height,
56
+ deviceScaleFactor: 1,
57
+ mobile: false
58
+ }, sid);
59
+ await send("Page.enable", {}, sid);
60
+ await send("Runtime.enable", {}, sid);
61
+ const nav = await send("Page.navigate", { url: frameUrl(req.origin, frame, theme) }, sid);
62
+ if (nav?.errorText && nav.errorText !== "net::ERR_ABORTED") return {
63
+ ok: false,
64
+ unchecked: `the frame did not load (${nav.errorText})`
65
+ };
66
+ const evaluate = async (expression) => (await send("Runtime.evaluate", {
67
+ expression,
68
+ returnByValue: true,
69
+ awaitPromise: true
70
+ }, sid))?.result?.value;
71
+ while (!await evaluate(MOUNTED).catch(() => false)) {
72
+ if (Date.now() > by - 500) return {
73
+ ok: false,
74
+ unchecked: `the frame never rendered${thrown ? ` - it threw: ${thrown}` : ""}`
75
+ };
76
+ await new Promise((r) => setTimeout(r, 150));
77
+ }
78
+ await evaluate("document.fonts.ready.then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r(true)))))");
79
+ const error = await evaluate("window.__mvFrameError || \"\"") || thrown;
80
+ if (error) return {
81
+ ok: false,
82
+ unchecked: `the frame threw - ${error}`
83
+ };
84
+ const found = await evaluate(`window.__mvAnchorCheck ? window.__mvAnchorCheck(${JSON.stringify(req.target)}, ${JSON.stringify(req.others ?? [])}) : null`);
85
+ if (!found) return {
86
+ ok: false,
87
+ unchecked: "the frame has no Marver bridge to ask"
88
+ };
89
+ if (found.bad) throw new CheckInputError(found.bad);
90
+ if (found.transparent) return {
91
+ ok: false,
92
+ unchecked: "only a transparent element shows that now (a fade-in, a control shown on hover)"
93
+ };
94
+ if (found.none) return {
95
+ ok: false,
96
+ refused: "none",
97
+ visible: found.none,
98
+ viewport,
99
+ theme
100
+ };
101
+ if (found.several) return {
102
+ ok: false,
103
+ refused: "several",
104
+ matches: found.several,
105
+ viewport,
106
+ theme
107
+ };
108
+ return {
109
+ ok: true,
110
+ anchor: found.anchor,
111
+ holders: found.holders ?? [],
112
+ viewport,
113
+ theme
114
+ };
115
+ } finally {
116
+ clearTimeout(stop);
117
+ off();
118
+ b.abort(me, "the check finished");
119
+ }
120
+ });
121
+ try {
122
+ return await Promise.race([run, late]);
123
+ } catch (err) {
124
+ if (err instanceof CheckInputError) throw err;
125
+ return {
126
+ ok: false,
127
+ unchecked: err.message
128
+ };
129
+ } finally {
130
+ clearTimeout(timer);
131
+ run.catch(() => {});
132
+ }
133
+ }
134
+ //#endregion
135
+ export { CheckInputError, checkAnchor };
@@ -1,4 +1,4 @@
1
- import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-Cw96h5Kk.mjs";
1
+ import { AREA, SURFACE, pool, shotConcurrency, withBrowser } from "./shot-CUlmkqFX.mjs";
2
2
  import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
3
3
  import { join, sep } from "node:path";
4
4
  import { createHash } from "node:crypto";
@@ -58,6 +58,8 @@ const DSF = 2;
58
58
  * (29 px > 8 of 5.18 M, none > 32) at a quarter of the memory; 0.5x fails on 30 px pills. */
59
59
  const TEXTURE_DSF = 1;
60
60
  const DEADLINE_MS = 45e3;
61
+ /** The refusal for a frame with a looping animation: it rests paused, never compiled. */
62
+ const LOOPING = "a looping animation - the frame rests paused, uncompiled";
61
63
  /** The largest frame an ask may name, in CSS px: the shot pipeline's bitmap budget at DPR 2. */
62
64
  const ASK_MAX = {
63
65
  side: Math.floor(SURFACE / DSF),
@@ -330,6 +332,10 @@ async function bakeIn(b, opts) {
330
332
  error: `the frame did not settle (${unsettled} image(s) or chart(s) still loading)`
331
333
  };
332
334
  await ev(`Promise.all(Array.from(document.querySelectorAll('image')).map((el) => { const href = el.getAttribute('href') || el.getAttribute('xlink:href'); if (!href) return 1; const im = new Image(); im.src = new URL(href, location.href).href; return im.decode().catch(() => 1) })).then(() => true)`, true);
335
+ if (await ev(`document.getAnimations().some((a) => { const t = a.effect && a.effect.getComputedTiming(); return !!t && t.iterations === Infinity && a.playState === 'running' })`)) return {
336
+ ok: false,
337
+ error: LOOPING
338
+ };
333
339
  await ev(`Promise.race([Promise.all(document.getAnimations().map((a) => a.finished.catch(() => 1))), new Promise((r) => setTimeout(r, 5000))]).then(() => true)`, true);
334
340
  await ev(`new Promise((resolve) => { let timer = 0; const done = () => { mo.disconnect(); resolve(true) }; const mo = new MutationObserver(() => { clearTimeout(timer); timer = setTimeout(done, 250) }); mo.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true }); timer = setTimeout(done, 250); setTimeout(done, 3000) })`, true);
335
341
  await ev(PAINTED, true);
@@ -652,17 +658,33 @@ function pruneBakes(root, keep) {
652
658
  /** Compiles in flight, by generation and key: identical asks - inside one request or across
653
659
  * concurrent ones - share one compile. */
654
660
  const inflight = /* @__PURE__ */ new Map();
661
+ /** Compiles that FAILED for the frame's own reasons (it loops, never stops changing, never settles,
662
+ * timed out, has too many effects), by generation and key, so it is answered at once from memory
663
+ * instead of being compiled again on every rest. The generation is in the key: an edit retries it.
664
+ * Only these are kept - anything else (the source moved mid-compile, the browser or its pipe died,
665
+ * a cache write failed) says nothing about the frame and is tried again. */
666
+ const failed = /* @__PURE__ */ new Map();
667
+ const FAILED_MAX = 2e3;
668
+ const ofTheFrame = (error) => error === "a looping animation - the frame rests paused, uncompiled" || /^the frame (never stopped changing|did not settle|never rendered|rendered an error)|^the bake timed out$|^too many effects|^an effect larger than/.test(error);
655
669
  /** Compile many frames as ONE operation (one browser, `shotConcurrency()` at a time), the cache
656
670
  * first. `urlFor(ask)` gives the frame's own URL; `urlBase` is where textures are served from;
657
671
  * `live()` is the source generation NOW - a compile the source outran is not published. */
658
672
  async function bakeBatch(opts) {
659
- const { root, gen, asks, urlFor, urlBase, live, log } = opts;
673
+ const { root, gen, asks, urlFor, urlBase, live, log, waitMs } = opts;
660
674
  if (!cacheInside(root)) return asks.map((ask) => ({
661
675
  ...ask,
662
676
  ok: false,
663
677
  error: "design/.local/bakes resolves outside the project"
664
678
  }));
665
- const answers = asks.map((ask) => readCached(root, gen, ask, urlBase));
679
+ const failedKey = (ask) => `${root}|${gen}|${bakeKey(ask)}`;
680
+ const answers = asks.map((ask) => {
681
+ const error = failed.get(failedKey(ask));
682
+ return error !== void 0 ? {
683
+ ...ask,
684
+ ok: false,
685
+ error
686
+ } : readCached(root, gen, ask, urlBase);
687
+ });
666
688
  const protect = new Set(asks.map(bakeKey));
667
689
  const misses = /* @__PURE__ */ new Map();
668
690
  asks.forEach((ask, i) => {
@@ -694,7 +716,7 @@ async function bakeBatch(opts) {
694
716
  };
695
717
  });
696
718
  });
697
- if (mine.length) {
719
+ async function compile() {
698
720
  const settle = (job, a) => {
699
721
  job.done = true;
700
722
  job.resolve(a);
@@ -729,6 +751,10 @@ async function bakeBatch(opts) {
729
751
  error: e.message
730
752
  };
731
753
  }
754
+ if (!a.ok && ofTheFrame(a.error)) {
755
+ if (failed.size >= FAILED_MAX) failed.clear();
756
+ failed.set(failedKey(job.ask), a.error);
757
+ }
732
758
  log?.(a);
733
759
  settle(job, a);
734
760
  }));
@@ -740,8 +766,21 @@ async function bakeBatch(opts) {
740
766
  });
741
767
  }
742
768
  }
743
- await Promise.all(waits);
744
- return answers;
769
+ const all = (mine.length ? compile() : Promise.resolve()).then(() => Promise.all(waits));
770
+ if (waitMs === void 0) {
771
+ await all;
772
+ return answers;
773
+ }
774
+ let timer;
775
+ await Promise.race([all, new Promise((r) => {
776
+ timer = setTimeout(r, waitMs);
777
+ })]);
778
+ clearTimeout(timer);
779
+ return answers.map((a, i) => a ?? {
780
+ ...asks[i],
781
+ ok: false,
782
+ error: "compiling - ask again"
783
+ });
745
784
  }
746
785
  //#endregion
747
786
  export { ASK_MAX, bakeBatch, pruneBakes };
@@ -1,10 +1,3 @@
1
- import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
2
- import { join, sep } from "node:path";
3
- import { createHash } from "node:crypto";
4
- //#region src/server/hash.ts
5
- /** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
6
- const hash = (s) => createHash("sha256").update(s).digest("hex");
7
- //#endregion
8
1
  //#region src/shared/board-types.ts
9
2
  /**
10
3
  * Board types (spec 20) - what a board is FOR in the workspace, one vocabulary every canvas
@@ -160,17 +153,32 @@ const KIND_FOLDERS = {
160
153
  * board file - one slug, the folder it sits in directly), ranked among its siblings by
161
154
  * `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
162
155
  * which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
163
- * folder inside a folder (a sub-folder) holds boards only. `all-scenes` never enters the
164
- * tree - callers pin it last.
156
+ * folder inside a folder (a sub-folder) holds boards only.
165
157
  */
166
158
  /** The on-disk name grammar shared by boards and folders (a board name is a filename). */
167
159
  const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
168
160
  const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
169
161
  /** The folder registry beside the boards - underscore = infrastructure, never a board. */
170
162
  const FOLDERS_FILE = "_folders.json";
171
- /** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
172
- * off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
173
- const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
163
+ /** The built-in board every frame sat on until 0.25 (spec 26, Part 7). A reserved name: never
164
+ * created, renamed to or saved, and a leftover file is set aside - but its comment log keeps
165
+ * its name, and old links naming it still land. */
166
+ const ALL_SCENES = "all-scenes";
167
+ /** Is this basename in design/boards/ a board file? `_folders.json`, temp files, any
168
+ * off-grammar name and a leftover `all-scenes.json` are not - every lister (dev API, build,
169
+ * watcher) shares this rule. */
170
+ const isBoardFile = (f) => f.endsWith(".json") && f !== `all-scenes.json` && isBoardName(f.slice(0, -5));
171
+ /** One meaning of "on a board": the live frames a board shows - those its nodes hold, or every
172
+ * live frame when it says `"auto": true`. Every check, hint, link, mark and the Not on a board
173
+ * list asks here. */
174
+ function framesOn(board, live) {
175
+ const b = board;
176
+ if (b?.auto === true) return [...live];
177
+ const held = new Set(Array.isArray(b?.nodes) ? b.nodes.map((n) => n?.frame) : []);
178
+ return live.filter((f) => held.has(f));
179
+ }
180
+ /** Sidebar order with archive boards last - history is not where a change is reviewed. */
181
+ const archiveLast = (order, isArchive) => [...order.filter((n) => !isArchive(n)), ...order.filter(isArchive)];
174
182
  const readDescription = (v) => {
175
183
  if (typeof v !== "string") return void 0;
176
184
  return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
@@ -353,268 +361,4 @@ function folderMap(t) {
353
361
  return out;
354
362
  }
355
363
  //#endregion
356
- //#region src/server/boards.ts
357
- /**
358
- * Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
359
- * share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
360
- * live, could read or publish JSON from outside the project - it is skipped, and reported so
361
- * the build can fail closed). The folder registry is read the same way: absent = no folders,
362
- * malformed = an error the human must fix, never a silently empty registry.
363
- */
364
- /** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
365
- function underRoot(root, dir) {
366
- try {
367
- const rr = realpathSync(root);
368
- const rd = realpathSync(dir);
369
- return rd === rr || rd.startsWith(rr + sep);
370
- } catch {
371
- return false;
372
- }
373
- }
374
- /** Is design/boards a directory we may read and write? It must not be a symlink at all (a
375
- * link to the repo root would list package.json as a board and let a tree write rewrite
376
- * it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
377
- * is fine (no boards yet). Returns the error, or null. */
378
- function checkBoardsDir(root, boardsDir) {
379
- return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
380
- }
381
- /** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
382
- * a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
383
- * creates it; a symlinked `design/scenes` would let a brief write land outside the project.
384
- * An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
385
- function checkRealDirs(root, dirs) {
386
- for (const [p, label] of dirs) {
387
- try {
388
- if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
389
- } catch {
390
- return null;
391
- }
392
- if (!underRoot(root, p)) return `${label} escapes the project`;
393
- }
394
- return null;
395
- }
396
- /** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
397
- const isRegularFile = (p) => {
398
- try {
399
- return lstatSync(p).isFile();
400
- } catch {
401
- return false;
402
- }
403
- };
404
- /** Is there ANY node at p (a dangling symlink counts)? */
405
- const nodeExists = (p) => {
406
- try {
407
- lstatSync(p);
408
- return true;
409
- } catch {
410
- return false;
411
- }
412
- };
413
- /** A board file's JSON, or why it is not JSON - the parser's own words, naming the line and column (#6). */
414
- function parseBoard(content) {
415
- try {
416
- return { json: JSON.parse(content) };
417
- } catch (e) {
418
- const msg = e.message, lines = content.split("\n");
419
- return {
420
- json: null,
421
- error: /end of JSON input$/.test(msg) ? `${msg} (line ${lines.length} column ${lines[lines.length - 1].length + 1})` : msg
422
- };
423
- }
424
- }
425
- /** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
426
- * names the entries that looked like boards but were not regular files. */
427
- function listBoardFiles(boardsDir) {
428
- const boards = [], skipped = [];
429
- if (!existsSync(boardsDir)) return {
430
- boards,
431
- skipped
432
- };
433
- for (const f of readdirSync(boardsDir)) {
434
- if (!isBoardFile(f)) continue;
435
- const file = join(boardsDir, f);
436
- if (!isRegularFile(file)) {
437
- skipped.push(f);
438
- continue;
439
- }
440
- const content = readFileSync(file, "utf8");
441
- boards.push({
442
- name: f.slice(0, -5),
443
- file,
444
- content,
445
- sha256: hash(content),
446
- ...parseBoard(content)
447
- });
448
- }
449
- return {
450
- boards,
451
- skipped
452
- };
453
- }
454
- function boardFields(json, validName) {
455
- const o = json;
456
- const title = readTitle(o?.title);
457
- const description = readDescription(o?.description);
458
- const type = readType(o?.type), capability = readCapability(o?.capability), status = readStatusWord(o?.status), reason = readReason(o?.reason);
459
- return {
460
- ...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
461
- ...validName(o?.folder) ? { folder: o.folder } : {},
462
- ...title ? { title } : {},
463
- ...description ? { description } : {},
464
- ...type ? { type } : {},
465
- ...capability ? { capability } : {},
466
- ...status ? { status } : {},
467
- ...reason ? { reason } : {}
468
- };
469
- }
470
- /** The fields a board's file owns that the shell's save shape never carries: an autosave keeps
471
- * each one from disk when the incoming board omits it (spec 20 - the fields survive every write). */
472
- const AUTHOR_FIELDS = [
473
- "order",
474
- "folder",
475
- "title",
476
- "description",
477
- "type",
478
- "capability",
479
- "status",
480
- "reason"
481
- ];
482
- /** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
483
- * no file"), so a write can never silently replace a registry it never saw. */
484
- function readRegistry(boardsDir) {
485
- const p = join(boardsDir, FOLDERS_FILE);
486
- if (!nodeExists(p)) return {
487
- state: "absent",
488
- folders: [],
489
- sha256: null
490
- };
491
- if (!isRegularFile(p)) return {
492
- state: "malformed",
493
- error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
494
- sha256: null
495
- };
496
- const content = readFileSync(p, "utf8");
497
- let raw;
498
- try {
499
- raw = JSON.parse(content);
500
- } catch {
501
- return {
502
- state: "malformed",
503
- error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
504
- sha256: hash(content)
505
- };
506
- }
507
- const parsed = parseFolders(raw);
508
- if (typeof parsed === "string") return {
509
- state: "malformed",
510
- error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
511
- sha256: hash(content)
512
- };
513
- return {
514
- state: "ok",
515
- folders: parsed,
516
- sha256: hash(content)
517
- };
518
- }
519
- /** The registry's write lock - one writer at a time across processes (the dev server's tree write,
520
- * `folders add`, `init --kind`), so a read-modify-write of `_folders.json` is atomic among Marver's
521
- * writers. A lock older than 10 s is a crashed writer's and is taken over. `wait` = how long to
522
- * try (the CLI waits; the dev server never blocks its event loop - it answers 409 instead). */
523
- const REGISTRY_LOCK = ".folders.lock";
524
- function withRegistryLock(dir, wait, fn) {
525
- const lock = join(dir, REGISTRY_LOCK);
526
- const t0 = Date.now();
527
- for (;;) try {
528
- writeFileSync(lock, `${process.pid} ${Date.now()}\n`, { flag: "wx" });
529
- break;
530
- } catch (e) {
531
- if (e.code !== "EEXIST") throw e;
532
- try {
533
- if (Date.now() - lstatSync(lock).mtimeMs > 1e4) {
534
- rmSync(lock, { force: true });
535
- continue;
536
- }
537
- } catch {
538
- continue;
539
- }
540
- if (Date.now() - t0 >= wait) return null;
541
- Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
542
- }
543
- try {
544
- return fn();
545
- } finally {
546
- rmSync(lock, { force: true });
547
- }
548
- }
549
- /** Append typed folders to the registry (spec 20: `init --kind`, `folders add`). Never renames,
550
- * moves or retypes a folder that exists - a name already registered is skipped and reported - and
551
- * never drops a field of an existing entry it does not manage. New folders rank after everything
552
- * already at the root. The write is compare-and-swap: the registry is re-read just before the
553
- * atomic rename, and a change since the first read (the shell's drag, another agent) starts the
554
- * append over from the new file. A malformed registry is an error, never overwritten. */
555
- function addFolders(root, folders) {
556
- const dir = join(root, "design", "boards");
557
- const de = checkBoardsDir(root, dir);
558
- if (de) throw new Error(de);
559
- mkdirSync(dir, { recursive: true });
560
- const file = join(dir, FOLDERS_FILE);
561
- const done = withRegistryLock(dir, 5e3, () => appendFolders(dir, file, folders));
562
- if (!done) throw new Error(`design/boards/${FOLDERS_FILE} is being written by another process - try again`);
563
- return done;
564
- }
565
- function appendFolders(dir, file, folders) {
566
- for (let attempt = 0; attempt < 5; attempt++) {
567
- const before = nodeExists(file) ? readFileSync(file, "utf8") : null;
568
- const reg = readRegistry(dir);
569
- if (reg.state === "malformed") throw new Error(reg.error);
570
- let raw = [];
571
- if (before !== null) {
572
- const j = JSON.parse(before);
573
- raw = Array.isArray(j.folders) ? j.folders : [];
574
- }
575
- const have = new Set(raw.map((f) => f.name));
576
- const rootRanks = [...raw.filter((f) => f.parent === void 0).map((f) => f.order), ...listBoardFiles(dir).boards.map((b) => {
577
- const o = b.json;
578
- return o?.folder ? void 0 : o?.order;
579
- })].filter((o) => typeof o === "number" && Number.isFinite(o));
580
- let next = rootRanks.length ? Math.max(...rootRanks) + 1 : 0;
581
- const added = [], existing = [];
582
- const rows = [...raw];
583
- for (const f of folders) {
584
- if (have.has(f.name)) {
585
- existing.push(f.name);
586
- continue;
587
- }
588
- rows.push({
589
- name: f.name,
590
- order: next++,
591
- ...f.title ? { title: f.title } : {},
592
- ...f.type ? { type: f.type } : {}
593
- });
594
- have.add(f.name);
595
- added.push(f.name);
596
- }
597
- if (!added.length) return {
598
- added,
599
- existing
600
- };
601
- const version = rows.some((f) => f.parent !== void 0) ? 2 : 1;
602
- const tmp = `${file}.${process.pid}.${Date.now()}.${attempt}.tmp`;
603
- writeFileSync(tmp, JSON.stringify({
604
- version,
605
- folders: rows
606
- }, null, 2) + "\n", { flag: "wx" });
607
- if ((nodeExists(file) ? readFileSync(file, "utf8") : null) !== before) {
608
- rmSync(tmp, { force: true });
609
- continue;
610
- }
611
- renameSync(tmp, file);
612
- return {
613
- added,
614
- existing
615
- };
616
- }
617
- throw new Error(`design/boards/${FOLDERS_FILE} kept changing while folders were added - try again`);
618
- }
619
- //#endregion
620
- export { knownType as A, wireKids as C, HAS_STATUS as D, FOLDER_MODULES as E, resolveType as F, settableStatuses as I, hash as L, readReason as M, readStatusWord as N, KIND_FOLDERS as O, readType as P, validateWire as S, DECISIONS as T, folderMap as _, checkRealDirs as a, readDescription as b, nodeExists as c, withRegistryLock as d, BOARD_NAME as f, folderEntries as g, flatten as h, checkBoardsDir as i, readCapability as j, PROPOSED_PUBLISH as k, parseBoard as l, buildTree as m, addFolders as n, isRegularFile as o, FOLDERS_FILE as p, boardFields as r, listBoardFiles as s, AUTHOR_FIELDS as t, readRegistry as u, humanize as v, BOARD_TYPES as w, readTitle as x, isBoardName as y };
364
+ export { settableStatuses as A, PROPOSED_PUBLISH as C, readStatusWord as D, readReason as E, readType as O, KIND_FOLDERS as S, readCapability as T, wireKids as _, buildTree as a, FOLDER_MODULES as b, folderMap as c, isBoardFile as d, isBoardName as f, validateWire as g, readTitle as h, archiveLast as i, resolveType as k, framesOn as l, readDescription as m, BOARD_NAME as n, flatten as o, parseFolders as p, FOLDERS_FILE as r, folderEntries as s, ALL_SCENES as t, humanize as u, BOARD_TYPES as v, knownType as w, HAS_STATUS as x, DECISIONS as y };