@dev.fast/whiteboard 0.4.1-preview.20261027.141 → 0.4.1-preview.20261028.142

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 (70) hide show
  1. package/dist/{account-alias-AJ6miBT5.js → account-alias-D1iIc7j5.js} +4 -5
  2. package/dist/{agent-cli-DIC2tBpL.js → agent-cli-B_gSzrhA.js} +8 -9
  3. package/dist/agent-cli-DtjnkDSL.js +2 -0
  4. package/dist/{agent-client-DyNmSHfO.js → agent-client-DudPjH3I.js} +3 -3
  5. package/dist/{authoring-tools-B9MhiKw4.js → authoring-tools-B-OyXmtR.js} +5 -5
  6. package/dist/{background-server-CZaB8zFH.js → background-server-CORnMQmu.js} +1 -1
  7. package/dist/{background-server-DlgbnDVt.js → background-server-CesuMV6N.js} +7 -6
  8. package/dist/build-info.json +1 -1
  9. package/dist/{cli-D7Lpc4ws.js → cli-CIP_-Fvm.js} +1 -1
  10. package/dist/{cli-runner-JPkbHD7I.js → cli-runner-dHnKnyNw.js} +22 -23
  11. package/dist/cli.js +2 -2
  12. package/dist/{fuzzy-match-rWIeloqo.js → fuzzy-match-CTvayutE.js} +3 -3
  13. package/dist/{headless-host-Cn6WDmaL.js → headless-host-CWuFw-CO.js} +118 -218
  14. package/dist/{headless-host-DmuAjcgt.js → headless-host-Cnu-o0xk.js} +1 -1
  15. package/dist/{import-CUNdl3NP.js → import-FOpJL22V.js} +198 -505
  16. package/dist/{lens-selection-BQxqiuWY.js → lens-selection-B_LTVyTB.js} +1 -1
  17. package/dist/{local-data-DxkQXCNG.js → local-data-BhNZ1Yep.js} +72 -91
  18. package/dist/{mcp-B154Vpj0.js → mcp-2bWqlJNW.js} +3 -3
  19. package/dist/{package-paths-LcO6HNp_.js → package-paths-Cg6fnaGp.js} +1 -1
  20. package/dist/profile-BmtFpq8d.js +2 -0
  21. package/dist/{profile-hC1iAoRB.js → profile-DnwIJvlh.js} +2 -2
  22. package/dist/{remote-attach-DhvNHMe1.js → remote-attach-C79X5M2Z.js} +4 -4
  23. package/dist/{remote-extensions-VLpt_4Tn.js → remote-extensions-Bw029iIS.js} +1 -1
  24. package/dist/{remote-extensions-DMKyDjAs.js → remote-extensions-MUUgbLJn.js} +2 -2
  25. package/dist/{remote-language-server-zgvAe8wb.js → remote-language-server-Dw1o27aF.js} +4 -4
  26. package/dist/{remote-uninstall-BR-rIuvK.js → remote-uninstall-Aza0u1_3.js} +5 -5
  27. package/dist/{request-origin-BnA7Nnca.js → request-origin-DEQd09Db.js} +3 -3
  28. package/dist/{review-app-launcher-B0Z4B8By.js → review-app-launcher-L7xKjTLQ.js} +2 -2
  29. package/dist/{src-KTjWplV9.js → review-home-paths-LdGS4SpR.js} +48 -8
  30. package/dist/{review-telemetry-yuCLNpDu.js → review-telemetry-lmK8HPLI.js} +4 -5
  31. package/dist/{runtime-5WG8rRgg.js → runtime-Bhk5L_SN.js} +1 -1
  32. package/dist/runtime.js +1 -1
  33. package/dist/server/desktop-host.js +34 -48
  34. package/dist/{server-discovery-Dj_xSDSa.js → server-discovery-D-2vz5gG.js} +2 -3
  35. package/dist/sharing/index.d.ts +51 -144
  36. package/dist/sharing/index.js +2 -2
  37. package/dist/{src-BJ_MeEmN.js → src-Bew3mW9I.js} +1 -1
  38. package/dist/{src-BTCRHmRM.js → src-Y30gweiK.js} +7 -1
  39. package/dist/{stored-document-migration-fQWLDqDx.js → stored-document-migration-CZe65mkx.js} +20 -6
  40. package/dist/{thread-state-BburMvgn.js → thread-state-XgVKaQ3-.js} +1 -1
  41. package/dist/{tool-failure-BuvwfVeF.js → tool-failure-Bi_-Zck-.js} +2 -2
  42. package/instructions/animation.md +18 -68
  43. package/instructions/authoring.md +1 -1
  44. package/package.json +5 -5
  45. package/src/review-api/README.md +5 -5
  46. package/src/review-api/ask-history.ts +3 -13
  47. package/src/review-api/authoring-tools.ts +2 -2
  48. package/src/review-api/blocks/animation.ts +50 -0
  49. package/src/review-api/http.ts +213 -383
  50. package/src/review-api/local-data.ts +24 -53
  51. package/src/review-api/review-progress.ts +1 -5
  52. package/src/review-api/store.ts +95 -16
  53. package/src/review-api/workspaces.ts +17 -48
  54. package/src/review-checkout-paths.ts +2 -5
  55. package/src/review-head-checkout.ts +3 -14
  56. package/src/server/background-server.ts +4 -2
  57. package/src/server/desktop-host.ts +17 -9
  58. package/src/server/desktop-server.ts +4 -6
  59. package/src/server/json-review-reporting.ts +4 -23
  60. package/src/server/review-gateway-pushes.ts +1 -10
  61. package/src/server/review-server-core.ts +8 -13
  62. package/src/sharing/client.ts +86 -2
  63. package/src/sharing/host.ts +111 -88
  64. package/src/sharing/import.ts +173 -710
  65. package/src/sharing/index.ts +1 -7
  66. package/src/sharing/repository.ts +18 -49
  67. package/dist/agent-cli-BDcF54b3.js +0 -2
  68. package/dist/profile-BLToeYh6.js +0 -2
  69. package/dist/review-home-paths-CjHB5c8m.js +0 -39
  70. package/src/sharing/routes.ts +0 -35
