@jxsuite/studio 5.3.0 → 5.4.0

package/src/canvas/canvas-utils.ts

@@ -674,11 +674,17 @@ export function resetZoom(surface: CanvasSurface = activeCanvasSurface()) {
  * (`iframe-host.ts`'s `pointForRect` composes the frame offset and the empirical scale before it
  * hands a rect back), so one arithmetic serves a rect measured from a parent DOM element and a rect
  * measured inside a canvas iframe alike.
+ *
+ * **The viewport is the box that SCROLLS, not the stage.** Edit docks the Document Header card
+ * above its scroller, inside the same stage cell, so there the stage is the band plus the page and
+ * its centre is half a band too high: a reveal would land the node that far above the middle of
+ * what the author can actually see. {@link revealScroller} is that box wherever there is one, and
+ * where there is none (Design, Stylebook, a comparison) the stage is still the viewport.
  */
 function centeringOffset(surface: CanvasSurface, rect: { top: number; height: number }): number {
-  const wrapRect = rectOf(surface.wrap);
-  const elCenterY = rect.top + rect.height / 2 - wrapRect.top;
-  return wrapRect.height / 2 - elCenterY;
+  const viewport = rectOf(revealScroller(surface) ?? surface.wrap);
+  const elCenterY = rect.top + rect.height / 2 - viewport.top;
+  return viewport.height / 2 - elCenterY;
 }
 
 /**
@@ -789,7 +795,7 @@ export type CanvasMode = (typeof CANVAS_MODES)[number];
 /** The base modes the preview flag composes with — the two the Canvas view axis shows it beside. */
 const PREVIEWABLE_BASE_MODES = new Set(["edit", "design"]);
 
-// ─── §4.2 axis 2 — the Canvas view ───────────────────────────────────────────
+// ─── The Canvas view (§4.2) ──────────────────────────────────────────────────
 // `Edit │ Design` is a radio and `Preview` is a TOGGLE beside it, because that is what the storage
 // Has always been: `preview` is not a base mode, it is a flag that composes with one.
 //
@@ -826,8 +832,9 @@ interface ViewableTab {
 /**
  * The views this document supports, in axis order — the control's entries.
  *
- * Filtered by `capabilities.modes` for the same reason the editor-kind dropdown is (§4.2): a
- * permanently dead segment is a question the app refuses to answer.
+ * Filtered by `capabilities.modes` for the same reason the Editor control is (the pane context bar,
+ * `docs/studio/interface/tabs.md`): a permanently dead segment is a question the app refuses to
+ * answer.
  */
 export function canvasViewsFor(tab: ViewableTab): CanvasView[] {
   return CANVAS_VIEWS.filter((value) => tab.capabilities.modes.includes(value));
@@ -937,16 +944,16 @@ const PANZOOM_MODES = new Set(["design", "stylebook", "git-diff"]);
 
 const documentOpen = (ctx: { document: { open: boolean } }) => ctx.document.open;
 
-/** The three values `session.ui.previewColorScheme` may hold (spec §9.5). */
+/** The three values `session.ui.previewColorScheme` may hold (spec.md §9.5). */
 const COLOR_SCHEMES = ["auto", "light", "dark"] as const;
 
 /**
  * The canvas view verbs — `setMode`, `setZoom`, `setEditZoom`.
  *
- * **These are the setters that retire `canvas.togglePreview`** (plan §13.3 clause 3). A toggle
- * cannot say which state it ends in, so six screenshots taken through it photographed whichever way
- * the default happened to point that week; `canvas.setMode { mode: "preview" }` means the same
- * thing twice in a row and from any starting state.
+ * **These are the setters that retire `canvas.togglePreview`** (the idempotence rule, §13.5). A
+ * toggle cannot say which state it ends in, so six screenshots taken through it photographed
+ * whichever way the default happened to point that week; `canvas.setMode { mode: "preview" }` means
+ * the same thing twice in a row and from any starting state.
  *
  * Three refusals, each a wrong picture that used to be accepted silently:
  *
@@ -1025,13 +1032,14 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       requires: "an open document",
       when: documentOpen,
       /*
-       * Projected, and it was deleted once under §12.4's first rule (chrome). The rule is about a
-       * verb whose WHOLE effect is what the person is looking at, and this one's is not: the tree
-       * tools are gated on `editor.kind`, which is derived from the mode (`editorKindForMode`), so
-       * a document the person left in Code — or the model itself moved — refuses every tree write
-       * with "requires an open document whose element tree the canvas is editing", and without this
-       * verb the model had no way back to a state it can read. `run` acts on the active tab and
-       * the model reads the result: `after.editor.kind` is the same fact the gate reads.
+       * Projected, and it was deleted once under studio-ui-guidelines.md §12.4's first rule
+       * (chrome). The rule is about a verb whose WHOLE effect is what the person is looking at, and
+       * this one's is not: the tree tools are gated on `editor.kind`, which is derived from the
+       * mode (`editorKindForMode`), so a document the person left in Code — or the model itself
+       * moved — refuses every tree write with "requires an open document whose element tree the
+       * canvas is editing", and without this verb the model had no way back to a state it can
+       * read. `run` acts on the active tab and the model reads the result: `after.editor.kind` is
+       * the same fact the gate reads.
        */
       aiTool: {
         description:
@@ -1210,7 +1218,7 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       title: "Set Edit Width",
     },
     /*
-     * ── The rendering context (§4.2's control ③) ──────────────────────────────────────────────
+     * ── The rendering context (§6.2) ──────────────────────────────────────────────────────────
      *
      * Three setters for the three axes the Context popover offers. The popover wrote
      * `session.ui.activeMedia` / `previewColorScheme` / `showLayout` through `updateUi` directly, so
@@ -1218,11 +1226,11 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
      * assistant, and not bindable — in a design whose first principle is that a capability exists
      * as a `Command` record and every surface projects it.
      *
-     * SETTERS, not cycles. §5.3's keymap declares `⌘⌥↑`/`⌘⌥↓` and `⌘⌥⇧S` to cycle the size and
-     * scheme axes, and a chord carries no argument, so those chords need `next`/`prev` records of
-     * their own — a delta each, which is what §13's R1 forbids a screenshot from naming. Naming the
-     * state you end in works from every surface; the chords are a separate decision and are not
-     * made here.
+     * SETTERS, not cycles. The cycle chords once proposed for the size and scheme axes
+     * (`⌘⌥↑`/`⌘⌥↓`, `⌘⌥⇧S`) carry no argument, so they would need `next`/`prev` records of their
+     * own — a delta each, which the shot contract's R1 (`scripts/screenshots/README.md`) forbids a
+     * screenshot from naming. Naming the state you end in works from every surface; the chords are
+     * a separate decision and are not made here (§6.2).
      */
     {
       args: {
@@ -1302,12 +1310,13 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
      * The language a pane RENDERS AS — and only that.
      *
      * Jx has no message catalogue: a translation is a different file in a different directory
-     * (site-architecture §13.3), so "show this page in French" is a navigation and the locale
+     * (site-architecture.md §13.3), so "show this page in French" is a navigation and the locale
      * preset owns it. What is left over is genuinely a rendering context, and it is the half of
-     * §13.4 the canvas can show today: the artboard root's `lang` and `dir`. That is why this is a
-     * verb and not a label — an RTL locale mirrors the layout on screen. (§13.4's other half,
-     * `$page.locale` in the rendered state, is injected by the compiler and not by the canvas's
-     * `substitutePreviewParams`; previewing it is a separate change to the render path.)
+     * site-architecture.md §13.4 the canvas can show today: the artboard root's `lang` and `dir`.
+     * That is why this is a verb and not a label — an RTL locale mirrors the layout on screen.
+     * (That section's other half, `$page.locale` in the rendered state, is injected by the
+     * compiler and not by the canvas's `substitutePreviewParams`; previewing it is a separate
+     * change to the render path.)
      *
      * It lives in this file rather than in `i18n/i18n-commands.ts` because `contextTab`, `paneArg`
      * and `repaint` are local closures here, and every rendering-context verb needs all three: the
@@ -1514,9 +1523,10 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       when: documentOpen,
       /*
        * The route params and component test props live in a popover now, and a transient surface
-       * opens by COMMAND rather than by clicking (plan §13.2) — otherwise the one shot that types a
-       * test value would need a CSS selector to reach it, which §13's contract forbids outright.
-       * The pointer and the camera use the same door.
+       * opens by COMMAND rather than by clicking (§6.2) — otherwise the one shot that types a test
+       * value would need a CSS selector to reach it, which the shot contract
+       * (`scripts/screenshots/README.md`) forbids outright. The pointer and the camera use the same
+       * door.
        */
       run: (_commandCtx, args) => {
         // Resolve the tab first, so a pane with no document refuses before anything opens.

package/src/canvas/diff-toolbar.ts

@@ -79,9 +79,27 @@ export function setDiffRepaint(repaint: (paneId: string) => void): void {
   _repaint = repaint;
 }
 
+/**
+ * How this module asks the pane CHROME to redraw, injected by `studio.ts`.
+ *
+ * The zoom pod is not drawn over the Code half (`panels/pane-context.ts`, `podFor`), and the half
+ * lives in `diff-view.ts`, which is deliberately not reactive — so nothing would tell the pod the
+ * half had changed, and it would go on floating over Monaco until something unrelated repainted the
+ * bar. Injected rather than imported for {@link setDiffRepaint}'s reason: the chrome module is far
+ * outside this one's graph, and `studio.ts` is the one place that already holds both. Null until
+ * then, which is only ever a test that drives the toolbar without the shell.
+ */
+let _chromeRepaint: (() => void) | null = null;
+
+/** Register the chrome repaint. Called once, from `studio.ts`. */
+export function setDiffChromeRepaint(repaint: () => void): void {
+  _chromeRepaint = 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.
+ * styling: one draws two artboards on a pan/zoom surface, the other one Monaco. And redraw the
+ * pane's chrome after it, because whether the zoom pod is drawn at all depends on the half.
  *
  * `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
@@ -90,6 +108,7 @@ export function setDiffRepaint(repaint: (paneId: string) => void): void {
 function repaintDiffStage(paneId: string): void {
   surfaceForPane(paneId).prevCanvasMode = null;
   _repaint(paneId);
+  _chromeRepaint?.();
 }
 
 /** Redraw one pane's toolbar in place, without touching its artboards. */
@@ -332,7 +351,7 @@ export function diffCommands(): AnyCommand[] {
       title: "Set Diff View",
       undo: "none",
       when: (ctx) => ctx.editor.kind === "diff",
-      /* No `aiTool`, by §12.4's first deletion rule: chrome. */
+      /* No `aiTool`, by studio-ui-guidelines.md §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.

package/src/canvas/diff-view.ts

@@ -3,10 +3,11 @@
  *
  * **The store is a module-local `Map` keyed by pane**, the shape `_editWidths` in `edit-width.ts`
  * and `_fits` in `canvas-utils.ts` already use. The value is transient — it is rebuilt by the
- * render pass that computes the comparison — and its only readers are that pass, the stepper and
- * the diff header, so a field on `CanvasSurface` would buy nothing and a field on `shell` would be
- * an app-level slot for a per-pane fact, which is exactly the defect the Diff LENS was built to
- * avoid (`workspace/pane-derive.ts`, finding 4: one app-level `diffState` meant two panes drew one
+ * render pass that computes the comparison — and its only readers are that pass, the stepper, the
+ * diff header and the zoom pod (which asks only which half is showing), so a field on
+ * `CanvasSurface` would buy nothing and a field on `shell` would be an app-level slot for a
+ * per-pane fact, which is exactly the defect the Diff LENS was built to avoid
+ * (`workspace/pane-derive.ts`, finding 4: one app-level `diffState` meant two panes drew one
  * comparison).
  *
  * **Keyed by PANE, because two panes can compare two different files at once** — the Source Control
@@ -14,8 +15,8 @@
  * source tab's `session.ui`. `canvasModeOfPane` and `derivationOfPane` are keyed the same way for
  * the same reason.
  *
- * **This file is a LEAF.** It imports one type and nothing else, so the render pass, the stepper
- * and the header can all reach it without any of them reaching each other.
+ * **This file is a LEAF.** It imports one type and nothing else, so the render pass, the stepper,
+ * the header and the pane chrome can all reach it without any of them reaching each other.
  */
 
 import type { ChangeMap } from "./diff-marks";
@@ -102,11 +103,34 @@ export function diffViewOf(paneId: string): DiffView {
   return _records.get(paneId)?.view ?? "visual";
 }
 
+/**
+ * Whether this pane draws its comparison as TEXT: the file has no visual half, or the author chose
+ * Code.
+ *
+ * One definition, because three callers must never disagree about it. `canvas-render.ts`'s branch
+ * chooses which half to build and its mount's post-await guard re-asks whether that half is still
+ * wanted; they were two spellings — the branch said "not renderable OR the author chose Code", the
+ * guard said only "the author chose Code" — so for a file with no visual half the branch built the
+ * Code container and the guard then refused to mount into it. An empty stage, no error, and a
+ * toolbar correctly describing an editor that was never there. The third is the zoom pod
+ * (`panels/pane-context.ts`), which is not drawn over the Code half: nothing there zooms, and it
+ * sat on Monaco's own scrollbar.
+ *
+ * **Renderability is an ARGUMENT** — `canRenderComparison(path)` from `panels/git-diff-open.ts` —
+ * so this file stays the leaf its header promises. Taking the path would have pulled the opener
+ * (and the media pane behind it) into everything that reads a pane's review state.
+ */
+export function diffShowsCode(paneId: string, renderable: boolean): boolean {
+  return !renderable || diffViewOf(paneId) === "code";
+}
+
 /**
  * Show the visual comparison or the code one.
  *
  * The caller pairs this with a repaint: the store is deliberately not reactive (its writers are a
  * render pass and a toolbar click, both of which already know to redraw), so nothing observes it.
+ * That repaint is the stage AND the pane chrome, because the zoom pod reads this through
+ * {@link diffShowsCode} — see `repaintDiffStage` in `diff-toolbar.ts`.
  */
 export function setDiffView(paneId: string, view: DiffView): void {
   recordFor(paneId).view = view;

package/src/canvas/iframe-entry.ts

@@ -209,7 +209,7 @@ export function patchDisturbsActiveEdit(forwardOps: JxDocOp[]): boolean {
   return false;
 }
 
-/** Consecutive quiet animation frames before the frame declares itself settled (§13.4). */
+/** Consecutive quiet animation frames before the frame declares itself settled (§13.5). */
 export const IDLE_QUIET_FRAMES = 2;
 
 /**
@@ -466,7 +466,7 @@ export function startCanvasIframe(opts: {
   const heightObserver = ResizeObs ? new ResizeObs(() => postContentHeight()) : null;
 
   // ─── Cross-realm quiescence ─────────────────────────────────────────────────
-  // The frame answers "have I settled?" instead of being polled (§13.4 condition 5). Nothing in the
+  // The frame answers "have I settled?" instead of being polled (§13.5). Nothing in the
   // Parent realm can look inside a cross-origin frame, so the alternative was `wait: {ms}` — and 115
   // Of those were 115 places a slow subsystem got answered with +500 ms and the wrong picture was
   // Accepted. Sampling lives HERE, next to the render that changes the answer.

package/src/canvas/iframe-host.ts

@@ -203,7 +203,7 @@ interface HostState {
    * The frame's own last quiescence report (`{kind: "idle"}`), or null before the first one.
    *
    * Held PER HOST from the start. `shot.ts`'s "Studio's only child frame" is a coin flip the moment
-   * P8 adds a second pane, and a global would have to be unpicked exactly then.
+   * a second pane exists, and a global would have to be unpicked exactly then.
    */
   idle: Omit<Extract<IframeToParent, { kind: "idle" }>, "kind"> | null;
   /**
@@ -607,7 +607,7 @@ function hostLabel(host: HostState): string {
  * Empty means every live frame's DOM reflects what this host told it, its fonts have loaded, no
  * animation is running and no image retry is in flight. Naming the blockers is the whole point:
  * `probe.idle()` rejects with this list, so a slow subsystem identifies itself instead of being
- * answered with `+500 ms` and a wrong capture (plan §13.4).
+ * answered with `+500 ms` and a wrong capture ("Determinism", `scripts/screenshots/README.md`).
  */
 export function canvasIdleBlockers(): string[] {
   const blockers: string[] = [];
@@ -660,8 +660,8 @@ export function canvasIdleBlockers(): string[] {
  *
  * The caller gets a point it can act on directly — click it, scroll to it, anchor a popover to it —
  * without knowing that a canvas iframe, a panzoom transform and an edit-zoom scale sit between the
- * document and the screen. P4.6's find-references jump, P8.4's jump bar and collab follow-peer all
- * want exactly this, and so does anything driving Studio from outside.
+ * document and the screen. The find-references jump, the jump bar and collab follow-peer all want
+ * exactly this, and so does anything driving Studio from outside.
  */
 export interface CanvasPoint {
   x: number;
@@ -1551,7 +1551,7 @@ function requestPresence(host: HostState): void {
     if (!structuralSelection || peer.state.focusedPath !== tab?.documentPath) {
       continue;
     }
-    // A peer publishes their whole selection SET (§6.5). Every path gets its own box under the
+    // A peer publishes their whole selection SET (§6.7). Every path gets its own box under the
     // Same name and colour — the meta map is keyed by path, so a peer selecting six nodes draws
     // Six boxes and a peer selecting one draws exactly the one box it always did.
     for (const path of structuralSelection) {

package/src/canvas/iframe-interaction.ts

@@ -294,9 +294,9 @@ export function startInteraction(
     }
     const hit = nearestHit(e.target);
     if (hit) {
-      // Ctrl/Cmd is the accumulate gesture (§6.5). The iframe reports the modifier and nothing
-      // Else — it holds no selection state, so what a modified click MEANS is the parent's to
-      // Decide, exactly as the unmodified click already was.
+      // Ctrl/Cmd is the accumulate gesture (studio-ui-guidelines.md §8.1). The iframe reports the
+      // Modifier and nothing else — it holds no selection state, so what a modified click MEANS is
+      // The parent's to decide, exactly as the unmodified click already was.
       const mouse = e as MouseEvent;
       channel.post({
         additive: mouse.ctrlKey === true || mouse.metaKey === true,
@@ -427,9 +427,10 @@ export function startInteraction(
      *
      * This called `preventDefault()` before looking, "legacy parity" with a handler that did the
      * same. The parent then posts `path: null`, `showContextMenu` returns early on it, and the
-     * result is a right-click that suppresses the browser menu and shows nothing in its place:
-     * plan §10's dead zone, named there as the thing to fix. The margin around the artboard is
-     * exactly where a reader reaches for View Source or Inspect.
+     * result is a right-click that suppresses the browser menu and shows nothing in its place, a
+     * dead zone where the docs promise the browser's own menu
+     * (`docs/studio/interface/canvas.md#the-right-click-context-menu`). The margin around the
+     * artboard is exactly where a reader reaches for View Source or Inspect.
      */
     if (!hit) {
       return;

package/src/canvas/iframe-overlay.ts

@@ -71,7 +71,7 @@ export interface OverlayLayer {
    */
   setPresence: (items: { placement: OverlayPlacement; color: string; label: string }[]) => void;
   /**
-   * Draw the NON-primary members of a multi-selection (§6.5). Replaces the whole set each call;
+   * Draw the NON-primary members of a multi-selection (§6.7). Replaces the whole set each call;
    * pass [] to clear, which is what a selection of one always does — one selected node draws the
    * selection box and nothing else, exactly as it did before the selection became a list.
    */

package/src/canvas/iframe-protocol.ts

@@ -122,7 +122,7 @@ export type ParentToIframe =
       assets?: AssetContext | null;
       mapperCtx: WireMapperCtx;
       siteStyle: Record<string, unknown> | null;
-      // Forced color-scheme preview (spec §9.5): "light"/"dark" sets data-color-scheme on the
+      // Forced color-scheme preview (spec.md §9.5): "light"/"dark" sets data-color-scheme on the
       // Iframe root, null clears it (auto — follow the OS).
       colorScheme: "light" | "dark" | null;
       /**
@@ -478,13 +478,13 @@ export type IframeToParent =
   // Not the parent, now resolves the scope). `gen` lets the parent drop a snapshot from a superseded
   // Render. Posted right after `renderComplete`; values are JSON-safe deep clones (see serialize-scope).
   | { kind: "dataScope"; gen: number; scope: Record<string, unknown> }
-  // The frame's own quiescence, ANSWERED rather than polled (spec §13.5, plan §13.4 condition 5).
+  // The frame's own quiescence, ANSWERED rather than polled (studio.md §13.5).
   // Nothing in the parent realm can see inside a cross-origin frame, so a parent that wanted to
   // Know whether the canvas had settled could only sleep. The frame samples itself at its own rAF
   // And posts whenever the tuple changes, ending with the quiet one; the host holds the latest.
   //
   // `fonts` is `document.fonts.status === "loaded"` and is NOT sufficient alone — in a blank canvas
-  // Frame it reports "loaded" against an EMPTY font set (measured in S0: `hero` drifted 0.150 RMSE
+  // Frame it reports "loaded" against an EMPTY font set (measured: `hero` drifted 0.150 RMSE
   // Because the first capture measured fallback metrics while Plus Jakarta Sans was still in
   // Flight). It is honest only together with `gen` (a frame that has not acked a render has not
   // Loaded its fonts either) and the runner's per-frame network count.
@@ -496,8 +496,9 @@ export type IframeToParent =
   // Pending retry is the one image fact only the app knows.
   | { kind: "idle"; gen: number; fonts: boolean; animations: number; images: number }
   // `additive` is Ctrl/Cmd being held at the moment of the click — the ACCUMULATE gesture, which
-  // The parent turns into a toggle against `session.selection` (studio §6.5). Absent/false is a
-  // Plain replace, which is what every canvas click was before the selection became a set.
+  // The parent turns into a toggle against `session.selection` (studio-ui-guidelines.md §8.1).
+  // Absent/false is a plain replace, which is what every canvas click was before the selection
+  // Became a set.
   | { kind: "hit"; hit: NodeHit; additive?: boolean }
   // A click on layout chrome (see {@link LayoutHit}). Distinct from `hit` because the target is not
   // In the page document at all: the parent adopts it as `view.layoutSelection` (which shows the

package/src/canvas/iframe-render.ts

@@ -573,7 +573,7 @@ export function syncEditableRoot(container: HTMLElement, mode: CanvasMode): void
    * infer it from.
    *
    * Scoped deliberately: this describes the editing REGION. Per-block landmarks and a
-   * keyboard-reachable block action bar are still missing (see specs/studio.md §4.5).
+   * keyboard-reachable block action bar are still missing (see specs/studio.md §4.4).
    */
   container.setAttribute("role", "textbox");
   container.setAttribute("aria-multiline", "true");
@@ -693,7 +693,7 @@ export function syncStylebookCss(doc: Document, mode: CanvasMode): void {
  * Apply the project's site style as a real stylesheet (replace-in-place): custom properties on
  * `:root`, plain properties on `body`, conditional blocks dual-emitted per the forced-scheme
  * contract. A stylesheet — not inline root properties — so `:root[data-color-scheme]` override
- * selectors can win (spec §9.5), and so removed tokens can't linger on reused iframes.
+ * selectors can win (spec.md §9.5), and so removed tokens can't linger on reused iframes.
  */
 export function applySiteStyle(
   siteStyle: Record<string, unknown> | null | undefined,
@@ -719,7 +719,7 @@ export function applySiteStyle(
 
 /**
  * Force or clear the color-scheme preview on the iframe's root element (the platform's
- * data-color-scheme contract, spec §9.5). Survives re-renders and patches — renders only replace
+ * data-color-scheme contract, spec.md §9.5). Survives re-renders and patches — renders only replace
  * the container's children, never the root element.
  */
 export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark" | null): void {

package/src/canvas/popover-state.ts

@@ -117,7 +117,7 @@ export function ensurePopoverRevealWatch(): () => void {
       const tab = activeTab.value;
       /* TRACKED: the selection, and the document its paths resolve against. Those are what the
          rule depends on, and a selection move is the only thing that should fire it. The whole
-         SET is read joined, for the reason §6.5 gives: a bare property read would not re-trigger
+         SET is read joined, for the reason §6.7 gives: a bare property read would not re-trigger
          when the selection changes within the array. */
       void tab?.session.selection.map((path) => path.join("/")).join("|");
       void tab?.doc.document;

package/src/canvas/stage-scrollbar.ts

@@ -0,0 +1,112 @@
+/// <reference lib="dom" />
+/**
+ * Stage scrollbar — how wide the stage's own scrollbar is, published on the pane's cell.
+ *
+ * The zoom pod floats in the pane's chrome layer (`surfaces/pane-grid.json`, `[part="chrome"]`),
+ * and that layer spans the WHOLE lower cell, scrollbar gutter included. Edit's scroller is the
+ * stage document's `[part="edit-canvas"]`, which sits in the same cell with its native vertical
+ * scrollbar flush against the same edge. The pod was placed a fixed `--jx-space-4` (12px) in from
+ * that edge, and a classic scrollbar is 15px in Chromium on Linux, so the pod painted 3px into the
+ * track (more with its shadow) and swallowed clicks on it.
+ *
+ * **CSS cannot measure a scrollbar, and the pod's document cannot see the scroller.** The scroller
+ * belongs to `surfaces/canvas-stage.json`; the pod to `surfaces/pane-context.json`. So the
+ * renderer, which is the one module that knows which element scrolls in which mode, hands the
+ * scroller here, and this module writes its width onto the cell as {@link STAGE_SCROLLBAR_VAR}. The
+ * pod's margin adds it by cascade. It is the seam `--jump-bar-h` and `--pane-context-h` already
+ * use, run the other way: there each bar owns its answer and the stage reads it; here the stage
+ * owns its scroller and the chrome reads the answer.
+ *
+ * **On the CELL, never on `:root`**, for the reason `panels/jump-bar.ts` gives at the same seam:
+ * two panes have two stages, and one document-level number would push the other pane's pod in by a
+ * scrollbar it does not have. A stage outside any cell writes the root, which only happens in a
+ * test fixture.
+ *
+ * **Edit only, and 0 everywhere else by construction.** `canvas-render.ts` tracks the scroller from
+ * the Edit branch and releases it at every teardown (a mode transition, a full reset, the pane's
+ * own teardown), and a release writes `0px`. Design, Stylebook and a comparison clip their stage
+ * rather than scroll it, so the pod goes back to its plain inset there.
+ *
+ * The observer writes a custom property on the cell. That moves the pod, which is in the chrome
+ * layer, and never the observed scroller, so there is no resize loop.
+ */
+
+import { PANE_SELECTOR } from "../surfaces/pane-grid";
+import type { CanvasSurface } from "./surface-registry";
+
+/**
+ * The custom property the cell carries: the stage scroller's scrollbar width, in px.
+ *
+ * `surfaces/pane-context.json`'s `[part="pod"]` margin reads it, and
+ * `tests/stage-scrollbar.test.ts` joins the two names so renaming either side goes red.
+ */
+export const STAGE_SCROLLBAR_VAR = "--stage-scrollbar-w";
+
+/**
+ * How much of `scroller`'s width its vertical scrollbar takes.
+ *
+ * `offsetWidth` is the border box and `clientWidth` the padding box minus the scrollbar, so the
+ * difference is exactly the scrollbar for a box that draws no border — which `[part="edit-canvas"]`
+ * does not (`surfaces/canvas-stage.json`). Give it one and this would count the border too.
+ *
+ * An OVERLAY scrollbar (macOS, GTK's overlay mode) reserves no width and correctly answers 0, so
+ * those platforms keep the pod at its plain inset. So does a DOM with no layout engine.
+ *
+ * @param {HTMLElement} scroller
+ * @returns {number}
+ */
+export function scrollbarWidthOf(scroller: HTMLElement): number {
+  return Math.max(0, scroller.offsetWidth - scroller.clientWidth);
+}
+
+/** The cell a stage belongs to, or the document root when it is outside every cell. */
+function cellOf(surface: CanvasSurface): HTMLElement {
+  return surface.wrap?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
+}
+
+/**
+ * Publish `scroller`'s scrollbar width on this stage's cell, and keep it current.
+ *
+ * **Observed, not measured once.** The scroller's content box shrinks when a scrollbar appears and
+ * grows when it goes, so one `ResizeObserver` hears the page growing past the pane and shrinking
+ * back as well as every window, dock and split resize.
+ *
+ * **Idempotent for the scroller it already holds**, because Edit's `.then` runs on every
+ * content-only repaint and the stage document keeps its scroller across them: re-observing it each
+ * time would churn an observer for nothing. A DIFFERENT scroller (the stage changed hands) releases
+ * the old one first, and `null` only releases.
+ *
+ * @param {CanvasSurface} surface
+ * @param {HTMLElement | null} scroller The element that scrolls this stage, or null for none.
+ */
+export function trackStageScrollbar(surface: CanvasSurface, scroller: HTMLElement | null): void {
+  if (surface.stageScrollbar?.scroller === scroller) {
+    return;
+  }
+  releaseStageScrollbar(surface);
+  if (!scroller) {
+    return;
+  }
+  const cell = cellOf(surface);
+  const write = () => {
+    cell.style.setProperty(STAGE_SCROLLBAR_VAR, `${scrollbarWidthOf(scroller)}px`);
+  };
+  const observer = new ResizeObserver(write);
+  observer.observe(scroller);
+  surface.stageScrollbar = { observer, scroller };
+  write();
+}
+
+/**
+ * Stop observing this stage's scroller and put the cell's offset back to 0. Idempotent.
+ *
+ * Safe while the surface has no host yet, because a surface is addressable before its stage exists
+ * and the teardown paths run for it all the same.
+ *
+ * @param {CanvasSurface} surface
+ */
+export function releaseStageScrollbar(surface: CanvasSurface): void {
+  surface.stageScrollbar?.observer.disconnect();
+  surface.stageScrollbar = null;
+  cellOf(surface).style.setProperty(STAGE_SCROLLBAR_VAR, "0px");
+}

package/src/canvas/surface-registry.ts

@@ -2,8 +2,8 @@
 /**
  * The surface REGISTRY — one stage record per pane, and nothing that knows what a pane contains.
  *
- * A pane is the unit of split, focus and zoom (§4.1), so it is also the unit of RENDER. The panels
- * a pass mounted, the host element they mounted into, the mode that pass was drawn in and the full
+ * A pane is the unit of split, focus and zoom (§18), so it is also the unit of RENDER. The panels a
+ * pass mounted, the host element they mounted into, the mode that pass was drawn in and the full
  * render a failed patch escalates to are all facts about ONE pane; they were app-level singletons
  * only because the shell had a single stage.
  *
@@ -67,6 +67,12 @@ export interface CanvasSurface {
   stage: CanvasStageHandle | null;
   /** The observer that re-centres this stage until the author pans it. One per stage. */
   centerObserver: ResizeObserver | null;
+  /**
+   * The observer publishing this stage's scroller's scrollbar width to its cell, and the scroller
+   * it watches. Edit only: it is the one mode whose stage scrolls under the zoom pod. See
+   * `canvas/stage-scrollbar.ts`.
+   */
+  stageScrollbar: { observer: ResizeObserver; scroller: HTMLElement } | null;
   /** Whether this stage still wants re-centring — cleared by the first deliberate pan. */
   needsCenter: boolean;
   panX: number;
@@ -164,6 +170,7 @@ function freshSurface(paneId: string): CanvasSurface {
     prevStylebookFilter: null,
     renderGeneration: 0,
     sourceCollabCleanup: null,
+    stageScrollbar: null,
     wrap: null as unknown as HTMLElement,
   };
 }

package/src/collab/collab-commands.ts

@@ -1,14 +1,15 @@
 /**
- * The `Collaborate:` command family — the entry point and the exit co-editing has never had (§7.4).
+ * The `Collaborate:` command family — the entry point and the exit co-editing has never had
+ * (collab.md §4).
  *
  * Collaboration in Studio has been a thing that HAPPENS to a document: a session attaches because
  * the platform said the file was shared, presence chips appear in the toolbar, and there is no verb
  * anywhere in the app for starting it, inviting anybody, following someone, or stopping. The
- * palette had no `Collaborate:` rows at all, and `CATEGORIES` has carried the name since P2 with
- * nothing filed under it.
+ * palette had no `Collaborate:` rows at all, and `CATEGORIES` has carried the name since the
+ * command registry landed with nothing filed under it.
  *
- * Five records, each registered here — in the module that owns the machinery, per P2's rule — and
- * composed by `commands/app-commands.ts`. Every one is idempotent or refuses with a `requires`
+ * Five records, each registered here — in the module that owns the machinery, as §13.1 requires —
+ * and composed by `commands/app-commands.ts`. Every one is idempotent or refuses with a `requires`
  * sentence, and none of them is a `toggle*` without a `set*` beside it: `collab.setEnabled` is the
  * setter, `collab.stop` is the same setter's `false` and exists because "stop sharing" is what a
  * person actually looks for in a palette.
@@ -216,7 +217,8 @@ export function collabCommands(): AnyCommand[] {
         }
         const state = collabState(active);
         /* This is the honesty command: every one of these states used to be either invisible or
-           spelled "detached", and the freeze in particular looked exactly like a bug (§7.4). */
+           spelled "detached", and the freeze in particular looked exactly like a bug
+           (collab.md §4). */
         const lines = [
           `Status: ${state.status}${state.attachError ? ` — ${state.attachError}` : ""}`,
           `People here: ${state.peers.length === 0 ? "just you" : state.peers.map((p) => p.state.user.login).join(", ")}`,