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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.fast/whiteboard",
-  "version": "0.4.0",
+  "version": "0.4.1-preview.20261026.137",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -60,8 +60,8 @@
     "smol-toml": "1.9.0",
     "undici": "7.29.1",
     "yauzl": "3.4.0",
-    "zod": "4.6.5",
-    "@dev.fast/diffr": "0.1.20"
+    "zod": "4.6.6",
+    "@dev.fast/diffr": "0.1.21"
   },
   "devDependencies": {
     "@dev.fast/local-vcs": "^0.1.0",
@@ -74,11 +74,11 @@
     "tsx": "4.21.0",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
-    "@dev.fast/json": "0.0.0",
     "@dev.fast/review-protocol": "0.0.0",
+    "@dev.fast/review-share-protocol": "0.1.2",
     "@dev.fast/trace-core": "0.0.0",
-    "@dev.fast/trace-protocol": "0.5.0",
-    "@dev.fast/review-share-protocol": "0.1.2"
+    "@dev.fast/json": "0.0.0",
+    "@dev.fast/trace-protocol": "0.5.0"
   },
   "engines": {
     "node": ">=24 <25"
@@ -88,7 +88,7 @@
     "repo": "devdotfast/review",
     "docs": "packages/review/instructions/authoring.md"
   },
-  "gitHead": "90564c926cee5f245d498cb56585759cca9b312b",
+  "gitHead": "46629c2739b7efbdb10cd7a98cfacb315e8d7ae0",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",

package/src/fixtures/blocks/animation.json

@@ -0,0 +1,19 @@
+[
+  {
+    "id": "block-1",
+    "type": "animation",
+    "title": "Order status",
+    "height": 300,
+    "frames": [
+      { "key": "before", "title": "An order arrives", "label": "ARRIVE" },
+      {
+        "key": "change",
+        "title": "Its status is queued",
+        "label": "QUEUE",
+        "caption": "The status line sets it."
+      }
+    ],
+    "code": { "status": "head/order.ts#L1" },
+    "html": "<script>const s = whiteboard.scene({ columns: 2 });\nconst client = s.actor({ id: \"client\", at: [1, 1], title: \"Client\", note: \"createOrder()\" });\nconst queue = s.store({ id: \"queue\", at: [2, 1], title: \"Queue\" });\ns.link(client, queue, { label: \"enqueue\", enter: \"change\" });\ns.send(client, queue, \"order\", \"change\");\ns.on(\"change\", queue, { note: \"1 pending\", tone: \"added\" });\nqueue.item(\"order\", { enter: \"change\", tone: \"added\" });\ns.peek(\"status\", { at: [1, 2, 1, 2], enter: \"change\" });</script>"
+  }
+]

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

@@ -6,7 +6,7 @@ import {
   activityEndSchema,
   activityUpdateSchema,
 } from "./activity.js";
-import { pathTargetSchema, publishedEditSchema } from "./document.js";
+import { pathTargetSchema, publishedEdits } from "./document.js";
 import { instructionsQuerySchema } from "./instructions.js";
 import { uploadSchema } from "./local-data.js";
 import { inspectQuerySchema } from "./read-schemas.js";
@@ -14,9 +14,12 @@ import { REVIEW_STATUS_TOOL } from "./status-tool.js";
 import { commandSchema } from "./store.js";
 
 /** The host publishes its input schemas, except where agents write less than
- * the host accepts (publishedEditSchema, publishedLensEditSchema) or name a
+ * the host accepts (publishedEdits, publishedLensEditSchema) or name a
  * checkout by path (pathTargetSchema); adapters validate nothing. */
