@dev.fast/whiteboard 0.4.0 → 0.4.1-preview.20261026.138

package/src/review-api/comparison-coverage.ts

@@ -4,6 +4,7 @@ import {
   type StructuralDiff,
   type StructuralRegion,
   type StructuralSource,
+  applyStructuralUpdate,
   structuralRows,
 } from "@dev.fast/review-protocol";
 import type { AlignmentRow } from "@review/lens-selection.js";
@@ -158,101 +159,131 @@ export async function comparisonCoverage(
     coverage.files.map((file, index) => [file.path, index]),
   );
 
-  const remaining = new Set<string>();
-
-  for await (const event of data.structuralChanges({
-    reviewId,
-    pins,
-    signal,
-  })) {
-    if (event.type === "start") {
-      for (const entry of event.files)
-        remaining.add((entry.file.rhs ?? entry.file.lhs)!.path);
-
-      if (!remaining.size) break;
-      continue;
-    }
-
-    if (event.type === "complete" && (event.failed || event.aborted))
-      throw new Error(
-        event.aborted?.message ?? "Structural coverage is incomplete.",
-      );
-
-    if (event.type !== "file") continue;
-
-    const path = (event.file.rhs ?? event.file.lhs)!.path;
-
-    if (!remaining.delete(path))
-      throw new Error(`Unexpected structural result: ${path}`);
-
-    const baseIndex = event.file.lhs && baseFiles.get(event.file.lhs.path);
-    const headIndex = event.file.rhs && headFiles.get(event.file.rhs.path);
-
-    if (event.error) {
-      if (
-        event.error.code !== "unsupported_file_type" &&
-        event.error.code !== "not_utf8"
-      )
-        throw new Error(`Cannot count ${path}: ${event.error.message}`);
-
-      for (const index of [baseIndex, headIndex])
-        if (index !== undefined) unsupported.add(coverage.files[index].path);
-    } else if (event.diff.type === "text") {
-      const diff = event.diff;
-      const folded = foldedChanges(diff);
-
-      // Match each side separately: diffr can split a Git rename into two files.
-      for (const side of ["base", "head"] as const) {
-        const source = side === "base" ? event.file.lhs : event.file.rhs;
-
-        const index =
-          source && (side === "base" ? baseFiles : headFiles).get(source.path);
-
-        if (index === undefined) continue;
-        const file = coverage.files[index];
-
-        const visible = subtractIntervals(
-          diff.structural_changes[side],
-          folded[side],
-        );
-
-        coverage.files[index] = {
-          ...file,
-          folded: {
-            ...(file.folded ?? emptyCoverage()),
-            [side]: subtractIntervals(file.changed[side], visible),
-          },
-        };
-      }
-
-      const index = headIndex ?? baseIndex;
+  return new Promise((resolve, reject) => {
+    let resolved = false;
 
-      if (index !== undefined) {
-        const sources =
-          coverage.fileSources.get(coverage.files[index].path) ?? [];
+    const counted = () => {
+      resolved = true;
+      resolve(current());
+    };
 
-        if (
-          sources.every(
-            (source) =>
-              source.file ===
-              (source.side === "base" ? event.file.lhs : event.file.rhs)?.path,
+    // Deferred updates keep refining `folded` after the counts resolve.
+    void (async () => {
+      const remaining = new Set<string>();
+
+      const diffs = new Map<
+        string,
+        Extract<StructuralDiff, { type: "text" }>
+      >();
+
+      for await (const event of data.structuralChanges({
+        reviewId,
+        pins,
+        signal,
+      })) {
+        if (event.type === "start") {
+          for (const entry of event.files)
+            remaining.add((entry.file.rhs ?? entry.file.lhs)!.path);
+
+          if (!remaining.size) break;
+          continue;
+        }
+
+        if (event.type === "complete" && event.aborted)
+          throw new Error(event.aborted.message);
+
+        if (event.type !== "file" && event.type !== "update") continue;
+
+        const path = (event.file.rhs ?? event.file.lhs)!.path;
+        const baseIndex = event.file.lhs && baseFiles.get(event.file.lhs.path);
+        const headIndex = event.file.rhs && headFiles.get(event.file.rhs.path);
+        let diff: StructuralDiff | undefined;
+
+        if (event.type === "update") {
+          const previous = diffs.get(path);
+
+          if (!previous)
+            throw new Error(`Unexpected structural result: ${path}`);
+
+          if (event.error) continue;
+          diff = applyStructuralUpdate(previous, event);
+        } else if (!remaining.delete(path))
+          throw new Error(`Unexpected structural result: ${path}`);
+        else if (event.error) {
+          if (
+            event.error.code !== "unsupported_file_type" &&
+            event.error.code !== "not_utf8"
           )
-        )
-          coverage.alignments = new Map(coverage.alignments).set(
-            coverage.files[index].path,
-            structuralRows(diff),
-          );
+            throw new Error(`Cannot count ${path}: ${event.error.message}`);
+
+          for (const index of [baseIndex, headIndex])
+            if (index !== undefined)
+              unsupported.add(coverage.files[index].path);
+        } else diff = event.diff;
+
+        if (diff?.type === "text") {
+          diffs.set(path, diff);
+          const folded = foldedChanges(diff);
+
+          // Match each side separately: diffr can split a Git rename into two files.
+          for (const side of ["base", "head"] as const) {
+            const source = side === "base" ? event.file.lhs : event.file.rhs;
+
+            const index =
+              source &&
+              (side === "base" ? baseFiles : headFiles).get(source.path);
+
+            if (index === undefined) continue;
+            const file = coverage.files[index];
+
+            const visible = subtractIntervals(
+              diff.structural_changes[side],
+              folded[side],
+            );
+
+            coverage.files[index] = {
+              ...file,
+              folded: {
+                ...(file.folded ?? emptyCoverage()),
+                [side]: subtractIntervals(file.changed[side], visible),
+              },
+            };
+          }
+
+          const index = headIndex ?? baseIndex;
+
+          if (event.type === "file" && index !== undefined) {
+            const sources =
+              coverage.fileSources.get(coverage.files[index].path) ?? [];
+
+            if (
+              sources.every(
+                (source) =>
+                  source.file ===
+                  (source.side === "base" ? event.file.lhs : event.file.rhs)
+                    ?.path,
+              )
+            )
+              coverage.alignments = new Map(coverage.alignments).set(
+                coverage.files[index].path,
+                structuralRows(diff),
+              );
+          }
+        }
+
+        publish?.(current());
+
+        if (!remaining.size && !resolved) counted();
       }
-    }
-
-    publish?.(current());
 
-    if (!remaining.size) break;
-  }
-
-  if (remaining.size) throw new Error("Structural coverage is incomplete.");
+      if (remaining.size) throw new Error("Structural coverage is incomplete.");
 
-  return current();
+      if (!resolved) counted();
+    })().catch((error) => {
+      if (resolved) console.warn("Could not refine folded coverage:", error);
+      else reject(error);
+    });
+  });
 }
 
 /**

package/src/review-api/component-reference.ts

@@ -1,3 +1,9 @@
+/** The animation component, shown only while Animations are on. */
+const ANIMATION = [
+  '- animation {title, html, frames: {key, title, label?, caption?, duration? (ms)}[] (1 to 60), code?: {name: anchor}, height?: "auto" (default) | number (120 to 1200 CSS px), pins?}; declare every possible frame',
+  'Use an animation for change over time that a static diagram cannot show: state before and after, a cache filling, data changing as a request crosses layers. It can sit in design beside the diagram, or replace it when the motion is the point. If nothing changes between frames, use a sequence or flow_diagram instead: their steps and nodes link to code. Read session_get_instructions({topic:"animation"}) before writing one.',
+];
+
 /** Every component's fields, for session_get_instructions: the edit tool's
  * description must stay short enough that clients don't cut it off. */
 export const COMPONENT_REFERENCE = [
@@ -26,6 +32,16 @@ export const COMPONENT_REFERENCE = [
   "- store {label, storage: relational|document, collections: {key: {label, fields: {key: field}, source?: anchor of its schema declaration}}, dataStoreKind?: database|objectStore|bucket|artifactStore|fileStore}",
   "- field {label, dataType, nullable?, primaryKey?, references?: {store, collection, field}, fields?: {key: field}}",
   "- useCase {label, summary?, operations: operation[] (1 or more)}; operation {kind: read|write, actor, store, collection, label, source: anchor, field?, detail?, pins?}, naming declared keys",
+  ...ANIMATION,
   "",
   'Example (replace its path and lines with verified ones): {"type":"sequence","title":"Request","actors":{"a":"Client","b":"Server"},"steps":[{"from":"a","to":"b","label":"Send","source":"head/src/app.ts#L10-L20"}]}',
 ].join("\n");
+
+/** Keep disabled experimental components out of agent guidance. */
+export function componentReference(animationsEnabled: boolean): string {
+  return animationsEnabled
+    ? COMPONENT_REFERENCE
+    : COMPONENT_REFERENCE.split("\n")
+        .filter((line) => !ANIMATION.includes(line))
+        .join("\n");
+}

package/src/review-api/document-text.ts

@@ -196,6 +196,17 @@ export function documentText(
             `[${edge.id}] ${edge.from} → ${edge.to}${edge.label ? `: ${edge.label}` : ""}`,
           );
         break;
+      case "animation":
+        for (const [index, frame] of element.frames.entries())
+          detail(
+            `Frame ${index + 1} [${frame.key}]: ${frame.title}${frame.caption ? ` — ${frame.caption}` : ""}`,
+          );
+
+        for (const [name, anchor] of Object.entries(element.code))
+          detail(`Code ${name}: ${anchor}`);
+
+        if (detailed) code(depth + 1, { language: "html", text: element.html });
+        break;
       case "software_map":
         detail(
           `Map: ${element.mapVersionId}${element.focusElementId ? `, focus: ${element.focusElementId}` : ""}`,

package/src/review-api/document.ts

@@ -198,6 +198,11 @@ const unitTypes = new Set(["step", "flow_node", "flow_edge"]);
 export const isUnit = (element: Element): element is Unit =>
   unitTypes.has(element.type);
 
+/** The reference id of a code peek an animation names: the canvas finds the
+ * peek's resolved anchor by it. */
+export const animationCodeId = (blockId: string, name: string) =>
+  `${blockId}:code:${name}`;
+
 /** Rewrites old review-source: and review-trace: links to their whiteboard: form. */
 export function canonicalLink(href: string): string {
   return href.replace(
@@ -523,6 +528,16 @@ function documentReferences(
         ),
       );
 
+    if (element.type === "animation")
+      return Object.entries(element.code).flatMap(([name, anchor]) =>
+        select(anchor, element.pins).map((source) => ({
+          id: animationCodeId(element.id!, name),
+          source,
+          label: name,
+          peek: true,
+        })),
+      );
+
     if (element.type === "call_stack_diff")
       return [...element.base, ...element.head].flatMap((frame) => {
         const pins = frame.pins ?? element.pins;
@@ -774,11 +789,17 @@ const namedByType = (types: string[]) =>
 
 /** What agents are shown: content names only its type. The host parses
  * editSchema, reporting the named kind's issues. */
-export const publishedEditSchema = edits(
-  namedByType([...writableBlockTypes, "step", "flow_node", "flow_edge"]),
-  namedByType(writableBlockTypes),
-  z.unknown(),
-);
+export function publishedEdits(animationsEnabled = true) {
+  const types = writableBlockTypes.filter(
+    (type) => animationsEnabled || type !== "animation",
+  );
+
+  return edits(
+    namedByType([...types, "step", "flow_node", "flow_edge"]),
+    namedByType(types),
+    z.unknown(),
+  );
+}
 
 /**
  * What one saved version did, for a canvas drawing the document as the

package/src/review-api/http.ts

@@ -70,6 +70,7 @@ import {
   type ReviewTarget,
   boardLinks,
   boardRepositoryId,
+  elements,
 } from "./document.js";
 import { instructionsQuerySchema, renderInstructions } from "./instructions.js";
 import type { LocalReviewData } from "./local-data.js";
@@ -206,6 +207,7 @@ export function createReviewApi(
   hooks: ReviewApiHooks = {},
   /** Desktop's Ask: local agents answering questions about a selection. */
   ask?: AskHost,
+  animationsEnabled: () => boolean = () => false,
 ) {
   const app = new Hono();
   app.onError((error, context) => {
@@ -372,12 +374,15 @@ export function createReviewApi(
   // renderer block tool listing and the first instructions call.
   const instructionContext = async () => ({
     traceEnabled: await traceEnabled(),
+    animationsEnabled: animationsEnabled(),
   });
 
   app.get("/authoring", async (context) => {
     const instructions = await instructionContext();
 
-    return context.json(authoringTools(instructions.traceEnabled));
+    return context.json(
+      authoringTools(instructions.traceEnabled, instructions.animationsEnabled),
+    );
   });
   app.get("/instructions", async (context) => {
     const { topic } = instructionsQuerySchema.parse(context.req.query());
@@ -508,7 +513,10 @@ export function createReviewApi(
   );
 
   app.get("/capabilities", async (context) =>
-    context.json(await capabilities()),
+    context.json({
+      ...(await capabilities()),
+      animationsEnabled: animationsEnabled(),
+    }),
   );
 
   app.get("/:id/activity", (context) => {
@@ -2259,6 +2267,27 @@ export function createReviewApi(
 
     const input = commandSchema.parse(request);
 
+    if (!animationsEnabled() && input.operation.type === "edit") {
+      const { edit, reviewId } = input.operation;
+      const incoming = "content" in edit ? elements([edit.content]) : [];
+
+      const target =
+        "targetId" in edit
+          ? elements(readReview(reviewId).document).find(
+              (element) => element.id === edit.targetId,
+            )
+          : undefined;
+
+      if (
+        incoming.some((element) => element.type === "animation") ||
+        target?.type === "animation"
+      )
+        throw new ReviewInputError(
+          "Animation authoring is disabled. Enable Animations in Settings under Experimental Features to edit animations. Existing animations can still be viewed.",
+          409,
+        );
+    }
+
     const command = sharedCommandSchema.safeParse(input);
 
     if (

package/src/review-api/instructions.ts

@@ -4,10 +4,12 @@ import path from "node:path";
 import { findReviewPackageRoot } from "@review/package-paths.js";
 import { z } from "zod";
 
-import { COMPONENT_REFERENCE } from "./component-reference.js";
+import { componentReference } from "./component-reference.js";
+import { ReviewInputError } from "./input-error.js";
 
 export const INSTRUCTION_TOPICS = [
   "authoring",
+  "animation",
   "file-lenses",
   "trace-archaeology",
 ] as const;
@@ -20,6 +22,7 @@ export const instructionsQuerySchema = z.strictObject({
 
 export interface InstructionContext {
   traceEnabled: boolean;
+  animationsEnabled?: boolean;
 }
 
 const cache = new Map<string, Promise<string>>();
@@ -44,6 +47,12 @@ export async function renderInstructions(
   context: InstructionContext,
   root = findReviewPackageRoot(import.meta.url),
 ): Promise<string> {
+  if (topic === "animation" && !context.animationsEnabled)
+    throw new ReviewInputError(
+      "Animation authoring is disabled. Enable Animations in Settings under Experimental Features.",
+      409,
+    );
+
   if (topic === "trace-archaeology" && !context.traceEnabled)
     return "Trace capture is off on this machine, so no agent traces are available. It can be turned on in Whiteboard Desktop Settings under Experimental Features.";
 
@@ -59,7 +68,7 @@ export async function renderInstructions(
 
   return [
     await read(root, "authoring"),
-    COMPONENT_REFERENCE,
+    componentReference(context.animationsEnabled === true),
     ...(context.traceEnabled
       ? [
           '## Traces\n\nAt the end, run `whiteboard trace list --session <sessionId> --json`, which covers every commit in the review. If it lists no sessions, there are no traces to quote: skip this step. Otherwise read `session_get_instructions({topic:"trace-archaeology"})` and rewrite as much as possible of the what/why, design, and requirements sections in terms of literal trace quotes from the user.',

package/src/review-api/local-data.ts

@@ -1817,6 +1817,8 @@ export class LocalReviewData {
       state: "pending" | "ready" | "error";
       error?: unknown;
       partial?: ComparisonCoverage;
+      abort: AbortController;
+      worktree?: string;
     }
   >();
   private readonly coverageAbort = new AbortController();
@@ -1877,11 +1879,24 @@ export class LocalReviewData {
     let entry = this.coverageCache.get(key);
 
     if (!entry || entry.state === "error") {
+      const worktree = pins.worktreeRevision
+        ? JSON.stringify({ ...pins, worktreeRevision: undefined })
+        : undefined;
+
+      // A newer worktree revision cancels older ones.
+      for (const [cachedKey, cached] of this.coverageCache)
+        if (worktree && cached.worktree === worktree) {
+          cached.abort.abort();
+          this.coverageCache.delete(cachedKey);
+        }
+
+      const abort = new AbortController();
+
       const promise = comparisonCoverage(
         this,
         reviewId,
         pins,
-        this.coverageAbort.signal,
+        AbortSignal.any([this.coverageAbort.signal, abort.signal]),
         (partial) => {
           const current = this.coverageCache.get(key);
 
@@ -1890,7 +1905,7 @@ export class LocalReviewData {
         },
       );
 
-      entry = { promise, state: "pending" };
+      entry = { promise, state: "pending", abort, worktree };
       this.coverageCache.set(key, entry);
       const current = entry;
 
@@ -1910,7 +1925,7 @@ export class LocalReviewData {
 
       void promise.then(
         (value) => {
-          current.partial = value;
+          current.partial ??= value;
 
           if (!this.closed)
             this.store.setDiffStats(pins, {
@@ -1931,7 +1946,9 @@ export class LocalReviewData {
       );
     }
 
-    return entry.promise;
+    return entry.state === "ready" && entry.partial
+      ? Promise.resolve(entry.partial)
+      : entry.promise;
   }
 
   changes(pins: Pins): Promise<LocalVcsDiffFileSummary[]>;

package/src/review-api/mcp.ts

@@ -1,10 +1,11 @@
 import type { Readable, Writable } from "node:stream";
 
-import type { JsonValue } from "@dev.fast/json";
+import { type JsonValue, isJsonObject } from "@dev.fast/json";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  type CallToolResult,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { ReviewToolCall } from "@review/review-telemetry.js";
@@ -13,6 +14,7 @@ import type { ReviewSessionAgent } from "@review/ui-telemetry-events.js";
 import {
   type AuthoringTool,
   type ConnectedReview,
+  ToolText,
   toolResultText,
 } from "./agent-client.js";
 import { authoringTools } from "./authoring-tools.js";
@@ -37,6 +39,7 @@ function mcpAuthoringGuidance(context: { traceEnabled: boolean }): string {
           'For why code exists, what an agent was thinking, or whether an agent solved something before, call session_get_instructions({topic:"trace-archaeology"}).',
         ]
       : []),
+    "For programmatic MCP calls, use structuredContent when present; otherwise parse JSON from the text content when the result is JSON. An insert through session_edit uses edit.content for the actual document component, never the MCP transport wrapper containing content or structuredContent.",
     "Never read or write Whiteboard files or SQL.",
   ].join(" ");
 }
@@ -168,20 +171,20 @@ export async function serveReviewMcp(
         )
           return { content: [{ type: "text" as const, text: RECOVERY }] };
 
-        if (request.params.name === REVIEW_STATUS_TOOL.name && offlineStatus)
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: JSON.stringify(
-                  await offlineStatus(
-                    error instanceof Error ? error.message : String(error),
-                  ),
-                ),
-              },
-            ],
+        if (request.params.name === REVIEW_STATUS_TOOL.name && offlineStatus) {
+          const result = await offlineStatus(
+            error instanceof Error ? error.message : String(error),
+          );
+
+          const response: CallToolResult = {
+            content: [{ type: "text", text: JSON.stringify(result) }],
           };
 
+          if (isJsonObject(result)) response.structuredContent = result;
+
+          return response;
+        }
+
         throw error;
       }
 
@@ -203,7 +206,7 @@ export async function serveReviewMcp(
       const text = toolResultText(tool, result);
       report();
 
-      return {
+      const response: CallToolResult = {
         content: [
           {
             type: "text",
@@ -214,6 +217,11 @@ export async function serveReviewMcp(
           },
         ],
       };
+
+      if (!(result instanceof ToolText) && isJsonObject(result))
+        response.structuredContent = result;
+
+      return response;
     } catch (error) {
       report(toolFailure(error, phase));