@jxsuite/studio 2.0.0 → 2.1.0

package/src/canvas/iframe-protocol.ts

@@ -46,6 +46,22 @@ export interface WireMapperCtx {
   arrayPaths: string[];
 }
 
+/**
+ * One live binding, as the frame needs to know it: the chord and the scope that holds it.
+ *
+ * Scopes are carried rather than flattened because the frame picks its own stack per keystroke —
+ * `caret` when an inline-edit session is live, `canvas` when the artboard has a selection, `global`
+ * under both — which is the same ladder `commands/context.ts`'s `keyScopeStack` walks host-side.
+ * Flattening to "chords the parent wants" would lose exactly the distinction that lets ⌘C reach the
+ * browser mid-sentence and the structural copy verb at every other moment.
+ *
+ * The command ID is deliberately absent: the frame decides whether to FORWARD, never what runs.
+ */
+export interface SyncedChord {
+  chord: string;
+  scope: "caret" | "canvas" | "global";
+}
+
 /** Messages the editor (parent) sends into the canvas iframe. */
 export type ParentToIframe =
   | { kind: "init"; gen: number }
@@ -82,6 +98,53 @@ export type ParentToIframe =
   // Flip the forced color-scheme preview on the iframe root without re-rendering — a document-level
   // Idempotent attribute write, deliberately gen-less (like endEdit).
   | { kind: "setColorScheme"; scheme: "light" | "dark" | null }