-export function authoringTools(traceEnabled = false) {
+export function authoringTools(
+  traceEnabled = false,
+  animationsEnabled = false,
+) {
   const id = z.string().min(1);
   const review = { reviewId: id };
 
@@ -38,7 +41,7 @@ export function authoringTools(traceEnabled = false) {
     create:
       'Create a whiteboard. target names its repository by the checkout\'s path, and what it shows: {kind:"project"} for a plan in that repository\'s project with no change; {kind:"worktree", base?} for the saved files in the checkout, uncommitted ones included and untracked ones left out (git add -N a new file to include it), against base, by default the repository\'s default branch, from the merge base of base and HEAD, which follows rebases; {kind:"commits", head, base?} for immutable commits (omitted base means source at head with no diff; supply the parent to review introduced changes); {kind:"pullRequest", pullRequest} for a GitHub PR by URL or number, fetched into that checkout and pinned at the PR head and GitHub diff base. For a branch stacked on another, pass the branch below it as base. Group plan implementations or a PR stack under one project-target overview with parentId, and order its children with dependsOn; Git bases do not set these relationships. Revisions are resolved on acceptance. With a PR and no title the PR\'s title is used. When the existing review for that PR is in Trash, creation reports its ID; restore it with review_lifecycle state:"active" before continuing. When an active review for that PR exists, it is returned instead, reporting whether its head moved and whether an agent is working on it; update it in place, move its target with review_set_target, or create a separate review with reuseExisting:false. The result carries review, as review_list shows it, with its target and repositoryPath, so no follow-up read is needed before diffing. When Desktop is available the review opens there and the result reports opened, softwareMapEnabled and environmentIssues, as review_open does; set open:false to author in the background without taking over Desktop. parentId and dependsOn set its place among the project\'s reviews, as review_set_parent and review_set_dependencies do; projectId files it in another project, by project.id from review_list.',
     set_target:
-      "Move the review to a new target (the same targets review_create takes), such as the commits after a rebase or amend, or commits or a PR for a board that had none. The document and component IDs are kept. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. A PR target names the PR; other targets keep it within the same repository and clear it across repositories.",
+      "Move the review to a new target (the same targets review_create takes), such as the commits after a rebase or amend, or commits or a PR for a board that had none. The document and component IDs are kept. Revisions are resolved on acceptance. Returns warnings for retained source ranges in files the new commits changed, to verify, and resources that no longer match; fix them with review_edit. Earlier versions keep their source. A PR target names the PR; other targets keep it within the same repository and clear it across repositories. To refresh a PR review, pass its PR target again: a commits target with its branch names pins their tips, not the PR's diff base.",
     edit: [
       "Edit one document component. content is one component, named by its type; each type's fields are in the Components section of session_get_instructions.",
       "Anchors are head/path#L10-L20 or base/path#L7, or diff/path#L84-R90 for a range across sides, with repository-relative paths and 1-based inclusive lines. pins {head, base?} say which commits of the whiteboard's repository anchors quote: a step, frame, attachment or operation without pins uses its block's, and a block without them the review's.",
@@ -97,7 +100,15 @@ export function authoringTools(traceEnabled = false) {
         (traceEnabled
           ? ' Call review_get_instructions({topic:"trace-archaeology"}) for why code exists, what an agent was thinking, or whether an agent solved this before.'
           : ""),
-      instructionsQuerySchema.partial(),
+      instructionsQuerySchema
+        .extend({
+          topic: animationsEnabled
+            ? instructionsQuerySchema.shape.topic
+            : z
+                .enum(["authoring", "file-lenses", "trace-archaeology"])
+                .default("authoring"),
+        })
+        .partial(),
       "GET",
       "/instructions",
     ),
@@ -144,7 +155,7 @@ export function authoringTools(traceEnabled = false) {
             open: z.boolean().optional(),
           }),
           ...(type === "set_target" && { target: pathTargetSchema }),
-          ...(type === "edit" && { edit: publishedEditSchema }),
+          ...(type === "edit" && { edit: publishedEdits(animationsEnabled) }),
         }),
         "POST",
         "/commands",

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

@@ -0,0 +1,98 @@
+import { anchorSchema } from "@review/lens-selection.js";
+import { ReviewInputError } from "@review/review-api/input-error.js";
+import { z } from "zod";
+
+import {
+  type BlockDefinition,
+  defineBlock,
+  elementPins,
+  label,
+  text,
+} from "./definition.js";
+
+/** A name the stage's script passes to the `whiteboard` shim. */
+const handle = z
+  .string()
+  .regex(
+    /^[A-Za-z][\w-]{0,63}$/,
+    "Use a short name: a letter, then letters, digits, _ or -.",
+  );
+
+export const animationFrameSchema = z.strictObject({
+  key: handle.describe(
+    "Names the frame for the stage: data-frame on <html>, data-enter/data-exit, and whiteboard.on(key, ...).",
+  ),
+  title: label,
+  label: z
+    .string()
+    .min(1)
+    .max(24)
+    .optional()
+    .describe(
+      "A short name for the step strip under the stage, e.g. PUSH. Give every frame one, or none.",
+    ),
+  caption: text
+    .optional()
+    .describe("One or two short sentences shown under the stage."),
+  duration: z
+    .number()
+    .int()
+    .min(300)
+    .max(30_000)
+    .optional()
+    .describe("Milliseconds this frame stays up while playing. Default 3000."),
+});
+
+export type AnimationFrame = z.infer<typeof animationFrameSchema>;
+
+export const animationSchema = defineBlock("animation", {
+  title: label,
+  html: text
+    .min(1)
+    .max(200_000)
+    .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"}).',
+    ),
+  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.",
+    ),
+  code: z
+    .record(handle, anchorSchema)
+    .default({})
+    .describe(
+      "Source ranges the stage shows as code peeks, by name: whiteboard.code(name).",
+    ),
+  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.",
+    ),
+  pins: elementPins,
+});
+
+export type AnimationBlock = z.infer<typeof animationSchema>;
+
+export const animation = {
+  type: "animation",
+  schema: animationSchema,
+  check(block: AnimationBlock) {
+    const keys = new Set(block.frames.map((frame) => frame.key));
+
+    if (keys.size !== block.frames.length)
+      throw new ReviewInputError(
+        "Animation frame keys must be unique within the animation.",
+      );
+
+    const labelled = block.frames.filter((frame) => frame.label).length;
+
+    if (labelled && labelled !== block.frames.length)
+      throw new ReviewInputError(
+        "Give every animation frame a label, or none: the step strip needs one per frame.",
+      );
+  },
+} satisfies BlockDefinition<AnimationBlock>;

package/src/review-api/blocks/index.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { animation } from "./animation.js";
 import { call_stack_diff } from "./call_stack_diff.js";
 import { type CalloutBlock, callout, calloutSchema } from "./callout.js";
 import { code } from "./code.js";
@@ -28,6 +29,7 @@ export const leafSchema = z.discriminatedUnion("type", [
   trace_quote.schema,
   software_map.schema,
   flow_diagram.schema,
+  animation.schema,
 ]);
 
 export type LeafBlock = z.infer<typeof leafSchema>;
@@ -53,6 +55,7 @@ export const blocks = {
   trace_quote,
   software_map,
   flow_diagram,
+  animation,
   section,
   callout,
 } satisfies Definitions;

package/src/review-api/blocks/sequence.ts

@@ -32,7 +32,9 @@ export const stepSchema = z
     /** The call site this arrow stands for, then any ranges directly about
      * that call, each shown as its own card. */
     source: z
-      .union([anchorSchema, z.array(anchorSchema).min(1).max(4)])
+      .union([anchorSchema, z.array(anchorSchema).min(1).max(4)], {
+        error: "source must be one range or a list of 1 to 4 ranges",
+      })
       .optional(),
     pins: elementPins,
     explanation: label.optional(),

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 (