@jxsuite/studio 4.0.0 → 5.0.0

package/src/canvas/dialog-state.ts

@@ -0,0 +1,67 @@
+/// <reference lib="dom" />
+/**
+ * Which `<dialog>` the canvas draws open, and the rule that decides it from a selection.
+ *
+ * The dialog twin of `popover-state.ts`, and the same shape on purpose: one writer of
+ * `ui.openDialog` (`setOpenDialog`), one asymmetric reveal rule (selecting at or inside a dialog
+ * opens it; selecting outside every dialog leaves the open one alone, so it can be styled from the
+ * Inspector), and no watch of its own — `popover-state.ts`'s reveal effect runs both rules, because
+ * two effects over the same selection would be two observers of one fact.
+ *
+ * A dialog shown in place is the canvas's affordance and nothing more: `session.ui.openDialog` is
+ * per-tab view state, takes no undo entry, does not replicate, and is not restored with a session.
+ * Preview renders the dialog natively, modal, backdrop and all.
+ *
+ * @docs studio/interface/canvas
+ */
+
+import { ancestorDialogPath } from "./dialog-path";
+import { postDialogOpen } from "./iframe-host";
+import { primarySelection } from "../tabs/selection";
+import { updateSession } from "../store";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxPath } from "../state";
+import type { Tab } from "../tabs/tab";
+
+/** Whether two paths address the same node. */
+function samePath(a: JxPath | null, b: JxPath | null): boolean {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return a.length === b.length && a.every((seg, i) => seg === b[i]);
+}
+
+/**
+ * Write `ui.openDialog` and tell every frame showing this tab.
+ *
+ * The single writer. `canvas.setDialogOpen`, the reveal rule and an invoker's click in the canvas
+ * all land here, so the model and the frames cannot disagree about which dialog is open.
+ *
+ * @param tab The tab whose dialog state is written.
+ * @param path The dialog to open, or null to close.
+ */
+export function setOpenDialog(tab: Tab, path: JxPath | null): void {
+  updateSession(tab, { ui: { openDialog: path } });
+  postDialogOpen(tab, path);
+}
+
+/**
+ * Open the dialog `path` is at or inside, if it is not already the open one.
+ *
+ * @returns Whether anything changed.
+ */
+export function openDialogFor(tab: Tab, path: JxPath | null): boolean {
+  const target = ancestorDialogPath(tab.doc.document as JxMutableNode, path);
+  if (target === null || samePath(tab.session.ui.openDialog, target)) {
+    return false;
+  }
+  setOpenDialog(tab, target);
+  return true;
+}
+
+/** The reveal rule for dialogs, over the tab's primary selection. */
+export function reconcileOpenDialog(tab: Tab | null | undefined): void {
+  if (tab) {
+    openDialogFor(tab, primarySelection(tab.session.selection));
+  }
+}

package/src/canvas/diff-marks.ts