+  /**
+   * Set the language the artboard is drawn in — `lang` and `dir` on the frame's document element.
+   *
+   * Render-free and gen-less, like `setColorScheme` above, because it changes no content: Jx has no
+   * message catalogue, so the TEXT is whatever file is open and only the direction, the font stack
+   * and CSS's own `:lang()` selectors move. `dir` travels with the tag rather than being derived in
+   * the frame — `localeDirection` is CLDR's answer via `Intl.Locale`, and the frame has no reason
+   * to hold a second copy of the RTL script list.
+   *
+   * `null` is "the document's own language": both attributes come off, and the frame falls back to
+   * whatever the rendered document declares.
+   */
+  | { kind: "setLocale"; locale: string | null; dir: "ltr" | "rtl" }
+  /**
+   * Open the slash menu at the caret, by name rather than by typing "/".
+   *
+   * The gesture is recognised inside the frame (`canvas/iframe-inline-edit.ts`), because that is
+   * where the keystroke is; this is the door for `insert.openSlashMenu` — the palette, a rebound
+   * chord, the automation runner and the assistant. The frame opens it UNANCHORED: there is no "/"
+   * in the document, so the menu carries its own filter field and selecting a block deletes
+   * nothing.
+   *
+   * Gen-less and render-free, like `setColorScheme` above. A frame with no caret session ignores
+   * it, which is the same refusal the record's `requires` sentence states.
+   */
+  | { kind: "openSlash" }
+  /**
+   * The chord table, so the frame forwards exactly what the host's registry binds.
+   *
+   * The frame used to answer "does the parent want this keystroke?" from three hand-written lists —
+   * eight bare keys, four "the editor owns these" chords, three "the browser owns these" chords —
+   * maintained beside a registry that already knew the answer. They disagreed in both directions:
+   * ⌘A was forwarded and `preventDefault`ed by a frame that assumed the host would claim it (no
+   * record binds it, so select-all did nothing AND the native one was suppressed), while ⌘B was
+   * withheld on the assumption the editing engine handled it (it does not — the parent's
+   * block-level keydown listener never fires against a container-level editing host, and
+   * `canvas/editable-actions.ts` rejects the browser's own `formatBold`), so Bold in the canvas did
+   * nothing at all.
+   *
+   * Idempotent and render-free, like `setColorScheme` above, and deliberately gen-less: it
+   * describes the APP, not a document. The host reposts it whenever the keymap changes, which is
+   * what makes a rebinding in Preferences take effect inside the canvas.
+   *
+   * A frame built before this message existed ignores it and keeps its own lists — which is the
+   * compatibility story `dist/iframe-entry.js` shipping prebuilt requires.
+   */
+  | { kind: "keymap"; mac: boolean; chords: readonly SyncedChord[] }
   // Replace the injected site-style sheet in place (live design-token editing) — idempotent and
   // Render-free; the superseding render carries the same style via its own siteStyle.
   | {
@@ -240,6 +303,29 @@ export interface DropPreview {
   edge: "top" | "bottom" | "inside";
 }
 
+/**
+ * A click that landed on LAYOUT chrome — a header, a footer, anything the layout file contributes
+ * that is not the page's own content. Such a node has no page-document path, so it can never be a
+ * {@link NodeHit}; it is addressed by the layout FILE it came from plus its path inside that file.
+ *
+ * This is the message that makes the first click a new author makes do something. On a default
+ * project the two most conspicuous strings on the page ("My Site", "Built with Jx") both come from
+ * `layouts/base.json`, and before this existed clicking either one selected nothing, hovered
+ * nothing and posted nothing.
+ */
+export interface LayoutHit {
+  /** Project-relative path of the layout document, e.g. `layouts/base.json`. */
+  layoutFile: string;
+  /** The clicked node's path WITHIN that layout document (what to select once it is open). */
+  layoutPath: (string | number)[];
+  /** The rendered tag, for the panel's `<header>` label. */
+  tagName: string;
+  /** The rendered class list, shown read-only in the panel. */
+  className: string;
+  /** The node's box, in iframe-viewport coords (same convention as {@link NodeHit}). */
+  rect: SerializableRect;
+}
+
 /** A document path plus the iframe-space rect of the node it resolves to. */
 export interface NodeHit {
   path: (string | number)[];
@@ -308,7 +394,31 @@ 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> }
-  | { kind: "hit"; hit: NodeHit }
+  // The frame's own quiescence, ANSWERED rather than polled (spec §13.5, plan §13.4 condition 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
+  // 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.
+  //
+  // `images` counts images whose load FAILED and whose retry (`installCanvasImageRetry`, re-firing
+  // At 150/300/450 ms) has not resolved. Deliberately NOT "images not yet complete": blocking on
+  // `img.complete` failed 8 of 61 shots — the design canvas renders unresolved bindings as literal
+  // Srcs, several starters ship a 404 favicon, and lazy images below the fold never complete. A
+  // 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.
+  | { 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
+  // Read-only layout panel with its "Open Layout →" action) rather than as a document selection.
+  | { kind: "layoutHit"; hit: LayoutHit }
   | { kind: "hover"; hit: NodeHit | null }
   // Candidate insertion "+" zones for the hovered node, recomputed on pointermove (cross-origin
   // Cousin of the legacy insertion-helper). `null` clears the "+" (cursor mid-element / left the
@@ -417,7 +527,17 @@ export type IframeToParent =
   // The engine (in the iframe) detected "/" in a live edit session; the parent shows the real
   // Lit/Spectrum menu. Re-posted with a new `filter` as the author keeps typing (the engine's
   // UpdateSlashMenu drives it). `rect` is the edited element's bbox in IFRAME-VIEWPORT coords.
-  | { kind: "slashShow"; rect: SerializableRect; filter: string }
+  /**
+   * Show the parent's slash menu at this rect.
+   *
+   * `showFilter` is what an UNANCHORED menu needs — one opened by `insert.openSlashMenu` rather
+   * than by typing "/". There is no "/…" run in the document to narrow the list with, so the menu
+   * has to carry its own field or the only way past fifteen blocks is scrolling. It existed as a
+   * callback option INSIDE the frame and was dropped at this boundary, which is the argument for a
+   * message carrying every fact its receiver needs rather than most of them: the loss was
+   * invisible, because the menu still appeared.
+   */
+  | { kind: "slashShow"; rect: SerializableRect; filter: string; showFilter?: boolean }
   // A menu-navigation key pressed in the iframe while the parent menu is open. The iframe
   // Intercepts these four keys capture-phase (restoring the "menu captures Enter" contract) and the
   // Host drives the parent menu's key handler directly — no synthetic keydown redispatch.
@@ -430,6 +550,21 @@ export type IframeToParent =
   // Browser menu is still suppressed, legacy parity); x/y are IFRAME-VIEWPORT coords for the host
   // To convert via its empirical geometry.
   | { kind: "contextMenu"; path: (string | number)[] | null; x: number; y: number }
+  // ─── Pane focus ─────────────────────────────────────────────────────────────
+  // A pointer went down somewhere in this frame. Nothing else — no path, no coordinates, no
+  // Selection: it says only "the person is working in this pane now", which the parent realm cannot
+  // Observe for itself because a pointer event inside a cross-origin iframe is delivered in the
+  // Frame's own realm and never surfaces above it.
+  //
+  // `hit` used to be the whole seam, and it has two holes. It is not posted in PREVIEW at all — a
+  // Click there is a click on the page, never a selection — so a pane showing Preview could not be
+  // Focused by clicking the thing it is showing; and in edit/design it is only posted when the
+  // Click lands ON a `[data-jx-path]` node, so clicking an artboard's empty margin focused nothing
+  // Either. Both left the keyboard in the other pane while the person was plainly in this one.
+  //
+  // Deliberately NOT in the host's preview block-list: focusing a pane is not an edit, and it is
+  // The one thing preview must still report.
+  | { kind: "paneFocus" }
   // ─── Preview navigation ─────────────────────────────────────────────────────
   // A link was clicked in PREVIEW mode. Preview keeps anchors live (design/edit de-link them onto
   // `data-jx-href`), so the click would navigate the canvas iframe away and destroy the render —

package/src/canvas/iframe-render.ts

@@ -165,6 +165,36 @@ export const EDIT_PLACEHOLDER_CSS = `
   font-size: 13px;
   pointer-events: none;
 }
+[data-jx-layout-region] {
+  position: relative;
+  opacity: 0.5;
+  transition: opacity 120ms ease;
+}
+[data-jx-layout-region]:hover {
+  opacity: 0.85;
+  outline: 1px dashed color-mix(in srgb, #808080 55%, transparent);
+  outline-offset: -1px;
+}
+[data-jx-layout-region] [data-jx-layout-region] {
+  opacity: 1;
+}
+[data-jx-layout-region]::before {
+  content: "LAYOUT \\00B7 " attr(data-jx-layout-file);
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 2;
+  padding: 1px 5px;
+  border-radius: 0 0 3px 0;
+  background: color-mix(in srgb, #808080 78%, transparent);
+  color: #fff;
+  font: 700 9px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+  letter-spacing: 0.08em;
+  pointer-events: none;
+}
+[data-jx-layout-region] [data-jx-layout-region]::before {
+  content: none;
+}
 `;
 
 /**
@@ -187,6 +217,22 @@ export function syncEditModeCss(doc: Document, mode: CanvasMode): void {
   doc.head.append(style);
 }
 
+/**
+ * Flag the canvas document as a preview shell, so `canvas.html`'s preview rules apply.
+ *
+ * The document's default box is built for EDITING: `html, body { overflow: hidden }`, because the
+ * host grows the iframe to its content height there and the parent canvas is what pans. Preview
+ * inverts that — the frame stays at the pane's height and the document scrolls itself — and until
+ * this existed nothing turned the clipping off, so preview showed the first screenful of every page
+ * and no more. An attribute rather than an injected stylesheet: the rules it switches live beside
+ * the ones they override, which is where a reader looks for them.
+ *
+ * Called on every render because one iframe is reused across modes.
+ */
+export function syncPreviewShell(doc: Document, mode: CanvasMode): void {
+  doc.documentElement.toggleAttribute("data-jx-preview", mode === "preview");
+}
+
 /**
  * Whether a canvas mode gets a live caret. Design and edit are the interactive modes; preview must
  * look and behave like the shipped page, and stylebook specimens are not documents.
@@ -429,7 +475,10 @@ export function injectHead(doc: JxDocument): void {
   }
 }
 
-/** Build the `onNodeCreated` hook that stamps `data-jx-path` / `data-jx-layout` on rendered nodes. */
+/**
+ * Build the `onNodeCreated` hook that stamps `data-jx-path` (page content) or `data-jx-layout-path`
+ * + `data-jx-layout-file` (layout-originated nodes) on rendered nodes.
+ */
 export function makeStamper(ctx: PathMapCtx) {
   return (created: Node, path: (string | number)[], def: unknown) => {
     if (!(created instanceof HTMLElement)) {
@@ -459,7 +508,25 @@ export function makeStamper(ctx: PathMapCtx) {
     }
     const classified = classifyRenderNode(path, def, ctx);
     if (classified.kind === "layout") {
-      created.dataset.jxLayout = "";
+      // A layout node has no page-document path, but it is NOT anonymous: stamp where it came from
+      // So a click on it can select it and offer to open the layout at that node. Without this the
+      // Two most clickable strings on a brand-new project ("My Site", "Built with Jx") answered a
+      // Click with nothing at all.
+      created.dataset.jxLayoutPath = serializeJxPath(classified.layoutPath);
+      if (classified.layoutFile) {
+        created.dataset.jxLayoutFile = classified.layoutFile;
+      }
+      if (classified.chrome) {
+        // Chrome — a region of the layout that does NOT wrap the page content. Marked so the canvas
+        // Can dim and label it, and frozen so no caret can land there. The container is permanently
+        // `contenteditable`, so without this the browser happily put a caret in the site header and
+        // Then dropped every keystroke on the floor at the `beforeinput` chokepoint: the one place a
+        // New author is most likely to click looked editable and silently was not.
+        created.dataset.jxLayoutRegion = "";
+        if (isEditableMode(ctx.canvasMode)) {
+          created.contentEditable = "false";
+        }
+      }
       return;
     }
     created.dataset.jxPath = serializeJxPath(classified.path);
@@ -542,6 +609,7 @@ export async function renderResolvedDocument(opts: {
   applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
   injectHead(opts.doc);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
+  syncPreviewShell(opts.container.ownerDocument, opts.mode);
   syncStylebookCss(opts.container.ownerDocument, opts.mode);
   // Seed the runtime's root $media before buildScope so a COMPONENT with its own `@--name` blocks
   // But no own `$media` resolves the breakpoint to its real query (the iframe path calls buildScope

package/src/canvas/iframe-slash.ts

@@ -59,6 +59,12 @@ export function startIframeSlashBridge(
         filter,
         kind: "slashShow",
         rect: { height: r.height, width: r.width, x: r.left, y: r.top },
+        /* Carried, because the parent draws the menu and only the FRAME knows why it opened. A
+           menu opened by name has no "/…" run in the document to filter with, so it needs its own
+           field; the "/" gesture needs none, because the author types into the block. This option
+           was dropped at this boundary and the loss was invisible — the menu still appeared, just
+           with no way past fifteen items but scrolling. */
+        ...(cbs.showFilter === true ? { showFilter: true } : {}),
       });
     },
   };

package/src/canvas/path-mapping.ts

@@ -22,17 +22,67 @@ export interface PathMapCtx {
   arrayPaths: Set<string>;
 }
 
-/** A render node either belongs to the layout chrome (no document path) or maps to a document path. */
-export type RenderNodeClass = { kind: "layout" } | { kind: "path"; path: JxPath };
+/**
+ * The marker `markLayoutNodes` stamps on every node of a resolved layout document (see
+ * {@link file://./canvas-live-render.ts}). It names the layout FILE and the node's own path inside
+ * that file — enough for the editor to select the node, label it, and open the layout at it. It
+ * used to be a bare `true`, which is why clicking layout chrome on a fresh project selected nothing
+ * at all: the render had thrown away the only two facts needed to act on the click.
+ */
+export interface LayoutMarker {
+  /** Project-relative path of the layout document, e.g. `layouts/base.json`. */
+  file: string;
+  /** The node's path WITHIN the layout document. */
+  path: JxPath;
+}
+
+/**
+ * A render node either belongs to the layout (carrying its origin in the layout file, since it has
+ * no page-document path) or maps to a page-document path.
+ *
+ * `chrome` distinguishes the two very different kinds of layout node. Most are chrome — a header, a
+ * footer, a `<noscript>` — regions the page cannot edit in place. But the nodes on the path down to
+ * the `<slot>` (the layout root, the `<main>` around it) WRAP the page content, so they must stay
+ * transparent: dimming or freezing them would dim and freeze the whole document. Only chrome is
+ * dimmed, labelled, and made `contenteditable="false"`.
+ */
+export type RenderNodeClass =
+  | { kind: "layout"; layoutFile: string; layoutPath: JxPath; chrome: boolean }
+  | { kind: "path"; path: JxPath };
+
+/**
+ * Whether `path` is the page-content container or one of its ancestors — i.e. whether this node's
+ * subtree contains the distributed page content. `prefix` is the render path of the container whose
+ * children hold that content (`PathMapCtx.pageContentPrefix`).
+ */
+export function wrapsPageContent(path: JxPath, prefix: JxPath | null): boolean {
+  if (!prefix) {
+    return false;
+  }
+  return path.length <= prefix.length && path.every((seg, i) => prefix[i] === seg);
+}
 
 /**
  * Resolve a runtime render path to a document path (or flag it as layout-originated). Pure — the
- * caller decides whether to record the result in a WeakMap or a `data-jx-path` attribute.
+ * caller decides whether to record the result in a WeakMap or `data-jx-*` attributes.
  */
 export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx): RenderNodeClass {
-  // Layout-originated nodes have no page-document path; the caller marks them (data-jx-layout).
-  if (ctx.layoutWrapped && typeof def === "object" && (def as { $__layout?: unknown })?.$__layout) {
-    return { kind: "layout" };
+  // Layout-originated nodes have no page-document path; the caller stamps their origin instead
+  // (data-jx-layout-path / data-jx-layout-file).
+  const marker =
+    ctx.layoutWrapped && typeof def === "object"
+      ? (def as { $__layout?: unknown } | null)?.$__layout
+      : undefined;
+  if (marker) {
+    const origin = (typeof marker === "object" ? marker : {}) as Partial<LayoutMarker>;
+    return {
+      // The root is never chrome even when the layout distributed nothing: it IS the render, and a
+      // Dimmed, frozen root would be a canvas nobody can touch.
+      chrome: path.length > 0 && !wrapsPageContent(path, ctx.pageContentPrefix),
+      kind: "layout",
+      layoutFile: typeof origin.file === "string" ? origin.file : "",
+      layoutPath: Array.isArray(origin.path) ? origin.path : [],
+    };
   }
 
   let mappedPath = path;

package/src/canvas/surface-registry.ts

@@ -0,0 +1,292 @@
+/// <reference lib="dom" />
+/**
+ * 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
+ * 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.
+ *
+ * They could not stay that way. `classifyOps` gated a patch on `canvasPanels.every(p => p.ready)`
+ * and on one `getCanvasMode()`, and `escalateToFullRender` scheduled the one global render — so the
+ * moment a second stage exists, an edit typed into one pane would be refused because the OTHER
+ * pane's canvas was still mounting, and every escalation would re-render both. That is a
+ * correctness bug, not a performance one, which is why this lands before the second host rather
+ * than with it.
+ *
+ * A surface is addressed by pane id and nothing else. `panels/pane-grid.ts` builds a cell per pane
+ * and registers its stage as it goes.
+ *
+ * **Split from `canvas-surface.ts` for one reason: the WORKSPACE.** The helpers that answer "which
+ * tab is this pane showing" need `workspace/workspace.ts`, and `workspace.ts` needs
+ * `services/monaco-buffer.ts` — which in turn has to enumerate every stage's source buffer, because
+ * a close gate that asked only "the" Monaco would miss whichever pane it was not holding. That is a
+ * cycle. The store of records has no opinion about tabs, so it is the half that comes out.
+ */
+
+import type { CanvasPanel } from "../types";
+import type { MonacoSurface } from "../view";
+
+/**
+ * The class name every pane's stage element carries.
+ *
+ * Declared here rather than in the grid because it is what the two genuinely document-level
+ * gestures test with `closest()` — "is this event over SOME stage" is a question about surfaces,
+ * not about the reconciler that happens to build them.
+ */
+export const STAGE_CLASS = "pane-stage";
+
+/** One pane's stage: where it renders, what it mounted there, and what it last drew. */
+export interface CanvasSurface {
+  /** The pane this stage belongs to. Stable for the life of the pane. */
+  readonly paneId: string;
+  /**
+   * The element the pane's stage renders into.
+   *
+   * Typed non-null and initialised null, exactly as the shell refs in `store.ts` are: a surface is
+   * addressable before its host exists in the DOM, and every renderer runs after `initShellRefs`.
+   */
+  wrap: HTMLElement;
+  /** The panels the last pass mounted here. Mutated in place by the render, never reassigned. */
+  readonly panels: CanvasPanel[];
+  /**
+   * The effective canvas mode this stage last drew, or null before its first pass.
+   *
+   * Per-surface because it decides a TEARDOWN: a mode transition rebuilds the panel structure, and
+   * one pane switching from Design to Code must not make the other pane's next pass believe its own
+   * structure is stale.
+   */
+  prevCanvasMode: string | null;
+  /**
+   * The transformed element the pan/zoom modes draw into, or null in the modes that render none.
+   *
+   * Per-surface because it IS the stage's content. `view.panzoomWrap` held whichever pane painted
+   * last, so a fit computed for one pane wrote a transform onto the other's artboards.
+   */
+  panzoomWrap: HTMLElement | null;
+  /** The observer that re-centres this stage until the author pans it. One per stage. */
+  centerObserver: ResizeObserver | null;
+  /** Whether this stage still wants re-centring — cleared by the first deliberate pan. */
+  needsCenter: boolean;
+  panX: number;
+  panY: number;
+  /** The source view's Monaco, mounted into THIS stage. Two Code panes are two models. */
+  monacoEditor: MonacoSurface | null;
+  /**
+   * The Stylebook filter and Customized flag THIS stage's catalogue was last built for.
+   *
+   * A one-slot module cache, until two panes started evicting each other from it.
+   * `shell.stylebook.filter` is a render input for every pane, so both stages render in the same
+   * frame: the first stored the new filter and rebuilt, the second compared against a slot the
+   * first had already advanced, found "nothing changed", and returned through the cheap
+   * `postStyleUpdateToStylebookHosts` path with its catalogue still listing the previous filter's
+   * specimens. Which pane lost was decided by render order, and it stayed wrong until a mode
+   * change. `null` means "this stage has never drawn a catalogue", which is not the same as "drew
+   * one for the empty filter" — the first pass must always rebuild.
+   */
+  prevStylebookFilter: string | null;
+  prevStylebookCustomizedOnly: boolean | null;
+  /** Teardown for this stage's source-mode collab binding (unbind + release the lock). */
+  sourceCollabCleanup: (() => void) | null;
+  /**
+   * The generation of the last render pass this stage opened.
+   *
+   * Per-surface because it is a STALENESS comparison within one pane: a deferred artboard asks "is
+   * the pass I belong to still the current one HERE". While it was app-wide, pane A opening a pass
+   * invalidated pane B's in-flight one, so B's artboards 1..n never reached `ready` and every edit
+   * in B escalated to a full render, permanently. The VALUES are still globally unique — see
+   * {@link nextRenderGeneration} — because the iframe host caches a pass's resolved document by
+   * generation identity.
+   */
+  renderGeneration: number;
+}
+
+/**
+ * The next render generation, monotonic across every surface.
+ *
+ * Unique across panes even though the comparison is per-pane: `iframe-host.ts`'s
+ * `preparePassRender` caches the resolved+serialized document on `byDoc` keyed by the generation's
+ * identity, so two surfaces reusing the number would thrash that cache — and the frame's own
+ * `latestGen` drop rule would start discarding the other pane's live renders.
+ */
+let _nextGen = 0;
+
+/** Take the next globally-unique render generation. */
+export function nextRenderGeneration(): number {
+  _nextGen += 1;
+  return _nextGen;
+}
+
+const _surfaces = new Map<string, CanvasSurface>();
+
+/**
+ * The surface record for a pane, created on first mention.
+ *
+ * Created rather than looked up so every reader has an answer before the host is attached — the
+ * same contract `store.ts`'s shell refs have, and what keeps `activeCanvasSurface()` non-nullable.
+ *
+ * @param {string} paneId
+ * @returns {CanvasSurface}
+ */
+export function surfaceForPane(paneId: string): CanvasSurface {
+  let surface = _surfaces.get(paneId);
+  if (!surface) {
+    surface = freshSurface(paneId);
+    _surfaces.set(paneId, surface);
+  }
+  return surface;
+}
+
+/** A surface record with nothing in it. One place the per-stage defaults are written down. */
+function freshSurface(paneId: string): CanvasSurface {
+  return {
+    centerObserver: null,
+    monacoEditor: null,
+    needsCenter: true,
+    panX: 0,
+    panY: 0,
+    panels: [],
+    paneId,
+    panzoomWrap: null,
+    prevCanvasMode: null,
+    prevStylebookCustomizedOnly: null,
+    prevStylebookFilter: null,
+    renderGeneration: 0,
+    sourceCollabCleanup: null,
+    wrap: null as unknown as HTMLElement,
+  };
+}
+
+/**
+ * Every registered surface, in registration order. The grid's inventory, and the tests'.
+ *
+ * @returns {CanvasSurface[]}
+ */
+export function allCanvasSurfaces(): CanvasSurface[] {
+  return [..._surfaces.values()];
+}
+
+/**
+ * The stage `node` sits inside, or null when it is outside every one of them.
+ *
+ * The N-stage replacement for `canvasWrap.contains(target)`. Two document-level gestures — the
+ * browser-zoom block and the wheel forwarded out of a frame — need "which stage is this in", and
+ * with one stage they were allowed to spell it as "is it in THE stage".
+ *
+ * @param {Node | null} node
+ * @returns {CanvasSurface | null}
+ */
+export function stageContaining(node: Node | null): CanvasSurface | null {
+  if (!node) {
+    return null;
+  }
+  for (const surface of _surfaces.values()) {
+    if (surface.wrap?.contains(node)) {
+      return surface;
+    }
+  }
+  return null;
+}
+
+/**
+ * Forget everything a surface's last pass mounted.
+ *
+ * Dropping the panel records is not enough: each artboard owns a render `EffectScope` (and the
+ * surgical-subtree scopes nested inside it) that goes on reacting to the document until it is
+ * stopped. The render path has always stopped them before emptying the array; a surface whose HOST
+ * changes hands has to do exactly the same, or every handover leaks one live scope per artboard —
+ * scopes that then repaint DOM belonging to a stage this pane no longer has.
+ */
+export function releaseMountedPanels(surface: CanvasSurface): void {
+  for (const panel of surface.panels) {
+    panel.renderScope?.stop();
+    panel.renderScope = null;
+  }
+  surface.panels.length = 0;
+  surface.prevCanvasMode = null;
+}
+
+/**
+ * Attach a pane's stage element. Called once per host that exists in the shell.
+ *
+ * A fresh host carries nothing over: the panels named by the previous one are detached DOM and the
+ * mode it last drew describes a structure that is gone, so both are cleared here rather than by
+ * each caller remembering to.
+ *
+ * @param {string} paneId
+ * @param {HTMLElement} wrap
+ * @returns {CanvasSurface}
+ */
+export function registerCanvasSurface(paneId: string, wrap: HTMLElement): CanvasSurface {
+  const surface = surfaceForPane(paneId);
+  surface.wrap = wrap;
+  releaseMountedPanels(surface);
+  return surface;
+}
+
+/* There is no `moveCanvasStage`, and there is no handover.
+   §18.3 handed the shell's ONE stage to whichever pane had focus, because there was one stage. The
+   grid gives every pane its own, registered by `panels/pane-grid.ts` when the cell is built and
+   released when it is removed, so nothing moves and no pane is ever left describing DOM it does
+   not own. The rule that survives is {@link releaseMountedPanels}: a surface that loses its host
+   has to stop the render scope of every artboard it mounted, or each goes on repainting a stage
+   that is not there. */
+
+/**
+ * Build a pane's surface record from scratch, replacing anything a previous pane of that id left.
+ *
+ * The grid calls this as it builds a cell, BEFORE the stage element exists — a pane is complete
+ * before it is published (§18.1 rule 1), and that includes the record every renderer resolves
+ * through.
+ *
+ * @param {string} paneId
+ * @returns {CanvasSurface}
+ */
+export function createPaneSurface(paneId: string): CanvasSurface {
+  const existing = _surfaces.get(paneId);
+  if (existing) {
+    disposePaneSurface(paneId);
+  }
+  const surface = freshSurface(paneId);
+  _surfaces.set(paneId, surface);
+  return surface;
+}
+
+/**
+ * How a surface releases the editors and observers its renders created.
+ *
+ * Injected, because the teardown lives in `canvas/canvas-render.ts` — which imports this module —
+ * and a surface record must stay reachable from the dependency-light half of the graph. Same idiom
+ * as `setIframePatchEscalation`.
+ */
+let _teardown: ((surface: CanvasSurface) => void) | null = null;
+
+/** Register the per-surface teardown. Called once, at import time, by `canvas-render.ts`. */
+export function setSurfaceTeardown(fn: ((surface: CanvasSurface) => void) | null): void {
+  _teardown = fn;
+}
+
+/**
+ * Release everything a pane's stage owns and forget the record.
+ *
+ * Ordered: the render-owned surfaces first (through the injected teardown — Monaco, the collab
+ * binding, the centering observer), then the artboards' render scopes, then the record. The DOM is
+ * the caller's: `pane-grid.ts` removes the cell, and `iframe-host.ts`'s `releaseCanvasHosts` tears
+ * the frames down BEFORE the removal, while they are still reachable from the stage.
+ *
+ * @param {string} paneId
+ */
+export function disposePaneSurface(paneId: string): void {
+  const surface = _surfaces.get(paneId);
+  if (!surface) {
+    return;
+  }
+  _teardown?.(surface);
+  releaseMountedPanels(surface);
+  unregisterCanvasSurface(paneId);
+}
+
+/** Forget a pane's surface record without releasing anything. Tests, and the app reset. */
+export function unregisterCanvasSurface(paneId: string): void {
+  _surfaces.delete(paneId);
+}