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

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));
 

package/src/review-preferences.ts

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { isJsonObject, parseJsonText } from "@dev.fast/review-protocol";
+import { writePrivateJsonAtomic } from "@dev.fast/trace-core";
+
+import { devReviewHome } from "./review-home-paths";
+
+/**
+ * Machine-wide Review preferences the server itself needs. Workbench settings
+ * do not work here: the review server never reads the workbench
+ * configuration.
+ */
+function reviewPreferencesPath(devHome = devReviewHome()): string {
+  return path.join(devHome, "preferences.json");
+}
+
+/** Whether agents are offered animation authoring; existing animations
+ * always render. A missing or unreadable file means off; it never throws. */
+export async function readAnimationsEnabled(
+  devHome?: string,
+): Promise<boolean> {
+  try {
+    const raw = parseJsonText(
+      await readFile(reviewPreferencesPath(devHome), "utf8"),
+    );
+
+    return isJsonObject(raw) && raw.animationsEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeAnimationsEnabled(
+  enabled: boolean,
+  devHome?: string,
+): Promise<boolean> {
+  await writePrivateJsonAtomic(reviewPreferencesPath(devHome), {
+    animationsEnabled: enabled,
+  });
+
+  return enabled;
+}

package/src/server/desktop-server.ts

@@ -46,6 +46,10 @@ import {
   reviewInstanceDiscoveryPath,
   reviewLegacyDiscoveryPath,
 } from "@review/review-home-paths";
+import {
+  readAnimationsEnabled,
+  writeAnimationsEnabled,
+} from "@review/review-preferences";
 import {
   ReviewTelemetry,
   type ReviewTelemetryContext,
@@ -173,6 +177,10 @@ export function createGlobalReviewServer(
   let closing = false;
   const cliPath = path.join(input.packageRoot, "dist", "cli.js");
 
+  // The animations preference, read once at listen and kept current by the
+  // settings endpoint below: this server is the only writer while it runs.
+  let animationsEnabled = false;
+
   const discovery: ReviewDesktopDiscovery = {
     version: REVIEW_DESKTOP_DISCOVERY_VERSION,
     instanceId,
@@ -205,6 +213,7 @@ export function createGlobalReviewServer(
     relay,
     token,
     instanceId,
+    animations: () => animationsEnabled,
     status: () => {
       const { key, channel, checkout, appVersion, cliVersion, instanceId } =
         discovery;
@@ -257,6 +266,20 @@ export function createGlobalReviewServer(
   app.all("/reviews-api", (context) => gateway.fetch(context.req.raw));
   app.all("/reviews-api/*", (context) => gateway.fetch(context.req.raw));
   app.get("/remote-hosts", () => serverJson(200, gateway.hosts()));
+  app.get("/preferences/animations", () =>
+    serverJson(200, { enabled: animationsEnabled }),
+  );
+  app.put("/preferences/animations", async (context) => {
+    const request = z
+      .object({ enabled: z.boolean() })
+      .safeParse(await readBoundedRequestJson(context.req.raw));
+
+    if (!request.success)
+      throw new ReviewServerError("enabled must be a boolean.", 400);
+    animationsEnabled = await writeAnimationsEnabled(request.data.enabled);
+
+    return serverJson(200, { enabled: animationsEnabled });
+  });
   app.post("/app/focus", async () => {
     const result = await relay.dispatch({
       name: "focusWindow",
@@ -499,6 +522,7 @@ export function createGlobalReviewServer(
     },
     listen: async () => {
       await migrateDiffrConfig();
+      animationsEnabled = await readAnimationsEnabled();
       boundPort = await listen(loopback.server, input.port);
       discovery.url = urlForBoundPort();
 

package/src/server/review-server-core.ts

@@ -132,6 +132,7 @@ export interface WhiteboardCoreInput {
   token: string;
   instanceId: string;
   softwareMapEnabled?: boolean;
+  animations?: () => boolean;
   status: () => JsonObject;
   hooks?: ReviewApiHooks;
   ask?: {
@@ -198,6 +199,7 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
       threads: askThreads,
       agents: async () => detectAskAgents(await ask?.env),
     },
+    input.animations,
   );
 
   // A shared store mounts the publisher with the rest of sharing.

package/src/server/structural-comparisons.ts

@@ -42,19 +42,16 @@ export class StructuralComparisons {
     } finally {
       entry.readers--;
 
-      if (
-        (!entry.done && !entry.initialReady && !entry.readers) ||
-        entry.error ||
-        entry.failed
-      ) {
+      // Summaries arrive after the files, so a run nobody reads stops. Full
+      // comparisons keep coverage as a reader until diffr completes.
+      if ((!entry.done && !entry.readers) || entry.error || entry.failed) {
         entry.abort.abort();
         this.entries.delete(key);
       }
-      // Keep the most recently read idle comparisons, including background enrichment.
-      // Coverage can finish before an editor subscribes; it must not cancel summaries.
 
+      // Keep the most recently read finished comparisons.
       const idle = [...this.entries].filter(
-        ([, value]) => (value.done || value.initialReady) && !value.readers,
+        ([, value]) => value.done && !value.readers,
       );
 
       for (const [oldKey, old] of idle.slice(0, -IDLE_COMPARISONS)) {
@@ -124,7 +121,6 @@ class Comparison {
   done = false;
   error: unknown;
   failed = false;
-  initialReady = false;
   private remaining: Set<string> | undefined;
   private readonly listeners = new Set<() => void>();
 
@@ -144,13 +140,11 @@ class Comparison {
               (entry) => (entry.file.rhs ?? entry.file.lhs)!.path,
             ),
           );
-          this.initialReady = this.remaining.size === 0;
         } else if (event.type === "file") {
           const path = (event.file.rhs ?? event.file.lhs)!.path;
 
           if (!this.remaining?.delete(path))
             throw new Error(`Unexpected structural result: ${path}`);
-          this.initialReady = this.remaining.size === 0;
         }
 
         if (event.type === "complete")

package/src/server/structural-diff.ts

@@ -61,7 +61,7 @@ export async function* structuralDiff(
       args.push(`${comparison.base}...${comparison.head}`);
   }
 
-  args.push("--", ...(input.paths ?? []));
+  args.push("--defer", "--", ...(input.paths ?? []));
 
   // Plugins can exceed two minutes between records. Apply this timeout only
   // until the manifest arrives; plugins enforce their own request timeouts.
@@ -101,6 +101,7 @@ export async function* structuralDiff(
   let completed = false;
   let aborted: StructuralProblem | undefined;
   let failed = 0;
+  const sent = new Set<string>();
   const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
 
   try {
@@ -131,7 +132,12 @@ export async function* structuralDiff(
 
         failed = event.failed;
         aborted = event.aborted;
-      } else if (event.type !== "file") {
+      } else if (event.type === "file") {
+        sent.add((event.file.rhs ?? event.file.lhs)!.path);
+      } else if (
+        event.type !== "update" ||
+        !sent.has((event.file.rhs ?? event.file.lhs)!.path)
+      ) {
         throw new Error(`Unexpected diffr event: ${event.type}`);
       }
 

package/src/ui-telemetry-events.ts

@@ -621,6 +621,15 @@ export const UI_TELEMETRY_EVENTS = {
     event: "review_diff_failed",
     properties: { reason: DIFF_FAILED_REASON, files: "number" },
   },
+  diff_loaded: {
+    event: "review_diff_loaded",
+    properties: {
+      first_file_ms: "number",
+      updates_ms: "number",
+      files: "number",
+      update_errors: "number",
+    },
+  },
   discord_clicked: {
     event: "review_discord_clicked",
     properties: { via: DISCORD_VIA },

package/dist/agent-cli-Cn4-16XA.js

@@ -1,2 +0,0 @@
-import { n as runReviewAgentCli } from "./agent-cli-CHNDd4Ga.js";
-export { runReviewAgentCli };

package/dist/profile-BopGMZUh.js

@@ -1,2 +0,0 @@
-import { t as openReviewProfile } from "./profile-D9wdlPgw.js";
-export { openReviewProfile };