@@ -0,0 +1,252 @@
+/**
+ * The two-sided change map behind the diff artboards' red/green marks.
+ *
+ * **Why this is not `diffDocs`.** `diffDocs` answers a different question: it emits a REPLAY
+ * SCRIPT, a list of ops that turn `a` into `b` when applied in order. Its removals are emitted
+ * descending against `a`'s indices, its inserts ascend against `b`'s final indices, and its
+ * recursion carries the `b`-side index — so every path it hands out is a post-splice coordinate
+ * valid only in `b`. The Original artboard needs `a`-side paths, and the stepper needs the two
+ * sides PAIRED so that "change 3 of 12" names the same change on both boards. Recovering either
+ * from an op list means re-running the matcher, which would be a second definition of "the same
+ * node".
+ *
+ * So this walks the two trees together, carrying `aPath` and `bPath` at once, and aligns each
+ * `children` array through `matchChildren` — the same LCS pairing `diffDocs` uses, exported from
+ * `@jxsuite/collab/diff-core` for exactly this. The import is static and costs no yjs: that is what
+ * the `diff-core` split bought.
+ *
+ * **Three rules the walk encodes, each because of what the canvas can actually stamp.**
+ *
+ * 1. A change to a node's own keys marks THAT node, once, however many keys moved. `textContent` is a
+ *    key, so the ordinary "someone edited this paragraph" case marks the paragraph — the element
+ *    that carries `data-jx-path`.
+ * 2. A bare string child is not an element and is never stamped (`makeStamper` returns early for
+ *    anything that is not an `HTMLElement`), so a change to one is attributed to its PARENT. The
+ *    alternative is a mark addressed to a node the frame cannot resolve, which is a change the
+ *    count promises and the artboard never shows.
+ * 3. A root-level key change — `state`, `$head`, a `$props` default — emits NO mark, because the
+ *    root's stamped element is the whole page and tinting it says "everything changed". Those keys
+ *    are reported in {@link ChangeMap.rootKeys} instead, for the header to state in words.
+ *
+ * Reorders of identical siblings come back as a removal plus an addition rather than a "moved"
+ * pair, and that is deliberate: the matcher genuinely cannot tell a move from a delete-plus-insert
+ * of an equal value, so a "moved" mark would be a claim the data does not support. It is also what
+ * `git diff` prints for a moved block.
+ */
+
+import { deepEqual, matchChildren } from "@jxsuite/collab/diff-core";
+import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+
+/** What happened to a node. `modified` means the node survived and its own content changed. */
+export type ChangeKind = "added" | "removed" | "modified";
+
+/** One node to tint, in one artboard's coordinate space. */
+export interface ChangeMark {
+  path: JxPath;
+  kind: ChangeKind;
+}
+
+/**
+ * One entry in the stepper's list, naming the change on BOTH boards where both have it.
+ *
+ * A removal has no `currentPath` and an addition no `originalPath` — the pair of artboards is what
+ * shows that, with a tinted block on one side and space beside it on the other.
+ */
+export interface ChangeStep {
+  kind: ChangeKind;
+  originalPath: JxPath | null;
+  currentPath: JxPath | null;
+}
+
+export interface ChangeMap {
+  /** `removed` and `modified`, addressed in the ORIGINAL document. */
+  original: ChangeMark[];
+  /** `added` and `modified`, addressed in the CURRENT document. */
+  current: ChangeMark[];
+  /** Every change in document reading order — the stepper's list. */
+  steps: ChangeStep[];
+  /** Root-level keys that changed. Stated in words; never tinted (rule 3 above). */
+  rootKeys: string[];
+  /** A sibling group was too large to align, so its changes are splices rather than pairs. */
+  degraded: boolean;
+}
+
+export interface ChangeMapOptions {
+  /**
+   * Largest `a.length * b.length` this will align before giving up on a sibling group.
+   *
+   * The LCS table is the only unbounded cost in the walk, and a generated listing page falsifies
+   * `lcsPairs`'s "typically < 200" assumption. Over budget the group degrades to plain removals and
+   * additions — still correct marks, just not paired — and {@link ChangeMap.degraded} says so.
+   */
+  maxCells?: number;
+}
+
+const DEFAULT_MAX_CELLS = 250_000;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+class ChangeWalker {
+  readonly original: ChangeMark[] = [];
+  readonly current: ChangeMark[] = [];
+  readonly steps: ChangeStep[] = [];
+  readonly rootKeys: string[] = [];
+  degraded = false;
+
+  private readonly maxCells: number;
+  /* Rule 2 attributes a string child's change to its parent, so one parent with three edited text
+     children would otherwise be marked three times — and the stepper would offer three stops that
+     all reveal the same element. Deduped on (kind, path) rather than on path alone: a node whose
+     children were spliced can legitimately be both an addition target and a modification. */
+  private readonly seen = new Set<string>();
+
+  constructor(maxCells: number) {
+    this.maxCells = maxCells;
+  }
+
+  private emit(kind: ChangeKind, aPath: JxPath | null, bPath: JxPath | null): void {
+    const key = `${kind}:${aPath ? JSON.stringify(aPath) : ""}:${bPath ? JSON.stringify(bPath) : ""}`;
+    if (this.seen.has(key)) {
+      return;
+    }
+    this.seen.add(key);
+    if (aPath && kind !== "added") {
+      this.original.push({ kind, path: aPath });
+    }
+    if (bPath && kind !== "removed") {
+      this.current.push({ kind, path: bPath });
+    }
+    this.steps.push({ currentPath: bPath, kind, originalPath: aPath });
+  }
+
+  diffNode(
+    aPath: JxPath,
+    bPath: JxPath,
+    a: Record<string, unknown>,
+    b: Record<string, unknown>,
+  ): void {
+    const isRoot = aPath.length === 0 && bPath.length === 0;
+    let ownChanged = false;
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (key === "children" || deepEqual(a[key], b[key])) {
+        continue;
+      }
+      if (isRoot) {
+        // Rule 3: reported, never tinted. The root's element is the whole page.
+        if (!this.rootKeys.includes(key)) {
+          this.rootKeys.push(key);
+        }
+      } else {
+        ownChanged = true;
+      }
+    }
+    if (ownChanged) {
+      this.emit("modified", aPath, bPath);
+    }
+
+    const ca = a["children"];
+    const cb = b["children"];
+    if (Array.isArray(ca) && Array.isArray(cb)) {
+      this.diffChildren(aPath, bPath, ca, cb);
+    } else if (!deepEqual(ca, cb) && !isRoot) {
+      /* Mapped-array children, or one side having none at all. There is no per-child alignment to
+         make here, so the owning node carries it — the same call `diffDocs` makes when it replaces
+         `children` wholesale rather than splicing. */
+      this.emit("modified", aPath, bPath);
+    }
+  }
+
+  private diffChildren(
+    aPath: JxPath,
+    bPath: JxPath,
+    ca: readonly unknown[],
+    cb: readonly unknown[],
+  ): void {
+    if (ca.length * cb.length > this.maxCells) {
+      this.degraded = true;
+    }
+    const matches = matchChildren(ca, cb, { maxCells: this.maxCells });
+    let i = 0;
+    let j = 0;
+    /* ONE merged pass, ascending on both sides at once, which is what puts `steps` in reading order
+       for both artboards simultaneously. Matches never cross, so draining the gap before each match
+       cannot emit a path out of order on either side. */
+    for (const match of matches) {
+      for (; i < match.aIndex; i++) {
+        this.emitChild("removed", aPath, bPath, ca[i], i, null);
+      }
+      for (; j < match.bIndex; j++) {
+        this.emitChild("added", aPath, bPath, cb[j], null, j);
+      }
+      if (!match.identical) {
+        const aItem = ca[match.aIndex];
+        const bItem = cb[match.bIndex];
+        if (isPlainObject(aItem) && isPlainObject(bItem)) {
+          this.diffNode(
+            [...aPath, "children", match.aIndex],
+            [...bPath, "children", match.bIndex],
+            aItem,
+            bItem,
+          );
+        } else if (!deepEqual(aItem, bItem)) {
+          // Rule 2: at least one side is a bare string, which is never a stamped element.
+          this.emit("modified", aPath, bPath);
+        }
+      }
+      i = match.aIndex + 1;
+      j = match.bIndex + 1;
+    }
+    for (; i < ca.length; i++) {
+      this.emitChild("removed", aPath, bPath, ca[i], i, null);
+    }
+    for (; j < cb.length; j++) {
+      this.emitChild("added", aPath, bPath, cb[j], null, j);
+    }
+  }
+
+  /** A spliced child: marked at its own path when it is an element, at its parent's when it is not. */
+  private emitChild(
+    kind: "added" | "removed",
+    aPath: JxPath,
+    bPath: JxPath,
+    item: unknown,
+    aIndex: number | null,
+    bIndex: number | null,
+  ): void {
+    if (!isPlainObject(item)) {
+      this.emit("modified", aPath, bPath);
+      return;
+    }
+    this.emit(
+      kind,
+      aIndex === null ? null : [...aPath, "children", aIndex],
+      bIndex === null ? null : [...bPath, "children", bIndex],
+    );
+  }
+}
+
+/**
+ * Every node that differs between `a` and `b`, in both documents' coordinates.
+ *
+ * Never throws for size and never answers null: a partial set of marks is still correct for the
+ * nodes it names, which is the opposite of `diffDocs`'s bargain (a partial op list would corrupt a
+ * document, so it returns null past its cap). {@link ChangeMap.degraded} is how a caller tells the
+ * reader that a group was too big to pair up.
+ */
+export function buildChangeMap(
+  a: JxMutableNode,
+  b: JxMutableNode,
+  opts: ChangeMapOptions = {},
+): ChangeMap {
+  const walker = new ChangeWalker(opts.maxCells ?? DEFAULT_MAX_CELLS);
+  walker.diffNode([], [], a as Record<string, unknown>, b as Record<string, unknown>);
+  return {
+    current: walker.current,
+    degraded: walker.degraded,
+    original: walker.original,
+    rootKeys: walker.rootKeys,
+    steps: walker.steps,
+  };
+}