@@ -711,6 +711,12 @@ const LARGE_READS = /* @__PURE__ */ new Set([
711
711
  "rev-list",
712
712
  "show"
713
713
  ]);
714
+ const TREE_WRITES = /* @__PURE__ */ new Set([
715
+ "checkout",
716
+ "read-tree",
717
+ "reset",
718
+ "worktree"
719
+ ]);
714
720
  const VALUED_OPTIONS = [
715
721
  "-C",
716
722
  "-c",
@@ -736,7 +742,7 @@ const namesRepository = (args) => args.slice(0, subcommandIndex(args)).some((arg
736
742
  function defaultVcsTimeout(tool, args) {
737
743
  if (talksToRemote(args)) return NETWORK_TIMEOUT_MS;
738
744
  const command = args[subcommandIndex(args)];
739
- if (tool === "jj" || command && LARGE_READS.has(command)) return LARGE_READ_TIMEOUT_MS;
745
+ if (tool === "jj" || command && (LARGE_READS.has(command) || TREE_WRITES.has(command))) return LARGE_READ_TIMEOUT_MS;
740
746
  return QUICK_TIMEOUT_MS;
741
747
  }
742
748
  const COMMIT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
@@ -1,8 +1,8 @@
1
- import { C as renderVcsArgs, v as parseGitRemote, w as runVcs } from "./src-BTCRHmRM.js";
1
+ import { C as renderVcsArgs, v as parseGitRemote, w as runVcs } from "./src-Y30gweiK.js";
2
2
  import { d as isBooleanValue, f as isNumberValue, l as jsonValueSchema, m as isStringValue, n as isJsonObject, t as isJsonArray } from "./src-X9phtB2j.js";
3
- import "./src-BJ_MeEmN.js";
4
- import "./src-KTjWplV9.js";
5
- import { a as commitLinkTarget, c as parseAnchor, d as selectionProblem, f as sourceAnchors, i as anchorSelection, r as anchorSchema, s as formatAnchor } from "./lens-selection-BQxqiuWY.js";
3
+ import "./src-Bew3mW9I.js";
4
+ import "./review-home-paths-LdGS4SpR.js";
5
+ import { a as commitLinkTarget, c as parseAnchor, d as selectionProblem, f as sourceAnchors, i as anchorSelection, r as anchorSchema, s as formatAnchor } from "./lens-selection-B_LTVyTB.js";
6
6
  import { t as ReviewInputError } from "./input-error-OLgB_h31.js";
7
7
  import { t as errorMessage } from "./error-message-OtiDonty.js";
8
8
  import { randomUUID } from "node:crypto";
@@ -1051,20 +1051,34 @@ const animationFrameSchema = z.strictObject({
1051
1051
  caption: text$1.optional().describe("One or two short sentences shown under the stage."),
1052
1052
  duration: z.number().int().min(300).max(3e4).optional().describe("Milliseconds this frame stays up while playing. Default 3000.")
1053
1053
  });
1054
+ const animationScenarioSchema = z.strictObject({
1055
+ key: handle.describe("Names the scenario."),
1056
+ label: z.string().min(1).max(32).describe("What the reader picks above the stage, e.g. Retried request. Keep it short."),
1057
+ frames: z.array(handle).min(1).max(60).describe("The frame keys this scenario plays, in order.")
1058
+ });
1054
1059
  const animation = {
1055
1060
  type: "animation",
1056
1061
  schema: defineBlock("animation", {
1057
1062
  title: label$1,
1058
1063
  html: text$1.min(1).max(2e5).describe("The stage's body markup: elements, <style> and <script>. It runs in a sandboxed frame with a global `whiteboard` shim; see session_get_instructions({topic:\"animation\"})."),
1059
1064
  frames: z.array(animationFrameSchema).min(1).max(60).describe("Every possible frame. Stage scripts may select an ordered branch with whiteboard.setSequence(keys); keys stay unique and stable."),
1065
+ scenarios: z.array(animationScenarioSchema).min(2).max(8).optional().describe("Alternate paths through the frames. The whiteboard draws a labelled scenario picker above the stage and starts on the first one."),
1060
1066
  code: z.record(handle, anchorSchema).default({}).describe("Source ranges the stage shows as code peeks, by name: whiteboard.code(name)."),
1061
1067
  height: z.union([z.literal("auto"), z.number().int().min(120).max(1200)]).default("auto").describe("Fit the stage to its content by default, or set a fixed height in CSS pixels."),
1062
1068
  pins: elementPins
1063
1069
  }),
1064
1070
  check(block) {
1065
- if (new Set(block.frames.map((frame) => frame.key)).size !== block.frames.length) throw new ReviewInputError("Animation frame keys must be unique within the animation.");
1071
+ const keys = new Set(block.frames.map((frame) => frame.key));
1072
+ if (keys.size !== block.frames.length) throw new ReviewInputError("Animation frame keys must be unique within the animation.");
1066
1073
  const labelled = block.frames.filter((frame) => frame.label).length;
1067
1074
  if (labelled && labelled !== block.frames.length) throw new ReviewInputError("Give every animation frame a label, or none: the step strip needs one per frame.");
1075
+ const scenarios = block.scenarios ?? [];
1076
+ if (new Set(scenarios.map((scenario) => scenario.key)).size !== scenarios.length) throw new ReviewInputError("Animation scenario keys must be unique within the animation.");
1077
+ for (const scenario of scenarios) {
1078
+ if (new Set(scenario.frames).size !== scenario.frames.length) throw new ReviewInputError(`Scenario "${scenario.key}" lists a frame twice.`);
1079
+ const unknown = scenario.frames.find((key) => !keys.has(key));
1080
+ if (unknown) throw new ReviewInputError(`Scenario "${scenario.key}" names frame "${unknown}", which the animation does not declare.`);
1081
+ }
1068
1082
  }
1069
1083
  };
1070
1084
  //#endregion
@@ -3339,4 +3353,4 @@ function liftFileLenses(document) {
3339
3353
  };
3340
3354
  }
3341
3355
  //#endregion
3342
- export { UNCATEGORIZED_LENS_ID as $, commitLinkCommits as A, readsAtBoardPins as B, adoptFlowUnits as C, assignMissingIds as D, assignFreshIds as E, pathTargetSchema as F, respellEditLinks as G, resourceReferences as H, pinDocumentReferences as I, sourceReferences as J, reviewTargetSchema as K, pinnedRepositoryIds as L, editSchema as M, elements as N, boardLinks as O, explicitPins as P, stepSources as Q, pinsSchema as R, parseUnifiedPatch as S, applyEdit as T, respellCommitLinks as U, resourceReference as V, respellDocumentLinks as W, checkReferences as X, summarizeEdit as Y, documentAdvice as Z, fetchPullRequest as _, SoftwareModelValidationError as a, checkSourcePath as at, textIncludesQuote as b, traceSchema as c, sliceSourceRange as ct, setPullRequest as d, parseMarkdown as dt, applyLensEdit as et, sourceBranchName as f, defaultPullRequestDeps as g, GitHubRefusedRead as h, readStoredDocument as i, SourceRangeError as it, documentSchema as j, boardRepositoryId as k, pullRequestKey as l, markdownNodes as lt, resolvePullRequest as m, migrateStoredDocument as n, lensSchema as nt, defineSoftwareMap as o, fileLineRangeSchema as ot, pullRequestProvider as p, selectionReferences as q, migrateStoredLenses as r, lensSelections as rt, softwareModelDataSchema as s, requireVisibleSource as st, liftFileLenses as t, lensEditSchema as tt, pullRequestUrl as u, markdownText as ut, remoteUrls as v, anchorPins as w, textualRows as x, azureRepositoryOf as y, publishedEdits as z };
3356
+ export { applyLensEdit as $, documentSchema as A, resourceReference as B, adoptFlowUnits as C, boardLinks as D, assignMissingIds as E, pinDocumentReferences as F, reviewTargetSchema as G, respellCommitLinks as H, pinnedRepositoryIds as I, summarizeEdit as J, selectionReferences as K, pinsSchema as L, elements as M, explicitPins as N, boardRepositoryId as O, pathTargetSchema as P, UNCATEGORIZED_LENS_ID as Q, publishedEdits as R, parseUnifiedPatch as S, applyEdit as T, respellDocumentLinks as U, resourceReferences as V, respellEditLinks as W, documentAdvice as X, checkReferences as Y, stepSources as Z, fetchPullRequest as _, SoftwareModelValidationError as a, fileLineRangeSchema as at, textIncludesQuote as b, traceSchema as c, markdownNodes as ct, setPullRequest as d, lensEditSchema as et, sourceBranchName as f, defaultPullRequestDeps as g, GitHubRefusedRead as h, readStoredDocument as i, checkSourcePath as it, editSchema as j, commitLinkCommits as k, pullRequestKey as l, markdownText as lt, resolvePullRequest as m, migrateStoredDocument as n, lensSelections as nt, defineSoftwareMap as o, requireVisibleSource as ot, pullRequestProvider as p, sourceReferences as q, migrateStoredLenses as r, SourceRangeError as rt, softwareModelDataSchema as s, sliceSourceRange as st, liftFileLenses as t, lensSchema as tt, pullRequestUrl as u, parseMarkdown as ut, remoteUrls as v, anchorPins as w, textualRows as x, azureRepositoryOf as y, readsAtBoardPins as z };
@@ -1,4 +1,4 @@
1
- import { M as ReviewSelectedDiffSchema, T as ReviewApiSelectionSourceSchema } from "./src-BJ_MeEmN.js";
1
+ import { M as ReviewSelectedDiffSchema, T as ReviewApiSelectionSourceSchema } from "./src-Bew3mW9I.js";
2
2
  import { z } from "zod";
3
3
  /** A semantic selection, independent of comment/thread creation. */
4
4
  const AgentSelectionSchema = z.strictObject({
@@ -1,6 +1,6 @@
1
1
  import { m as isStringValue, n as isJsonObject } from "./src-X9phtB2j.js";
2
- import { l as boardTitle } from "./src-BJ_MeEmN.js";
3
- import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-DyNmSHfO.js";
2
+ import { l as boardTitle } from "./src-Bew3mW9I.js";
3
+ import { n as callAuthoringTool, s as ReviewApiError, t as ToolText } from "./agent-client-DudPjH3I.js";
4
4
  import { t as ReviewInputError } from "./input-error-OLgB_h31.js";
5
5
  //#region src/review-api/public-tools.ts
6
6
  function publicDescription(text) {
@@ -7,10 +7,9 @@ Choose where to start by what changes between the frames:
7
7
  | Build with | When the frames show |
8
8
  | --- | --- |
9
9
  | The scene (`whiteboard.scene`) | Up to about 8 cards whose notes, text and tones change, with chips moving along their edges. This is the default. |
10
- | Mermaid (`whiteboard.mermaid`) | A larger diagram, or one with branches or subgroups, whose nodes and edges appear, leave or light up. Its labels stay fixed: use the scene if they must change. |
11
10
  | The toolkit, style kit and raw HTML | Anything else: a chart, a timeline, a queue, a custom shape, or motion the scene cannot express (`arrow`, `token`, `travel`, `timeline`). |
12
11
 
13
- If no part of the drawing changes between frames, it is not an animation: use a `sequence` or `flow_diagram` block, whose steps and nodes link to code. The three mix: a stage can hold a scene, a Mermaid diagram and your own HTML together.
12
+ If no part of the drawing changes between frames, it is not an animation: use a `sequence` or `flow_diagram` block, whose steps and nodes link to code. For a larger graph, animate only the part that changes as a scene, and put the whole graph in a `flow_diagram` beside it. The two mix: a stage can hold a scene and your own HTML together.
14
13
 
15
14
  ## The component
16
15
 
@@ -39,7 +38,8 @@ If no part of the drawing changes between frames, it is not an animation: use a
39
38
  }
40
39
  ```
41
40
 
42
- - `frames`: every possible step. `key` names the frame for your markup and scripts; `title` and `caption` show under the stage. `label` is a short step name (e.g. `SEND`); give every frame one, or none, and the reader gets a named step strip instead of dots. `duration` (ms, default 3000) is how long the frame holds while playing. For a flow with alternate branches, declare every stable frame here and select the active ordered path with `whiteboard.setSequence(...)`.
41
+ - `frames`: every possible step. `key` names the frame for your markup and scripts; `title` and `caption` show under the stage. `label` is a short step name (e.g. `SEND`); give every frame one, or none, and the reader gets a named step strip instead of dots. `duration` (ms, default 3000) is how long the frame holds while playing. For a flow with alternate paths, declare every frame here and list the paths in `scenarios`.
42
+ - `scenarios`: alternate paths through the frames, 2 to 8, each `{ "key", "label", "frames": [frame keys in order] }`. The whiteboard draws a picker labelled Scenario above the stage and starts on the first. `label` is what the reader picks, e.g. `Retried request`. Omit it for an animation with one path.
43
43
  - `code`: the source ranges the stage shows, by name. The server checks each anchor like any other reference, so verify paths and lines. Use `head/` for the new code and `base/` for the old.
44
44
  - `pins`: as on any block that quotes code. A review with a target lends its own; a board without one needs them on the block.
45
45
  - `html`: the stage's body. It runs in a sandboxed frame with no network: inline `<style>` and `<script>` only, no external URLs. Images must be `data:` URLs.
@@ -104,11 +104,11 @@ If no part of the drawing changes between frames, it is not an animation: use a
104
104
 
105
105
  A scene appends to the stage body by default. To compose it with your own headings, text or controls, pass a container selector or element: `whiteboard.scene({ columns: 3, container: "#diagram" })`. Badges stay with that container too.
106
106
 
107
- When the container is too narrow for readable cards, the scene stacks its cells in row/column order. Widening restores the declared grid. Tables wrap their content. Hidden cards, store items and table rows take no space, so auto height follows visible content. Use `responsive: false` for an intentional fixed grid with your own responsive or scrolling plan.
107
+ When the container is too narrow for the declared columns, the scene folds into fewer, in row/column order: four columns become two rows of two, and a cell spanning columns takes a whole row. Narrower still, it stacks into one column. Widening restores the declared grid. Tables wrap their content. Hidden cards, store items and table rows take no space, so auto height follows visible content. Use `responsive: false` for an intentional fixed grid with your own responsive or scrolling plan.
108
108
 
109
109
  The scene keeps three things consistent for you:
110
110
 
111
- - **Spacing.** Cards sit in grid cells with a fixed gap. You choose the cell; the scene sets the gap and the padding. Four cards fit a sufficiently wide row; narrower containers stack them. Past four, prefer a second row.
111
+ - **Spacing.** Cards sit in grid cells. You choose the cell; the scene sets the padding and the gap, widening the gap between columns to fit the longest label on a link within a row. At the default document width, three cards with short link labels fit a row; a fourth folds the row in two until the reader widens the document or goes fullscreen. Past four, prefer a second row.
112
112
  - **Edges.** `link` draws one straight line from the center of one card's nearest side to the other's, with one weight and one arrowhead. `dashed: true` means async (a reply, a stream, a background send). A second edge between the same two cards offsets beside the first.
113
113
  - **Moving blocks.** `send` is the only way to move a block along an edge. The chip rides the edge's line at one fixed speed, so a longer edge takes longer, and every chip moves at the same pace. It fades out on arrival unless you pass `stay: true`.
114
114
 
@@ -154,58 +154,7 @@ table.row(cells: string[], { enter?; exit?; only?; tone? }): HTMLTableRowElement
154
154
 
155
155
  ### Frames
156
156
 
157
- The stage sets `data-frame="<key>"` on `<html>`, and `enter` / `exit` / `only` on any scene part decide the frames it shows in. They are states, not events, so they land right when the reader jumps to a frame or steps back. With `setSequence`, `enter` / `exit` and held `scene.on` changes follow active-sequence order, not declaration order: a change whose key is outside the active path does not apply, an inactive `enter` never occurs, and an inactive `exit` does not end an already-entered part. `only` and highlight lists always match exact stable keys. Visible cards keep their declared wide-grid cells. Hidden cards, store items and table rows collapse from layout; put replacing cards in the same cell. For an intentionally stable footprint, give the container a min-height or choose a fixed stage height with an appropriate scrolling plan.
158
-
159
- ## Draw with Mermaid
160
-
161
- `whiteboard.mermaid(text)` draws a Mermaid diagram in the stage's theme, lays it out for you, and shows its parts frame by frame. Use it when the frames change a diagram too large to place card by card: a pipeline whose stages light up in turn, a state machine stepping through its states, a graph that grows as a request spreads. Use the scene when a few cards carry chips along their edges; Mermaid has no `send`.
162
-
163
- Mermaid nodes do not link to code. A diagram that stays the same in every frame belongs in a `flow_diagram` or `sequence` block, not in an animation.
164
-
165
- ```html
166
- <script>
167
- const d = whiteboard.mermaid(`flowchart LR
168
- agent[Agent] e1@-->|call| api(Review API)
169
- api e2@-->|edit op| store[(Store)]
170
- store e3@-.->|snapshot| canvas[Canvas]`);
171
-
172
- d.highlight("call", "agent", "e1")
173
- .enter("write", "store", "e2")
174
- .on("write", "store", { tone: "modified" })
175
- .enter("watch", "canvas", "e3")
176
- .on("watch", "canvas", { tone: "added" });
177
- </script>
178
- ```
179
-
180
- Name a part by its Mermaid id:
181
-
182
- - A node by its id: `api` above.
183
- - An edge by the id you give it with `@`: `a e1@--> b`. Name every edge you will reveal or light up. An unnamed flowchart edge is `L_<from>_<to>_<n>`, counting from 0.
184
- - In a sequence diagram, a participant by its name, and a message as `i0`, `i1`, … in the order they appear.
185
-
186
- `d.ids` lists every part in the drawing, and a call naming a part the drawing lacks throws with that list.
187
-
188
- ```ts
189
- whiteboard.mermaid(text: string, options?: { container?: string | Element }): MermaidDiagram;
190
-
191
- interface MermaidDiagram {
192
- readonly element: HTMLElement; // the diagram's box
193
- readonly ids: readonly string[];
194
- enter(frame: string, ...ids: string[]): MermaidDiagram; // show from this frame on
195
- exit(frame: string, ...ids: string[]): MermaidDiagram; // hide from this frame on
196
- only(frames: string | string[], ...ids: string[]): MermaidDiagram;
197
- highlight(frames: string | string[], ...ids: string[]): MermaidDiagram; // ring during these frames
198
- on(frame: string, ids: string | string[], change: { tone: Tone | "none" }): MermaidDiagram;
199
- }
200
- ```
201
-
202
- - The whole diagram is laid out once, from its full text, and parts that have not entered keep their place. Nothing moves as parts appear, so write the text for the last frame and reveal it frame by frame.
203
- - `enter`, `exit`, `only` and `highlight` follow the same rules as on scene parts, active sequences included. A solid edge draws in along its line as it enters; a dashed one fades in. An edge's label shows and hides with it.
204
- - `on` gives nodes and edges a tone from that frame on, as `scene.on` does; `"none"` clears it.
205
- - The diagram follows the stage's colors, faces and theme. Leave out Mermaid's `style`, `classDef` and `%%{init}%%` theming: they fix colors that do not follow light and dark. Use tones instead. Links and `click` actions do nothing in the stage.
206
- - The diagram fits its box's width and draws again when that width changes. A diagram that runs across and does not fit a narrow box is drawn running down instead of shrunk, so a `flowchart LR` may show top to bottom in the document column. Your frame changes carry over to the new drawing, but an element you hold from `d.element` does not: look parts up again inside a frame handler.
207
- - Any Mermaid diagram type draws. Highlights and tones color nodes and edges. Flowchart and sequence diagrams name their parts as above. State, class and ER diagrams name nodes by their ids too, but make up their own edge ids, such as `edge0`; read them from `d.ids`.
208
- - Text Mermaid cannot parse shows its error under the stage.
157
+ The stage sets `data-frame="<key>"` on `<html>`, and `enter` / `exit` / `only` on any scene part decide the frames it shows in. They are states, not events, so they land right when the reader jumps to a frame or steps back. With an active path (a scenario, or `setSequence`), `enter` / `exit` and held `scene.on` changes follow active-path order, not declaration order: a change whose key is outside the active path does not apply, an inactive `enter` never occurs, and an inactive `exit` does not end an already-entered part. `only` and highlight lists always match exact stable keys. Visible cards keep their declared wide-grid cells. Hidden cards, store items and table rows collapse from layout; put replacing cards in the same cell. For an intentionally stable footprint, give the container a min-height or choose a fixed stage height with an appropriate scrolling plan.
209
158
 
210
159
  ## Going further: the toolkit
211
160
 
@@ -300,19 +249,19 @@ readonly theme; readonly colorScheme: "light" | "dark"; readonly reducedMotion;
300
249
 
301
250
  `whiteboard.frame` is the current frame object, not its key. For keyed state, read `whiteboard.frame.key` or use the handler argument: `whiteboard.on("*", ({ frame }) => render(frame.key))`.
302
251
 
303
- For alternate paths, call `whiteboard.setSequence(["start", "branch-a", "done"])`. Every key must be a unique frame declared in the component. Repeating the same sequence is a no-op, so it is safe to call from a render path. The selected order controls the host step labels, titles, count, Previous/Next, keyboard navigation, Play/Replay, and `whiteboard.next()` / `prev()`; changing it stops current playback and clears its hold timer. Changing the sequence preserves the current frame when it remains in the new path; otherwise it lands instantly on the new path's first frame. `whiteboard.frames` contains the active ordered path and its `index` values, and `whiteboard.frame.index` is the current active-path position; keys remain the stable identity. `goto(key)` accepts only a frame in the active sequence and is a direct jump, while adjacent forward steps still play the destination frame's motion even when declaration indexes move backward. Call `setSequence` before `goto` when a control switches branches:
252
+ For alternate paths, declare `scenarios` on the component rather than drawing your own buttons in the stage: the reader gets a labelled picker that works the same on every whiteboard.
304
253
 
305
- ```js
306
- const delivered = ["push", "gossip", "replicate", "serve"];
307
- const dropped = ["push", "gossip-dropped", "catch-up", "serve-recovered"];
308
-
309
- function selectPath(drop) {
310
- const path = drop ? dropped : delivered;
311
- whiteboard.setSequence(path);
312
- whiteboard.goto(path[1]);
313
- }
254
+ ```json
255
+ "scenarios": [
256
+ { "key": "delivered", "label": "Delivered", "frames": ["push", "gossip", "replicate", "serve"] },
257
+ { "key": "dropped", "label": "Dropped packet", "frames": ["push", "gossip-dropped", "catch-up", "serve-recovered"] }
258
+ ]
314
259
  ```
315
260
 
261
+ Picking a scenario selects its frames as the active path. The active path controls the host step labels, titles, count, Previous/Next, keyboard navigation, Play/Replay, and `whiteboard.next()` / `prev()`; changing it stops current playback and clears its hold timer. It preserves the current frame when that frame is in the new path; otherwise it lands instantly on the new path's first frame. `whiteboard.frames` contains the active ordered path and its `index` values, and `whiteboard.frame.index` is the current active-path position; keys remain the stable identity. `goto(key)` accepts only a frame in the active path and is a direct jump, while adjacent forward steps still play the destination frame's motion even when declaration indexes move backward.
262
+
263
+ `whiteboard.setSequence(keys)` selects a path from a script, for a branch the drawing itself decides. Every key must be a unique declared frame, and repeating the same sequence is a no-op, so it is safe to call from a render path. When the path matches a scenario, the picker shows that scenario.
264
+
316
265
  - `scene.peek(name, ...)`, `whiteboard.code(name)` and `<div data-wb-code="name">` all draw the real code peek over a placeholder. Give `scene.peek` a cell, and span columns (the cell's `colSpan`) when the code needs width — a one-column peek clips long lines; a raw `data-wb-code` div takes a CSS width instead. Its height follows the code, up to about 18 lines. A peek is always on top of your drawing, so do not draw or travel over it.
317
266
  - A code peek is about 40px of header plus 18px per line, up to about 400px. Rows of cards take about 90px each. With the default `height: "auto"`, the stage grows to fit them. If you intentionally use a numeric fixed height, leave enough room because overflow clips at that height.
318
267
 
@@ -340,6 +289,7 @@ Custom CSS should use the whiteboard's variables, never literal colors, sizes or
340
289
  - Each frame shows one idea; its title says what changed. 3 to 8 frames is usual.
341
290
  - Omit `height` unless the animation intentionally needs a fixed viewport; verify any numeric height in every frame and narrow layout.
342
291
  - Every frame reads correctly when reached by a jump, not only by playing.
343
- - Build as "Choose how to build it" says: a scene by default, Mermaid for a larger or branching diagram, and the toolkit or raw HTML for anything else.
292
+ - Alternate paths are `scenarios` on the component, not buttons drawn in the stage.
293
+ - Build as "Choose how to build it" says: a scene by default, and the toolkit or raw HTML for anything else.
344
294
  - In raw HTML, build from the style kit and the `--wb-*` variables; write no literal color, size or font name.
345
295
  - Script errors show under the stage. After writing, read the whiteboard back and fix any.
@@ -17,7 +17,7 @@ Keep plans and their implementation reviews together, and group reviews of an ac
17
17
  **flow**
18
18
  For each board, follow these first five steps in order, with no tool calls beyond what they need: loading the tools they use (`session_create`, `session_activity_begin`, `session_edit`, `session_get`, and later `session_activity_update` and `session_activity_end`) and, for a PR, reading its description (`gh pr view`).
19
19
 
20
- - create the whiteboard with a `target` naming the checkout by its `repositoryPath`: `{kind:"commits", head, base?}` for commits, `{kind:"pullRequest", pullRequest}` for a PR by URL or number, or `{kind:"project"}` for a plan with no change yet. if they name none, use a `worktree` target with no `base`: it reviews the checkout, uncommitted work included, against the default branch. for uncommitted work only, pass `base: "HEAD"`. untracked files are left out: run `git add -N <file>` on new files you want reviewed
20
+ - create the whiteboard with a `target` naming the checkout by its `repositoryPath`. prefer `{kind:"worktree", base?}` for a change in a checkout you have: it follows that checkout, uncommitted work included, against `base` (default branch; the branch below for a stacked branch; `"HEAD"` for uncommitted work only) and creates no checkout. `{kind:"commits", head, base?}` is for fixed commits with no checkout, such as lower stack layers; `{kind:"pullRequest", pullRequest}` for a PR by URL or number; `{kind:"project"}` for a plan with no change yet. create the board before its worktree: start as `project`, then `session_set_target` once the worktree exists. untracked files are left out: `git add -N <file>` to include them
21
21
  - for a change board only, trigger a subagent with this exact instruction: "Call `session_get_instructions({topic:\"file-lenses\"})` and follow it for whiteboard <sessionId>, whose change is `<base>..<head>` in `<repositoryPath>`."
22
22
  - call `session_activity_begin` and pass its `activityId` on every `session_edit`
23
23
  - for a project-target plan or overview, read the relevant source or the stack's combined diff; no diff is expected on the project target itself. For a change board, read the diff with git (or jj) in `repositoryPath`, at the commits `session_create` returned: `git diff <base> <head>`, or for a worktree target `git diff <base>` plus `git status` for untracked files. if it shows no changes, the target is wrong: fix it with `session_set_target` before writing. for a PR, retarget with `{kind:"pullRequest", pullRequest}`, never its branch names: those pin the branch tips, not the PR's merge base, and widen the diff
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dev.fast/whiteboard",
3
- "version": "0.4.1-preview.20261027.141",
3
+ "version": "0.4.1-preview.20261028.142",
4
4
  "private": false,
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -75,11 +75,11 @@
75
75
  "tsx": "4.21.0",
76
76
  "typescript": "6.0.3",
77
77
  "vitest": "4.1.11",
78
+ "@dev.fast/json": "0.0.0",
78
79
  "@dev.fast/review-protocol": "0.0.0",
79
80
  "@dev.fast/review-share-protocol": "0.3.0",
80
- "@dev.fast/trace-core": "0.0.0",
81
- "@dev.fast/json": "0.0.0",
82
- "@dev.fast/trace-protocol": "0.5.0"
81
+ "@dev.fast/trace-protocol": "0.5.0",
82
+ "@dev.fast/trace-core": "0.0.0"
83
83
  },
84
84
  "engines": {
85
85
  "node": ">=24 <25"
@@ -89,7 +89,7 @@
89
89
  "repo": "devdotfast/review",
90
90
  "docs": "packages/review/instructions/authoring.md"
91
91
  },
92
- "gitHead": "27c5ce9a6af4a118a675105249b81e9a930e0ed3",
92
+ "gitHead": "bedb61d18982132726ec118b55337804e8992238",
93
93
  "scripts": {
94
94
  "prebuild": "pnpm run build:workspace-deps",
95
95
  "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",
@@ -268,10 +268,10 @@ HTTP requests and restart. Existing desktop-server tests remain unchanged.
268
268
 
269
269
  ### Language information and committed source
270
270
 
271
- Committed reviews use Review-owned worktrees at their base/head commits for
271
+ Committed reviews use a Review-owned worktree at their head commit for
272
272
  language services. The displayed source remains the immutable Git source.
273
- Existing matching managed checkouts are reused; an equal base/head shares one
274
- checkout. Opening a review prepares its current sides in the background; older
273
+ Existing matching managed checkouts are reused. Opening a review prepares its
274
+ current head in the background; older
275
275
  versions and selected commits acquire environments on demand.
276
276
 
277
277
  Configure preparation through the repository's existing Git configuration:
@@ -285,8 +285,8 @@ Commands run in order inside each managed checkout, never in the invoking user
285
285
  checkout. Successful preparation is cached by checkout and command-list hash;
286
286
  changed commands or recreated checkouts invalidate it. Preparation has no canvas
287
287
  disclosure. `review_open`, and `review_create` when it opens the review, starts acquisition in the background and returns any
288
- already-recorded acquisition issues. `review_environment` rechecks current base/head
289
- checkouts; `retry:true` explicitly reruns failed preparation. Missing setup, pending preparation,
288
+ already-recorded acquisition issues. `review_environment` rechecks the current head
289
+ checkout; `retry:true` explicitly reruns failed preparation. Missing setup, pending preparation,
290
290
  and failed commands with a usable checkout do not produce issues. These checks
291
291
  report acquisition failures (including transient errors), not end-to-end LSP health.
292
292
  `review_workspace_cleanup` lists failed cleanup of retired checkouts and accepts
@@ -85,15 +85,10 @@ const THREAD_PROJECT_SQL =
85
85
  const THREAD_COLUMNS = `ask_conversations.*, ${THREAD_PROJECT_SQL} AS project_id`;
86
86
 
87
87
  /** Saved Ask conversations by project, each anchored on the board it started
88
- * on. No foreign key on the anchor: shared reviews are not in `reviews`.
89
- * So deleting a board removes its threads by hand (removeReview). */
88
+ * on. Deleting a board removes its threads by hand (removeReview). */
90
89
  export class AskHistory {
91
90
  private readonly listeners = new Set<() => void>();
92
91
 
93
- private externalWriteGuard?: (reviewId: string) => void;
94
- setExternalWriteGuard(guard: (reviewId: string) => void) {
95
- this.externalWriteGuard = guard;
96
- }
97
92
  constructor(
98
93
  private readonly db: DatabaseSync,
99
94
  /** The store's rule for writing about a board: one in Trash is
@@ -147,18 +142,13 @@ export class AskHistory {
147
142
  for (const listener of this.listeners) listener();
148
143
  }
149
144
 
150
- private assertWritable(reviewId: string) {
151
- if (reviewId.startsWith("shared-")) this.externalWriteGuard?.(reviewId);
152
- else this.writable(reviewId);
153
- }
154
-
155
145
  private assertThreadWritable(id: string) {
156
146
  const record = this.get(id);
157
147
 
158
- if (record) this.assertWritable(record.anchor.board);
148
+ if (record) this.writable(record.anchor.board);
159
149
  }
160
150
  save(record: AskRecord) {
161
- this.assertWritable(record.anchor.board);
151
+ this.writable(record.anchor.board);
162
152
  this.db
163
153
  .prepare(
164
154
  // Its columns, not the row: when it was last seen, and what the
@@ -186,14 +186,14 @@ export function authoringTools(
186
186
  ),
187
187
  tool(
188
188
  "open",
189
- "Show an active review immediately; restore it from Trash before opening it. Prepare current pinned checkouts in the background. Returns softwareMapEnabled and any already-recorded environmentIssues. Missing optional setup is not an issue; use review_environment to recheck.",
189
+ "Show an active review immediately; restore it from Trash before opening it. Prepare its pinned checkout in the background. Returns softwareMapEnabled and any already-recorded environmentIssues. Missing optional setup is not an issue; use review_environment to recheck.",
190
190
  z.strictObject(review),
191
191
  "POST",
192
192
  "/:reviewId/open",
193
193
  ),
194
194
  tool(
195
195
  "environment",
196
- "Acquire and recheck this review's current base/head language checkouts (not historical or selected commits). Returns acquisition issues, not full LSP health. Missing optional setup and failed setup with a usable checkout stay silent. Set retry:true to rerun failed preparation after an actual language-feature failure; preparation runs in the background.",
196
+ "Acquire and recheck this review's current head language checkout (not historical or selected commits). Returns acquisition issues, not full LSP health. Missing optional setup and failed setup with a usable checkout stay silent. Set retry:true to rerun failed preparation after an actual language-feature failure; preparation runs in the background.",
197
197
  z.strictObject({ ...review, retry: z.boolean().optional() }),
198
198
  "POST",
199
199
  "/:reviewId/environment",
@@ -45,6 +45,24 @@ export const animationFrameSchema = z.strictObject({
45
45
 
46
46
  export type AnimationFrame = z.infer<typeof animationFrameSchema>;
47
47
 
48
+ export const animationScenarioSchema = z.strictObject({
49
+ key: handle.describe("Names the scenario."),
50
+ label: z
51
+ .string()
52
+ .min(1)
53
+ .max(32)
54
+ .describe(
55
+ "What the reader picks above the stage, e.g. Retried request. Keep it short.",
56
+ ),
57
+ frames: z
58
+ .array(handle)
59
+ .min(1)
60
+ .max(60)
61
+ .describe("The frame keys this scenario plays, in order."),
62
+ });
63
+
64
+ export type AnimationScenario = z.infer<typeof animationScenarioSchema>;
65
+
48
66
  export const animationSchema = defineBlock("animation", {
49
67
  title: label,
50
68
  html: text
@@ -60,6 +78,14 @@ export const animationSchema = defineBlock("animation", {
60
78
  .describe(
61
79
  "Every possible frame. Stage scripts may select an ordered branch with whiteboard.setSequence(keys); keys stay unique and stable.",
62
80
  ),
81
+ scenarios: z
82
+ .array(animationScenarioSchema)
83
+ .min(2)
84
+ .max(8)
85
+ .optional()
86
+ .describe(
87
+ "Alternate paths through the frames. The whiteboard draws a labelled scenario picker above the stage and starts on the first one.",
88
+ ),
63
89
  code: z
64
90
  .record(handle, anchorSchema)
65
91
  .default({})
@@ -94,5 +120,29 @@ export const animation = {
94
120
  throw new ReviewInputError(
95
121
  "Give every animation frame a label, or none: the step strip needs one per frame.",
96
122
  );
123
+
124
+ const scenarios = block.scenarios ?? [];
125
+
126
+ if (
127
+ new Set(scenarios.map((scenario) => scenario.key)).size !==
128
+ scenarios.length
129
+ )
130
+ throw new ReviewInputError(
131
+ "Animation scenario keys must be unique within the animation.",
132
+ );
133
+
134
+ for (const scenario of scenarios) {
135
+ if (new Set(scenario.frames).size !== scenario.frames.length)
136
+ throw new ReviewInputError(
137
+ `Scenario "${scenario.key}" lists a frame twice.`,
138
+ );
139
+
140
+ const unknown = scenario.frames.find((key) => !keys.has(key));
141
+
142
+ if (unknown)
143
+ throw new ReviewInputError(
144
+ `Scenario "${scenario.key}" names frame "${unknown}", which the animation does not declare.`,
145
+ );
146
+ }
97
147
  },
98
148
  } satisfies BlockDefinition<AnimationBlock>;