@dev.fast/whiteboard 0.5.0 → 0.5.2-preview.20261104.146

package/src/review-api/animation-references.ts

@@ -0,0 +1,92 @@
+// The reference animations shipped in instructions/animations: worked examples
+// an agent copies as a starting point. Each folder is an animation draft plus a
+// README, read by the same code that publishes a draft.
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { ReviewInputError } from "@dev.fast/whiteboard-document";
+import { isMissingFileError } from "@review/fs-utils.js";
+import { findReviewPackageRoot } from "@review/package-paths.js";
+
+import { readAnimationFolder } from "./animation-drafts.js";
+
+export type AnimationReference = {
+  name: string;
+  directory: string;
+  title: string;
+  summary: string;
+};
+
+/** The README's H1 and the paragraph right after it. */
+function readmeHeading(file: string, text: string) {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim());
+  const title = lines[start]?.match(/^# (.+)$/)?.[1]?.trim();
+  const rest = lines.slice(start + 1);
+  const from = rest.findIndex((line) => line.trim());
+  const paragraph = [];
+
+  for (const line of from < 0 ? [] : rest.slice(from)) {
+    if (!line.trim() || line.startsWith("#")) break;
+    paragraph.push(line.trim());
+  }
+
+  const summary = paragraph.join(" ");
+
+  if (!title || !summary)
+    throw new ReviewInputError(
+      `${file} must open with "# Title" followed by a one-sentence summary paragraph.`,
+    );
+
+  return { title, summary };
+}
+
+/** Every reference animation, sorted by name, each checked as a publish would
+ * be. Strict (the default) throws on a broken reference, for the tests that
+ * keep them valid; otherwise a broken one is left out, so an agent's checkout
+ * and instructions never fail on a reference. */
+export async function readAnimationReferences(
+  root = findReviewPackageRoot(import.meta.url),
+  { strict = true } = {},
+): Promise<AnimationReference[]> {
+  const parent = path.join(root, "instructions", "animations");
+  let entries;
+
+  try {
+    entries = await readdir(parent, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingFileError(error)) return [];
+    throw error;
+  }
+
+  const names = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+
+  const references = await Promise.all(
+    names.map(async (name): Promise<AnimationReference | undefined> => {
+      const directory = path.join(parent, name);
+      const readme = path.join(directory, "README.md");
+
+      try {
+        await readAnimationFolder(directory);
+
+        return {
+          name,
+          directory,
+          ...readmeHeading(readme, await readFile(readme, "utf8")),
+        };
+      } catch (error) {
+        if (!strict) return undefined;
+
+        throw new ReviewInputError(
+          `Reference animation ${name}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }),
+  );
+
+  return references.filter((reference) => reference !== undefined);
+}

package/src/review-api/animation-render.ts

@@ -0,0 +1,106 @@
+// An agent's look at an animation it wrote: one frame of it (or a clip at
+// one marker), shown by the attached Desktop as the reader sees it and
+// captured as a PNG. The server checks the stop against the document; the
+// Desktop shows and captures it.
+
+import {
+  type Element,
+  ReviewInputError,
+  elements,
+} from "@dev.fast/whiteboard-document";
+import { z } from "zod";
+
+import type { Snapshot } from "./store.js";
+
+export const renderQuerySchema = z.object({
+  targetId: z.string().min(1),
+  /** A frame key, or a clip's marker key; omitted, the first stop. */
+  frame: z.string().min(1).optional(),
+});
+
+/** What the Desktop answers: the stop it showed, and the figure's PNG. */
+export const renderedFrameSchema = z.object({
+  frame: z.object({
+    key: z.string(),
+    title: z.string(),
+    position: z.number().int().nonnegative(),
+    count: z.number().int().positive(),
+  }),
+  scenario: z.string().optional(),
+  /** The figure ran past the window, so the capture cuts it. */
+  clipped: z.boolean(),
+  /** The error the stage reported, if its script threw. */
+  error: z.string().nullable(),
+  /** The capture, base64. */
+  png: z.string().min(1),
+});
+
+export type RenderedFrame = z.infer<typeof renderedFrameSchema>;
+
+export interface RenderRequest {
+  reviewId: string;
+  targetId: string;
+  frame: string;
+}
+
+/** The host's way to a Desktop that shows the frame and captures it. */
+export type RenderAnimation = (
+  request: RenderRequest,
+) => Promise<RenderedFrame>;
+
+/** The stop a render shows: a frame of an animation, or a marker of a clip. */
+export interface RenderTarget {
+  type: "animation" | "clip";
+  key: string;
+}
+
+type StageBlock = Extract<Element, { type: "animation" | "clip" }>;
+
+const isStageBlock = (element: Element): element is StageBlock =>
+  element.type === "animation" || element.type === "clip";
+
+/** The stop to render: `frame` checked against the block's frames or markers, or
+ * the first stop of the first scenario when omitted. */
+export function renderTarget(
+  snapshot: Snapshot,
+  targetId: string,
+  frame: string | undefined,
+): RenderTarget {
+  const target = elements(snapshot.document).find(
+    (element) => element.id === targetId,
+  );
+
+  if (!target)
+    throw new ReviewInputError("Target not found in this version.", 404);
+
+  if (!isStageBlock(target))
+    throw new ReviewInputError(
+      `${targetId} is a ${target.type}; only an animation or a clip renders a frame.`,
+    );
+
+  const noun = target.type === "clip" ? "marker" : "frame";
+
+  const keys =
+    target.type === "clip"
+      ? target.markers.map((marker) => marker.key)
+      : target.frames.map((item) => item.key);
+
+  if (frame === undefined) {
+    const first =
+      target.type === "animation"
+        ? (target.scenarios?.[0]?.frames[0] ?? keys[0])
+        : keys[0];
+
+    if (first === undefined)
+      throw new ReviewInputError(`${targetId} has no ${noun}s to render.`);
+
+    return { type: target.type, key: first };
+  }
+
+  if (!keys.includes(frame))
+    throw new ReviewInputError(
+      `${frame} is not a ${noun} of ${targetId}. Its ${noun}s: ${keys.join(", ")}.`,
+    );
+
+  return { type: target.type, key: frame };
+}

package/src/review-api/authoring-tools.ts

@@ -52,7 +52,7 @@ export function authoringTools(
       "While a reader may be watching, write small and often: one paragraph per edit. Insert a new diagram whole. Change one already drawn a unit at a time (a flow_node, flow_edge or step, with parentId naming the diagram), and link each added flow_node to a node already drawn.",
       ...(animationsEnabled
         ? [
-            "An animation is edited as files: review_checkout writes it to a folder, you edit the files with your own file tools, and an edit with fromFiles naming that folder publishes it in place of content or changes. Publish the same folder again after each round of edits.",
+            "An animation or clip is edited as files: review_checkout writes it to a folder, you edit the files with your own file tools, and an edit with fromFiles naming that folder publishes it in place of content or changes. Publish the same folder again after each round of edits.",
           ]
         : []),
     ].join("\n"),
@@ -177,11 +177,18 @@ export function authoringTools(
       ? [
           tool(
             "checkout",
-            "Write an animation to a folder of files to edit with your own file tools: animation.html (its html), frames.json (its frames, each with its data), scenarios.json and block.json (title, code, height, pins). Then publish the folder with review_edit, giving fromFiles instead of content or changes. dir defaults to a folder Whiteboard manages; checking out again overwrites it. A publish is refused if the animation changed after the checkout.",
+            "Write an animation or clip to a folder of files to edit with your own file tools: animation.html (its html), frames.json (an animation's frames, each with its data) or markers.json (a clip's markers), scenarios.json and block.json (title, code, height, pins). Then publish the folder with review_edit, giving fromFiles instead of content or changes. dir defaults to a folder Whiteboard manages; checking out again overwrites it. A publish is refused if the block changed after the checkout.",
             z.strictObject({ ...review, targetId: id, dir: id.optional() }),
             "GET",
             "/:reviewId/inspect",
           ),
+          tool(
+            "render",
+            "See an animation or clip as the reader does: Desktop shows one of its frames (frame: a frame key, or a clip's marker key; omitted, the first) on the open whiteboard and returns it as a PNG image, with the error its script threw, if any. The PNG is also written to the path the result names. After publishing, render each frame you changed and look at it, instead of taking screenshots of the screen. The whiteboard must be open in Desktop: review_create opens it, and review_open opens an existing one.",
+            z.strictObject({ ...review, targetId: id, frame: id.optional() }),
+            "GET",
+            "/:reviewId/render",
+          ),
         ]
       : []),
     tool("list", "List saved reviews.", z.strictObject({}), "GET", ""),
@@ -244,7 +251,7 @@ function withDraftFiles(edit: ReturnType<typeof publishedEdits>) {
     .string()
     .min(1)
     .describe(
-      "An animation's draft folder, from review_checkout or written yourself: publishes its files as the content (insert, replace) or changes (update).",
+      "An animation's or clip's draft folder, from review_checkout or written yourself: publishes its files as the content (insert, replace) or changes (update). frames.json makes it an animation, markers.json a clip.",
     );
 
   const [insert, replace, update, move, remove] = edit.options;

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

@@ -201,21 +201,36 @@ export function documentText(
           );
         break;
       case "animation":
-        for (const [index, frame] of element.frames.entries()) {
-          detail(
-            `Frame ${index + 1} [${frame.key}]: ${frame.title}${frame.caption ? ` — ${frame.caption}` : ""}`,
-          );
+      case "clip":
+        if (element.type === "animation") {
+          for (const [index, frame] of element.frames.entries()) {
+            detail(
+              `Frame ${index + 1} [${frame.key}]: ${frame.title}${frame.caption ? ` — ${frame.caption}` : ""}`,
+            );
 
-          if (frame.code) write(depth + 2, `Code: ${frame.code.join(", ")}`);
+            if (frame.code) write(depth + 2, `Code: ${frame.code.join(", ")}`);
 
-          if (detailed && frame.data !== undefined)
-            write(depth + 2, `Data: ${JSON.stringify(frame.data)}`);
-        }
+            if (detailed && frame.data !== undefined)
+              write(depth + 2, `Data: ${JSON.stringify(frame.data)}`);
+          }
 
-        for (const scenario of element.scenarios ?? [])
-          detail(
-            `Scenario [${scenario.key}] ${scenario.label}: ${scenario.frames.join(" → ")}`,
-          );
+          for (const scenario of element.scenarios ?? [])
+            detail(
+              `Scenario [${scenario.key}] ${scenario.label}: ${scenario.frames.join(" → ")}`,
+            );
+        } else {
+          for (const [index, marker] of element.markers.entries()) {
+            detail(
+              `Marker ${index + 1} [${marker.key}]: ${marker.title}${marker.caption ? ` — ${marker.caption}` : ""}`,
+            );
+
+            if (marker.code)
+              write(depth + 2, `Code: ${marker.code.join(", ")}`);
+          }
+
+          for (const scenario of element.scenarios ?? [])
+            detail(`Scenario [${scenario.key}] ${scenario.label}`);
+        }
 
         if (runs) {
           const run =

package/src/review-api/http.ts

@@ -57,6 +57,7 @@ import { resolveReviewStackLayers } from "@review/review-stack.js";
 import { readBoundedRequestJson } from "@review/server/hono-http.js";
 import { HttpJsonError } from "@review/server/http-json.js";
 import {
+  type RemoteShare,
   type SharingHostEvents,
   mountSharingHost,
 } from "@review/sharing/host.js";
@@ -67,6 +68,11 @@ import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 
 import { anchorQuotes } from "./anchor-quotes.js";
+import {
+  type RenderAnimation,
+  renderQuerySchema,
+  renderTarget,
+} from "./animation-render.js";
 import type { AskRecord } from "./ask-history.js";
 import { authoringTools } from "./authoring-tools.js";
 import { documentText } from "./document-text.js";
@@ -172,7 +178,7 @@ export interface ReviewApiHooks {
     via: ReviewRequestVia;
     agentKind?: ReviewSessionAgent;
   }) => void;
-  sharing?: SharingHostEvents;
+  sharing?: SharingHostEvents & { remoteShare?: RemoteShare };
 }
 
 /** A person's save carries the whole board, which edits one at a time can
@@ -207,6 +213,8 @@ export function createReviewApi(
   /** Desktop's Ask: local agents answering questions about a selection. */
   ask?: AskHost,
   animationsEnabled: () => boolean = () => false,
+  /** Shows a frame of an animation in the attached Desktop and captures it. */
+  render?: RenderAnimation,
 ) {
   const app = new Hono();
   app.onError((error, context) => {
@@ -2085,6 +2093,32 @@ export function createReviewApi(
             },
     );
   });
+  // One frame of an animation (or a clip at a marker) as the reader sees it:
+  // the attached Desktop shows it on the open board and captures it.
+  app.get("/:id/render", async (context) => {
+    const query = renderQuerySchema.parse(context.req.query());
+    const id = context.req.param("id");
+    const target = renderTarget(readReview(id), query.targetId, query.frame);
+
+    if (!render)
+      throw new ReviewInputError(
+        "Rendering a frame needs Whiteboard Desktop, which this server cannot reach.",
+        409,
+      );
+
+    const rendered = await render({
+      reviewId: id,
+      targetId: query.targetId,
+      frame: target.key,
+    });
+
+    return context.json({
+      reviewId: id,
+      targetId: query.targetId,
+      type: target.type,
+      ...rendered,
+    });
+  });
   app.get("/:id", async (context) => {
     const query = readQuerySchemas.get.parse(context.req.query());
 
@@ -2170,12 +2204,15 @@ export function createReviewApi(
             )
           : undefined;
 
+      const animated = (type: string | undefined) =>
+        type === "animation" || type === "clip";
+
       if (
-        incoming.some((element) => element.type === "animation") ||
-        target?.type === "animation"
+        incoming.some((element) => animated(element.type)) ||
+        animated(target?.type)
       )
         throw new ReviewInputError(
-          "Animation authoring is disabled. Enable Animations in Settings under Experimental Features to edit animations. Existing animations can still be viewed.",
+          "Animation authoring is disabled. Enable Animations in Settings under Experimental Features to edit animations and clips. Existing ones can still be viewed.",
           409,
         );
     }
@@ -2196,7 +2233,7 @@ export function createReviewApi(
             ...(threadId && { threadId }),
           };
 
-    // A copy's kept commits go when it is deleted for good.
+    // A link's kept commits go when its last copy is deleted for good.
     const copy =
       input.operation.type === "delete" && store.has(input.operation.reviewId)
         ? store.read(input.operation.reviewId)
@@ -2206,7 +2243,16 @@ export function createReviewApi(
     const key = copy?.shared?.key;
     const kept = copy && boardRepositoryId(copy);
 
-    if (result.deleted && key && kept)
+    if (
+      result.deleted &&
+      key &&
+      kept &&
+      !store
+        .copiesOf(key)
+        .some(
+          ({ reviewId }) => boardRepositoryId(store.read(reviewId)) === kept,
+        )
+    )
       await Promise.resolve()
         .then(() => forgetSharedCommits(store.repositoryPath(kept), key))
         .catch((error) =>

package/src/review-api/instructions.ts

@@ -30,7 +30,7 @@ export interface InstructionContext {
 /** Keep disabled experimental components out of agent guidance. */
 export const desktopBlockTypes = (animationsEnabled: boolean) =>
   writableBlockTypes.filter(
-    (type) => animationsEnabled || type !== "animation",
+    (type) => animationsEnabled || (type !== "animation" && type !== "clip"),
   );
 
 const COMPONENT_EXAMPLE =

package/src/review-api/mcp.ts

@@ -17,7 +17,7 @@ import { authoringTools } from "./authoring-tools.js";
 import type { ReviewApiClient } from "./client.js";
 import { ReviewApiError } from "./client.js";
 import { mcpClientAgent } from "./mcp-client-agent.js";
-import { callPublicTool, publicTool } from "./public-tools.js";
+import { callPublicTool, publicTool, renderedImage } from "./public-tools.js";
 import { RECOVERY } from "./recovery.js";
 import { REVIEW_STATUS_TOOL } from "./status-tool.js";
 import { type ToolFailure, toolFailure } from "./tool-failure.js";
@@ -191,11 +191,14 @@ export async function serveReviewMcp(
           `Unknown Whiteboard tool: ${request.params.name}`,
         );
 
-      const result = await callPublicTool(
-        client,
+      const { image, result } = renderedImage(
         tool,
-        request.params.arguments ?? {},
-        ctx.mcpReq.signal,
+        await callPublicTool(
+          client,
+          tool,
+          request.params.arguments ?? {},
+          ctx.mcpReq.signal,
+        ),
       );
 
       const text = toolResultText(tool, result);
@@ -203,6 +206,8 @@ export async function serveReviewMcp(
 
       const response: CallToolResult = {
         content: [
+          // The frame an agent rendered, ahead of what the host says about it.
+          ...(image ? [{ type: "image" as const, ...image }] : []),
           {
             type: "text",
             text:

package/src/review-api/public-tools.ts

@@ -1,5 +1,9 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
 import { type JsonValue, isJsonObject, isStringValue } from "@dev.fast/json";
 import { boardTitle } from "@dev.fast/review-protocol";
+import { devReviewHome } from "@dev.fast/trace-core";
 import { ReviewInputError } from "@dev.fast/whiteboard-document";
 
 import {
@@ -12,7 +16,7 @@ import {
   checkoutAnimation,
   recordPublish,
   resolveDraftEdit,
-  stageReferenceHint,
+  stageReferenceText,
   writeStageReference,
 } from "./animation-drafts.js";
 import type { ReviewApiClient } from "./client.js";
@@ -131,7 +135,7 @@ export async function callPublicTool(
 
   if (tool.name === "session_get_instructions" && rest.topic === "animation") {
     const instructions = await callAuthoringTool(client, tool, fields, signal);
-    const hint = stageReferenceHint(await writeStageReference());
+    const hint = stageReferenceText(await writeStageReference());
 
     if (instructions instanceof ToolText)
       return new ToolText(`${instructions.text}\n\n${hint}`);
@@ -171,6 +175,13 @@ export async function callPublicTool(
   if (result instanceof ToolText) return result;
   const published = withoutRepositoryIds(publicResult(result));
 
+  if (
+    tool.name === "session_render" &&
+    isStringValue(sessionId) &&
+    isStringValue(rest.targetId)
+  )
+    return saveRenderedFrame(published, sessionId, rest.targetId);
+
   if (
     draft &&
     isStringValue(sessionId) &&
@@ -189,6 +200,64 @@ export async function callPublicTool(
   return published;
 }
 
+/** A tool result with its rendered frame, if any, taken out as an image. */
+export interface RenderedImage {
+  image?: { data: string; mimeType: "image/png" };
+  result: JsonValue | ToolText;
+}
+
+/** A rendered frame's PNG, for an agent that reads images from a tool
+ * result, and the rest of the result for its text. */
+export function renderedImage(
+  tool: Pick<AuthoringTool, "name">,
+  result: JsonValue | ToolText,
+): RenderedImage {
+  if (
+    tool.name !== "session_render" ||
+    result instanceof ToolText ||
+    !isJsonObject(result) ||
+    !isStringValue(result.png)
+  )
+    return { result };
+
+  const { png, ...rest } = result;
+
+  return { image: { data: png, mimeType: "image/png" }, result: rest };
+}
+
+/** Writes the frame's PNG where the agent can open it with its own tools,
+ * beside the animation drafts, and names the file in the result. A folder
+ * that cannot be written leaves the image in the result alone. */
+async function saveRenderedFrame(
+  result: JsonValue,
+  sessionId: string,
+  targetId: string,
+): Promise<JsonValue> {
+  if (!isJsonObject(result) || !isStringValue(result.png)) return result;
+
+  const key =
+    isJsonObject(result.frame) && isStringValue(result.frame.key)
+      ? result.frame.key
+      : "frame";
+
+  const file = path.join(
+    devReviewHome(),
+    "animation-renders",
+    ...[sessionId, targetId, `${key}.png`].map((part) =>
+      part.replace(/[^\w.-]/g, "_"),
+    ),
+  );
+
+  try {
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, Buffer.from(result.png, "base64"));
+  } catch {
+    return result;
+  }
+
+  return { ...result, file };
+}
+
 /** The read a draft compares and records against: session_get's JSON. */
 const INSPECT: AuthoringTool = {
   name: "review_get",