package/src/canvas/diff-toolbar.ts

@@ -0,0 +1,349 @@
+/// <reference lib="dom" />
+/**
+ * The diff stage's own chrome: how many changes there are, and how to walk them.
+ *
+ * **This is the flow; `surfaces/diff-toolbar.json` is the markup.** What the count means for the
+ * half that is showing, which step is reachable, whether a comparison has a visual half at all and
+ * what a step does to both artboards are decided here; the bar's structure, ARIA, keyboard and
+ * style live in the document beside it.
+ *
+ * **It owns its own reactivity from here**, the way `renderGridMode` does. A step must not go
+ * through `renderCanvas(paneId)`: that rebuilds the stage and remounts both artboard iframes, so
+ * pressing "next change" would tear down and reload the very documents it is trying to move you
+ * through. The toolbar keeps a host element per pane, mounts ONE document into it, and a redraw
+ * writes that document's scope.
+ *
+ * **It is an absolutely-positioned SIBLING of the stage's pan/zoom wrap, never a child and never in
+ * flow.** A child would be scaled and panned along with the artboards; a flow sibling would shift
+ * the origin `applyTransform` and `centerCanvas` compute against, so entering the mode would centre
+ * the boards somewhere other than where the pan maths says they are. That placement belongs to the
+ * stage — `surfaces/canvas-stage.json` draws the host — because where a floating bar sits over a
+ * pan/zoom surface is a fact about the stage rather than about the bar.
+ */
+
+import { argsSchema, enumArg, enumProperty, stringProperty } from "../commands/command-args";
+import type { CommandArgValues } from "../commands/command-args";
+import type { AnyCommand } from "../commands/registry";
+import {
+  diffChangeCount,
+  diffChangeMapOf,
+  diffStepOf,
+  diffViewOf,
+  setDiffView,
+  stepDiff,
+} from "./diff-view";
+import type { DiffView } from "./diff-view";
+import type { ChangeStep } from "./diff-marks";
+import { panToParentRect } from "./canvas-utils";
+import { surfaceForPane } from "./canvas-surface";
+import { announce } from "../services/announce";
+import { workspace } from "../workspace/workspace";
+import { mountDiffToolbarSurface } from "../surfaces/diff-toolbar";
+import type { DiffToolbarSurfaceHandle, DiffToolbarView } from "../surfaces/diff-toolbar";
+
+/**
+ * Where each pane's toolbar draws, and the document standing in it.
+ *
+ * Pane-keyed and module-local, like the rest of the diff state — and the MOUNT is kept beside the
+ * host rather than rebuilt per redraw. A step redraws the bar several times a second; remounting a
+ * document each time would be the same defect the stage-rebuild note above describes, one level
+ * down. A new host means a new stage, so that one is a genuine remount.
+ */
+const _bars = new Map<string, { host: HTMLElement; surface: DiffToolbarSurfaceHandle | null }>();
+
+/** Record (or forget) the element a pane's toolbar renders into. */
+export function setDiffToolbarHost(paneId: string, host: HTMLElement | null): void {
+  const standing = _bars.get(paneId);
+  if (standing && standing.host !== host) {
+    standing.surface?.dispose();
+    _bars.delete(paneId);
+  }
+  if (host && !_bars.has(paneId)) {
+    _bars.set(paneId, { host, surface: null });
+  }
+}
+
+/**
+ * How this module asks a pane to redraw, injected by `canvas-render.ts`.
+ *
+ * **By injection rather than by import**, the same idiom `setSurfaceTeardown` uses and for the same
+ * reason: `canvas-render.ts` imports THIS module, so an edge back would close a cycle. A dynamic
+ * import would break the cycle too, and it was tried — but a dynamic import of a module that is
+ * otherwise statically reachable makes the bundler hoist it into a shared chunk, which moved 664 KB
+ * out of `studio.js` and pushed `chunks` past its budget. An injected function costs nothing.
+ */
+let _repaint: (paneId: string) => void = () => {};
+
+/** Register the repaint. Called once, from `canvas-render.ts`. */
+export function setDiffRepaint(repaint: (paneId: string) => void): void {
+  _repaint = repaint;
+}
+
+/**
+ * Rebuild the whole stage, because Visual and Code are different renders rather than different
+ * styling: one draws two artboards on a pan/zoom surface, the other one Monaco.
+ *
+ * `prevCanvasMode` is nulled first — the documented "this stage's structure is stale" signal, the
+ * same one `resetCanvasView` ends on. Without it the repaint sees `modeChanged === false` (the
+ * canvas mode did not move; only the view within it did) and skips the setup the new branch needs.
+ */
+function repaintDiffStage(paneId: string): void {
+  surfaceForPane(paneId).prevCanvasMode = null;
+  _repaint(paneId);
+}
+
+/** Redraw one pane's toolbar in place, without touching its artboards. */
+export function renderDiffToolbar(paneId: string): void {
+  const bar = _bars.get(paneId);
+  if (!bar) {
+    return;
+  }
+  const view = diffToolbarView(paneId);
+  if (bar.surface) {
+    bar.surface.update(view);
+    return;
+  }
+  bar.surface = mountDiffToolbarSurface(bar.host, view, {
+    next: () => onStepClick(paneId, 1),
+    previous: () => onStepClick(paneId, -1),
+    showCode: () => selectDiffView(paneId, "code"),
+    showVisual: () => selectDiffView(paneId, "visual"),
+  });
+}
+
+/**
+ * Choose which half of a comparison is showing.
+ *
+ * Idempotent, and for the same reason `diff.setView` is: re-selecting the half already on screen
+ * must rebuild nothing, because the rebuild remounts both artboard iframes.
+ */
+function selectDiffView(paneId: string, view: DiffView): void {
+  if (diffViewOf(paneId) === view) {
+    return;
+  }
+  setDiffView(paneId, view);
+  repaintDiffStage(paneId);
+}
+
+/** How a change reads aloud, for the step announcement. */
+function describeStep(step: ChangeStep, index: number, total: number): string {
+  const kind = step.kind === "modified" ? "changed" : step.kind;
+  return `Change ${index + 1} of ${total}, ${kind}.`;
+}
+
+/**
+ * A stepper button's click.
+ *
+ * One handler for both directions, so the failure path is written once. A rejection here is not an
+ * outcome to raise: the cursor has already moved and the toolbar has already redrawn to say where
+ * it is, so a reveal that could not measure leaves a correct toolbar over an unmoved canvas.
+ */
+function onStepClick(paneId: string, delta: 1 | -1): void {
+  stepDiffAndReveal(paneId, delta).catch((error: unknown) => {
+    console.warn("stepDiffAndReveal:", error);
+  });
+}
+
+/**
+ * Move to the next or previous change and bring it on screen on BOTH artboards.
+ *
+ * The two boards share one `.panzoom-wrap` and therefore one vertical offset, so this pans to the
+ * UNION of the two rects rather than centring either: a node that sits at a different height on the
+ * two sides is only fully readable if the move accounts for both. A change that exists on one side
+ * only — a removal has no counterpart to the right of it, an addition none to the left — pans to
+ * the one rect there is, so the step never becomes a no-op just because it is one-sided.
+ */
+export async function stepDiffAndReveal(paneId: string, delta: 1 | -1): Promise<void> {
+  const landed = stepDiff(paneId, delta);
+  if (landed === null) {
+    return;
+  }
+  renderDiffToolbar(paneId);
+  const step = diffChangeMapOf(paneId)?.steps[landed];
+  const { panels } = surfaceForPane(paneId);
+  const original = panels[0]?.canvas as HTMLElement | undefined;
+  const current = panels[1]?.canvas as HTMLElement | undefined;
+  if (!step) {
+    return;
+  }
+  /* DYNAMICALLY, and not for size. `iframe-host.ts` is one of the most-mocked modules in the
+     suite — a dozen files replace it with a partial stub — and a partial mock of a module the
+     static graph reaches is a LOAD error, not a missing stub at call time. A static import here
+     would have made every one of those files grow three exports it never calls. The step is
+     already async, so this costs nothing, and it is the same idiom `canvas-render.ts` uses for
+     the collab binding. */
+  const { hostForCanvas, measureInCanvas, revealCanvasPathIn } = await import("./iframe-host");
+  const measured = await Promise.all([
+    step.originalPath && original ? measureInCanvas(original, step.originalPath) : null,
+    step.currentPath && current ? measureInCanvas(current, step.currentPath) : null,
+  ]);
+  const rects = measured.filter((rect) => rect !== null);
+  const sentence = describeStep(step, landed, diffChangeCount(paneId));
+  if (rects.length === 0) {
+    // The node is real but unstamped — a component's internals, or a repeater row past the first.
+    // The count still names it, and the Code view still shows it; there is simply nowhere to pan.
+    announce(`${sentence} Not shown on the canvas.`);
+    return;
+  }
+  const top = Math.min(...rects.map((rect) => rect.top));
+  const bottom = Math.max(...rects.map((rect) => rect.top + rect.height));
+  /* Pan only. The two artboards sit side by side at a fixed 800px each and `fitOnCanvasEntry`
+     framed both horizontally on arrival; moving X per step would read as the canvas being dragged
+     sideways under the reader. */
+  panToParentRect({ height: bottom - top, top }, surfaceForPane(paneId));
+  // Re-measure through the reveal so the ring (and any caller acting on the point) sees where the
+  // Node ended up, not where it was before the move — `revealCanvasPath`'s own rule.
+  const host = step.currentPath && current ? hostForCanvas(current) : null;
+  if (host && step.currentPath) {
+    await revealCanvasPathIn(host, step.currentPath);
+  }
+  announce(sentence);
+}
+
+/**
+ * What the toolbar says, as one value.
+ *
+ * The counter is text rather than a button because it has no verb — `.pc-zoom-label` is a button
+ * only because clicking it resets the zoom. Before the first step it reads "12 changes" rather than
+ * "0 of 12", because the author is not on a change yet.
+ *
+ * @param {string} paneId
+ * @returns {DiffToolbarView}
+ */
+export function diffToolbarView(paneId: string): DiffToolbarView {
+  const map = diffChangeMapOf(paneId);
+  /* THE COUNT BELONGS TO THE VIEW THAT IS SHOWING, and the two views count different things. The
+     change map counts NODES, which is the right answer for the artboards and the wrong one for a
+     text comparison: a `package.json` whose dependency versions moved has no node change at all —
+     its keys are the ROOT's, and a root key is reported in words rather than tinted — so the Code
+     view sat over a screenful of red and green saying "No changes, document settings changed".
+     Monaco owns the line diff and its own navigation there, so the toolbar states what it is
+     showing and steps out of the way. */
+  const code = diffViewOf(paneId) === "code" || map === null;
+  const total = code ? 0 : diffChangeCount(paneId);
+  const index = code ? -1 : diffStepOf(paneId);
+  const countLabel = code
+    ? "Changed lines are marked"
+    : total === 0
+      ? "No changes"
+      : index < 0
+        ? `${total} ${total === 1 ? "change" : "changes"}`
+        : `${index + 1} of ${total}`;
+  const showing = diffViewOf(paneId);
+  return {
+    codeChecked: showing === "code" ? "true" : "false",
+    countLabel,
+    degraded: !code && map?.degraded ? "shown" : "hidden",
+    nextDisabled: index >= total - 1,
+    prevDisabled: index <= 0,
+    rootKeys: !code && map?.rootKeys.length ? "shown" : "hidden",
+    rootKeysTitle: `Changed: ${map?.rootKeys.join(", ") ?? ""}`,
+    stepper: total === 0 ? "hidden" : "shown",
+    // A file the canvas cannot render arrives with a null map: there is no visual half to offer.
+    viewMode: map === null ? "static" : "choice",
+    visualChecked: showing === "visual" ? "true" : "false",
+  };
+}
+
+/** The pane a diff verb addresses: named, or the focused one. */
+function paneOfArgs(args: CommandArgValues): string {
+  const { pane } = args as { pane?: unknown };
+  return typeof pane === "string" ? pane : workspace.activePaneId;
+}
+
+const paneProperty = stringProperty("Which pane to act on. Defaults to the focused one.");
+
+/**
+ * The stepper verbs' schema: `pane` declared, nothing required.
+ *
+ * `argsSchema`'s default requires every key, and the two keybound records took it, so their schemas
+ * said `pane` was required while `paneOfArgs` fell back to the focused pane and F7 ran them with
+ * `{}`. `registry.run` now coerces against the schema before `run`, for a chord as much as for the
+ * palette, so a required `pane` would have made F7 a refusal.
+ */
+const stepperArgs = argsSchema({ pane: paneProperty }, []);
+
+/**
+ * Walking a comparison, and choosing which half of it to read.
+ *
+ * **`keyScope` is `global`, not `canvas`**, and that is not a preference. `keyScopeStack` switches
+ * on `ctx.editor.kind`, and `diff` falls through to the default arm — its own docstring says so:
+ * "Preview and the non-editing surfaces (the diff view, the media library, the stylebook) get the
+ * bare `global` stack." A chord declared in the canvas scope would never fire here.
+ *
+ * `f7` / `shift+f7` are VSCode's own next/previous-difference chords and are free in this keymap
+ * (`f6` / `shift+f6` are region cycling).
+ */
+export function diffCommands(): AnyCommand[] {
+  const onDiff = (paneId: string) => diffChangeCount(paneId) > 0;
+  return [
+    {
+      args: stepperArgs,
+      category: "View",
+      group: "3_canvas",
+      id: "diff.nextChange",
+      keybinding: "f7",
+      keyScope: "global",
+      level: "document",
+      menus: ["palette"],
+      requires: "a pane showing a comparison with changes",
+      title: "Next Change",
+      undo: "none",
+      when: (ctx) => ctx.editor.kind === "diff",
+      // The FOCUSED pane, because that is what a command's subject is. The toolbar's own buttons
+      // Call `stepDiffAndReveal(paneId, …)` with the pane they were drawn for instead — one
+      // Implementation, two subjects, which is the split `check-pane-singletons.ts` looks for.
+      enablement: () => onDiff(workspace.activePaneId),
+      run: (_ctx, args) => stepDiffAndReveal(paneOfArgs(args), 1),
+    },
+    {
+      args: stepperArgs,
+      category: "View",
+      group: "3_canvas",
+      id: "diff.previousChange",
+      keybinding: "shift+f7",
+      keyScope: "global",
+      level: "document",
+      menus: ["palette"],
+      requires: "a pane showing a comparison with changes",
+      title: "Previous Change",
+      undo: "none",
+      when: (ctx) => ctx.editor.kind === "diff",
+      // The FOCUSED pane, because that is what a command's subject is. The toolbar's own buttons
+      // Call `stepDiffAndReveal(paneId, …)` with the pane they were drawn for instead — one
+      // Implementation, two subjects, which is the split `check-pane-singletons.ts` looks for.
+      enablement: () => onDiff(workspace.activePaneId),
+      run: (_ctx, args) => stepDiffAndReveal(paneOfArgs(args), -1),
+    },
+    {
+      args: argsSchema(
+        {
+          pane: paneProperty,
+          view: enumProperty(["visual", "code"], "Which half of the comparison to show."),
+        },
+        ["view"],
+      ),
+      category: "View",
+      group: "3_canvas",
+      id: "diff.setView",
+      level: "document",
+      menus: ["palette"],
+      requires: "a pane showing a comparison",
+      title: "Set Diff View",
+      undo: "none",
+      when: (ctx) => ctx.editor.kind === "diff",
+      /* No `aiTool`, by §12.4's first deletion rule: chrome. */
+      run: (_ctx, args) => {
+        // An idempotent SETTER, never a toggle: the screenshot contract refuses a `toggle*` id, and
+        // A verb whose result depends on the state it is called in cannot be photographed honestly.
+        const view = enumArg("diff.setView", args, "view", ["visual", "code"] as const);
+        const paneId = paneOfArgs(args);
+        if (diffViewOf(paneId) === view) {
+          return;
+        }
+        setDiffView(paneId, view);
+        repaintDiffStage(paneId);
+      },
+    },
+  ];
+}