@jxsuite/studio 4.1.0 → 5.1.0

package/src/services/ai-write-report.ts

@@ -0,0 +1,174 @@
+/**
+ * Ai-write-report.ts — what the model is told after a document write, whoever made it.
+ *
+ * Extracted from `ai-tools.ts`'s `applyAndValidate`, which used to own both halves of a document
+ * tool: the transaction and the verdict on it. The verdict is the half every document write needs
+ * — the seven hand-registered tree tools AND every command the assistant runs through
+ * `services/ai-command-tools.ts` — so it lives here, in two functions the caller brackets its write
+ * with:
+ *
+ * 1. {@link snapshotBeforeWrite} reads the document's schema errors and render state BEFORE the
+ *    write, because the eval signal (ADR docs/ai-assistant-decision.md §6b) is "what did this edit
+ *    newly introduce", not "is the document valid": a page that was already broken must not make
+ *    every subsequent edit read as the culprit.
+ * 2. {@link reportDocumentWrite} compares AFTER the write, translating each new schema error into a
+ *    fix hint the model can act on, running the render check only when rendering worked before,
+ *    and appending the soft token-discipline hints to a success.
+ *
+ * The change stays applied either way (optimistic apply + undo, ADR §5); reporting the errors lets
+ * the agent loop self-correct on the next round.
+ *
+ * @license MIT
+ */
+
+import type { ToolResult } from "@jxsuite/ai/tools";
+import { toRaw } from "../reactivity";
+import type { Tab } from "../tabs/tab";
+import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
+
+/** A render probe's answer: rendered, or the message it threw. */
+export type RenderVerdict = { ok: true } | { ok: false; error: string };
+
+/** What a write reporter needs. Every member is what `registerAiTools` already takes by injection. */
+export interface WriteReportDeps {
+  /** Schema errors for a document, as raw ajv sentences. */
+  validate: (doc: unknown) => Promise<string[]>;
+  /** The detached-DOM render probe, when the host has one. */
+  renderCheck?: ((doc: unknown) => Promise<RenderVerdict>) | undefined;
+  /** The project's design tokens, read per call so a project opened mid-session contributes. */
+  getProjectStyle?: (() => Record<string, string> | undefined) | undefined;
+}
+
+/** The document as it stood before a write, in the two respects the verdict compares. */
+export interface WriteSnapshot {
+  errors: Set<string>;
+  renderOk: boolean;
+}
+
+/**
+ * Translate a raw JSON Schema validation error into a Jx-specific actionable message. The LLM needs
+ * concrete guidance on HOW to fix errors, not just what rule was violated. Shared with the
+ * project-level file tools (ai-project-tools.ts), which pre-validate Jx documents before writing.
+ *
+ * @param {string} rawError - Message from ajv (e.g. "/children/0/style: must NOT have additional
+ *   property")
+ * @returns {string}
+ */
+export function translateValidationError(rawError: string): string {
+  const lower = rawError.toLowerCase();
+
+  // Additional property — extract the offending key from the message if present
+  if (
+    lower.includes("must not have additional property") ||
+    lower.includes("additional properties")
+  ) {
+    return `${rawError}\n  → Fix: Remove or move the unexpected property. Style properties must be camelCase (e.g. "backgroundColor", not "background-color"). Non-IDL HTML attributes (aria-*, data-*, role, ...) must go inside an "attributes" object: { "attributes": { "aria-label": "..." } }.`;
+  }
+
+  // Pattern — usually tagName hyphen rule
+  if (lower.includes("must match pattern")) {
+    return `${rawError}\n  → Fix: Custom element tag names must contain a hyphen (e.g. "newsletter-form", "feature-card"). Standard HTML elements use their exact name (e.g. "div", "input", "button").`;
+  }
+
+  // Type error
+  if (lower.includes("must be string")) {
+    return `${rawError}\n  → Fix: Wrap the value in quotes — all Jx property values should be strings. For example, use "10px" (string) not 10px (unquoted).`;
+  }
+
+  if (lower.includes("must be number") || lower.includes("must be integer")) {
+    return `${rawError}\n  → Fix: Remove quotes from the numeric value — it should be a plain number, not a string.`;
+  }
+
+  if (lower.includes("must be object") || lower.includes("must be array")) {
+    return `${rawError}\n  → Fix: The value must be an object/array (use {} or []), not a string or number.`;
+  }
+
+  if (lower.includes("must be boolean")) {
+    return `${rawError}\n  → Fix: Use true or false without quotes for boolean values.`;
+  }
+
+  // Required property
+  if (lower.includes("must have required property")) {
+    return `${rawError}\n  → Fix: Add the missing required property. Every Jx element must have at least a "tagName" field.`;
+  }
+
+  // Enum / allowed values
+  if (lower.includes("must be equal to one of the allowed values")) {
+    return `${rawError}\n  → Fix: Change the value to one of the allowed options listed in the error.`;
+  }
+
+  return rawError;
+}
+
+/**
+ * Read the document's standing BEFORE a write: its schema errors and whether it renders.
+ *
+ * Reads the RAW document, not the reactive proxy, for the same reason `applyAndValidate` always
+ * did: the validator walks the whole tree, and walking a proxy subscribes whichever effect is
+ * running to every key of it.
+ *
+ * @param {Tab} tab
+ * @param {WriteReportDeps} deps
+ * @returns {Promise<WriteSnapshot>}
+ */
+export async function snapshotBeforeWrite(tab: Tab, deps: WriteReportDeps): Promise<WriteSnapshot> {
+  const rawBefore = toRaw(tab.doc.document);
+  const errors = new Set(await deps.validate(rawBefore));
+  const rendered = deps.renderCheck ? await deps.renderCheck(rawBefore) : { ok: true };
+  return { errors, renderOk: rendered.ok };
+}
+
+/**
+ * The verdict on a write that has been applied: the NEW schema errors with fix hints, the render
+ * check (only when rendering worked before — a page that already failed to render is not this
+ * edit's fault), or a success carrying `summary` plus any token-discipline hints.
+ *
+ * The three sentences here are the ones the model has read since the tools were written; every
+ * bridged document command now answers with the same ones, which is what lets the prompt's error
+ * recovery guidance stay generic.
+ *
+ * @param {Tab} tab
+ * @param {WriteSnapshot} before - What {@link snapshotBeforeWrite} read.
+ * @param {string} summary - The sentence to return on success.
+ * @param {WriteReportDeps} deps
+ * @returns {Promise<ToolResult>}
+ */
+export async function reportDocumentWrite(
+  tab: Tab,
+  before: WriteSnapshot,
+  summary: string,
+  deps: WriteReportDeps,
+): Promise<ToolResult> {
+  const rawAfter = toRaw(tab.doc.document);
+  const after = await deps.validate(rawAfter);
+  const newErrors = after.filter((e) => !before.errors.has(e));
+  if (newErrors.length > 0) {
+    const formatted = newErrors.map((e) => `- ${translateValidationError(e)}`).join("\n");
+    return {
+      success: false,
+      error: `Change applied, but it introduced schema errors. Fix these issues with follow-up edits:\n${formatted}`,
+    };
+  }
+
+  if (deps.renderCheck && before.renderOk) {
+    const renderResult = await deps.renderCheck(rawAfter);
+    if (!renderResult.ok) {
+      return {
+        success: false,
+        error: `Change applied and schema-valid, but it broke rendering. Fix with follow-up edits:\n- ${renderResult.error}`,
+      };
+    }
+  }
+
+  // Soft token-discipline hints (never fail the mutation)
+  const projectStyle = deps.getProjectStyle?.();
+  if (projectStyle) {
+    const findings = flagHardcodedTokens(rawAfter, projectStyle);
+    const hints = formatTokenHints(findings);
+    if (hints) {
+      return { success: true, summary: `${summary}\n\n${hints}` };
+    }
+  }
+
+  return { success: true, summary };
+}

package/src/services/document-assistant.ts

@@ -21,6 +21,11 @@ import { componentRegistry } from "../files/components";
 import { activeRegistry } from "../commands/active-registry";
 import { registerAiTools } from "./ai-tools";
 import { cancelAsk, registerAskTool, resetAsk } from "./ai-ask";
+import {
+  commandToolBlurbs,
+  composeToolRegistries,
+  createCommandToolRegistry,
+} from "./ai-command-tools";
 import { registerProjectTools } from "./ai-project-tools";
 import { registerImportTools, resetImportGuard } from "./ai-import-tools";
 import { createGatedToolRegistry } from "./gated-registry";
@@ -29,12 +34,14 @@ import { adoptProject } from "./project-adoption";
 import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
 import { AI_TOOL_TIERS, buildSystemPrompt, toolActive } from "./ai-system-prompt";
+import type { ExtensionCatalogSummary } from "./ai-system-prompt";
 import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
-import { openFileInTab, reloadFileInTab } from "../files/files";
-import { refreshExtensionUi } from "../format/format-host";
+import { validateDoc } from "./jx-validate";
+import { reloadFileInTab } from "../files/files";
+import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
 import * as sessionStore from "./ai-session-store";
 
 /**
@@ -91,7 +98,6 @@ export function createDocumentAssistant() {
     renderCheck: renderCheck as (
       doc: unknown,
     ) => Promise<{ ok: true } | { ok: false; error: string }>,
-    openDocument: openFileInTab,
     getProjectStyle,
     findOpenTab,
     reloadTab: reloadFileInTab,
@@ -123,12 +129,15 @@ export function createDocumentAssistant() {
         sessionStore.moveSession("", root, sessionId);
       }
     },
-    onProjectConfigWritten: async (config: ProjectConfig) => {
+    onProjectConfigWritten: async (config: ProjectConfig, text: string) => {
       /* Into the configuration document, not beside it. This used to assign a fresh object to
          `projectState.projectConfig`, leaving the document holding the previous configuration —
          and the next settings commit wrote that stale document back over the assistant's file.
-         `adoptProjectConfig` is the one door for a config that reached disk another way. */
-      await adoptProjectConfig(config);
+         `adoptProjectConfig` is the one door for a config that reached disk another way. The text
+         goes with it: the document derives the file's layout record from the bytes the tool wrote,
+         so the next settings commit is a one-line diff on the file as the model laid it out, not a
+         re-layout of it with the record of the file it read before (issue 331). */
+      await adoptProjectConfig(config, text);
       /* An `extensions` edit changes what the generated entry documents compose, and the backends
          regenerate them from project.json on demand — so without this the editor and the assistant
          both keep judging by the PREVIOUS project's schemas until the window reopens. */
@@ -150,7 +159,8 @@ export function createDocumentAssistant() {
     document: "an open document (use open_document first)",
     "document-tree":
       "an open document whose element tree the canvas is editing — Project Settings and the " +
-      "grid editors are documents, but not trees to restructure",
+      "grid editors are documents, but not trees to restructure, and a page left in Code view " +
+      "returns to the canvas with set_canvas_mode",
   } as const;
 
   /**
@@ -189,7 +199,26 @@ export function createDocumentAssistant() {
       },
     ]),
   );
-  const toolRegistry = createGatedToolRegistry(innerRegistry, availability);
+  /*
+   * The other kind of tool: every command record that declares `aiTool`, as a VIEW over the active
+   * registry (`services/ai-command-tools.ts`). Nothing is registered — the record IS the tool, its
+   * `when` / `enablement` is the gate, `registry.run` is the executor — so `enable_extension`,
+   * `delete_node` and the rest need no row in the tier table and no registrar here. The deps are
+   * the write reporter's, the same three the hand tree tools take, because a bridged document write
+   * is held to the same verdict (new schema errors, the render check, the token hints).
+   */
+  const commandTools = createCommandToolRegistry({
+    getProjectStyle,
+    getTab: () => activeTab.value,
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    validate: validateDoc,
+  });
+  const toolRegistry = composeToolRegistries(
+    createGatedToolRegistry(innerRegistry, availability),
+    commandTools,
+  );
 
   let controller: AbortController | null = null;
 
@@ -201,6 +230,19 @@ export function createDocumentAssistant() {
           .filter((e) => e.type === "file")
           .map((e) => e.path)
       : undefined;
+    /* The synchronous snapshot beside the async load, exactly as `getExtensions()` sits beside
+       `loadExtensions()`: `buildSystemPrompt` is a pure function and this is called per turn, so
+       the catalogue is read from the ONE cache the Extensions section also reads. Two caches would
+       be two answers to "what can this project turn on". */
+    const catalog: ExtensionCatalogSummary[] = [];
+    for (const entry of getExtensionCatalog()) {
+      catalog.push({
+        name: entry.name,
+        sections: entry.sections.map((section) => section.key),
+        ...(entry.title === undefined ? {} : { title: entry.title }),
+        ...(entry.description === undefined ? {} : { description: entry.description }),
+      });
+    }
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
       projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
@@ -208,7 +250,16 @@ export function createDocumentAssistant() {
       projectRoot: workspace.projectRoot || undefined,
       hasProject: Boolean(workspace.projectRoot),
       canImport: Boolean(getPlatform().importSite),
+      /* The same reading the gate makes, so the prompt advertises exactly what `execute` will
+         honour. This was never passed: with Project Settings focused the prompt listed the seven
+         hand tree writers while the `document-tree` gate refused every one of them, and the model
+         spent a round learning it. */
+      treeEditable: treeEditable(),
+      /* Read per turn from the live registry — a projected tool the gate will honour this round is
+         listed this round, and one it will not is not. */
+      commandTools: commandToolBlurbs(activeRegistry()),
       ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
+      ...(catalog.length > 0 ? { extensionCatalog: catalog } : {}),
     });
   }
 

package/src/services/idle.ts

@@ -12,22 +12,29 @@
  * in-flight (gitStatus)"]` — so the slow subsystem identifies itself.
  *
  * Nothing here polls a subsystem it does not own. Each source is a function the owning module
- * already had to write for its own reasons:
+ * already had to write for its own reasons.
+ *
+ * There WAS a seventh, `panel-scheduler.pendingSchedulers()`, and it went with the scheduler. It
+ * reported a panel with an animation frame queued or a render withheld while a field had focus —
+ * both facts about a lit dock repainting itself. The Navigator and the Inspector are documents now
+ * (`surfaces/navigator-dock.json`, `surfaces/inspector-dock.json`): a projection is written
+ * synchronously and a binding whose value did not move writes nothing, so there is no queued frame
+ * to be outstanding and no withheld render to wait for. The panel bodies that ARE still lit are
+ * painted synchronously from the same call.
  *
  * 1. `store.rendersInFlight()` — renderers mid-paint.
- * 2. `panel-scheduler.pendingSchedulers()` — panels with a frame queued or a render withheld.
- * 3. `iframe-host.canvasIdleBlockers()` — per host: unacked generations and patches, plus the frame's
+ * 2. `iframe-host.canvasIdleBlockers()` — per host: unacked generations and patches, plus the frame's
  *    own cross-realm report of fonts, running animations and pending image retries.
- * 4. `platform.platformInFlight()` — unsettled PAL calls, counted at the one seam every adapter and
+ * 3. `platform.platformInFlight()` — unsettled PAL calls, counted at the one seam every adapter and
  *    all thirty-odd `git*`/fs/fetch methods pass through.
- * 5. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
+ * 4. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
  *    resting toast is not a blocker, which is what lets `toastsAreHeld()` hold one open for a
  *    capture without `probeIdle()` waiting forever alongside it (plan §13.7's named exception).
- * 6. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
+ * 5. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
  *    duplicate of `platform`: an activity spans a whole operation (an install, a deploy, a clone)
  *    across many PAL calls, so the gaps between them look quiet at the seam while the operation is
  *    plainly mid-flight. A finished entry never blocks — the list stays on screen forever.
- * 7. `grid-idle.gridIdleBlockers()` — tables still building, or built but not yet showing the
+ * 6. `grid-idle.gridIdleBlockers()` — tables still building, or built but not yet showing the
  *    selection range `selectableRange: 1` gives them. Nothing else covered Tabulator: a grid
  *    command resolves when the panel mounts, which is several frames before the table is drawn.
  *
@@ -37,7 +44,6 @@
 
 import { rendersInFlight } from "../store";
 import { activityIdleBlockers } from "../panels/activity-panel";
-import { pendingSchedulers } from "../panels/panel-scheduler";
 import { canvasIdleBlockers } from "../canvas/iframe-host";
 import { platformInFlight } from "../platform";
 import { overlayIdleBlockers } from "../ui/layers";
@@ -45,7 +51,7 @@ import { gridIdleBlockers } from "../grid/grid-idle";
 
 /** One subsystem that can be outstanding, and its account of why. */
 export interface IdleSource {
-  /** Stable name — `render`, `panels`, `canvas`, `platform`, `overlay`. */
+  /** Stable name — `render`, `canvas`, `platform`, `overlay`. */
   readonly name: string;
   /** Empty when quiet; otherwise one human-readable line per outstanding item. */
   blockers: () => readonly string[];
@@ -73,7 +79,7 @@ export class NotIdleError extends Error {
 }
 
 /**
- * The seven live sources.
+ * The six live sources.
  *
  * Built per call rather than held in a module constant so a test can substitute one without
  * unpicking the others, and so a second window's hosts are never read through the first window's
@@ -88,10 +94,6 @@ export function defaultIdleSources(): IdleSource[] {
       },
       name: "render",
     },
-    {
-      blockers: () => pendingSchedulers().map((panel) => `panels: ${panel}`),
-      name: "panels",
-    },
     { blockers: canvasIdleBlockers, name: "canvas" },
     {
       blockers: () => {

package/src/services/live-surfaces.ts

@@ -0,0 +1,237 @@
+/**
+ * Live authoring of Studio's own chrome.
+ *
+ * Studio's surfaces are Jx documents (`src/surfaces/*.json`) and its controls are the kit's
+ * (`packages/ui/components/*.json`), so both are things Studio can open and edit. This is what
+ * closes the loop: a saved surface document re-mounts every root drawn from it, and a saved kit
+ * component redefines the element and re-mounts every root that used it, so the edit shows in the
+ * shell the reader is standing in (studio-ui-guidelines.md §9.3, embedding.md §7).
+ *
+ * **The lane is keyed on the saved PATH, and that is the whole of how it stays inert.** A save is
+ * something to act on only when the file, joined to the open project's root, is one of the two
+ * places the chrome comes from. Any other project — a site, a starter, the examples — saves files
+ * this never looks at, and the shipped app never reads its chrome from disk: the document that
+ * re-mounts is the one the tab just wrote, handed over by the save path, never read back.
+ *
+ * Two things are deliberately NOT here. The lane does not watch the filesystem: an edit made
+ * outside Studio reaches the shell on the next reload, as it always did, because a watcher is a
+ * second writer racing the tab. And it does not diff: a saved document is re-registered whole and
+ * every root re-mounted, because a surface's host scope is reused (`SurfaceMount.remount`) and only
+ * the surface-local state resets, which is the contract §9.3 gives the registry.
+ *
+ * A kit redefinition reaches the canvas frames too, with the FILE's URL under the project as its
+ * base: the frame draws a project's elements from the project's own files, so a sibling `$ref` in
+ * the definition must resolve to the project's copy, not to the bundle's. The frame answers the
+ * definition's `jx-ui:` sidecars from the loaders it registered at boot (`iframe-entry.ts`), one
+ * chunk per behaviour on first use.
+ *
+ * @docs extending/ui-kit
+ */
+import { redefineElement } from "@jxsuite/runtime";
+import { KIT_BASE } from "@jxsuite/ui";
+import type { JxDocument } from "@jxsuite/schema/types";
+import { mountsOf, mountsUsing } from "./surface-registry";
+import { registerSurface, surfaceDocument } from "../ui/surface";
+import { documentBase } from "../canvas/canvas-origin";
+
+/** What a saved file IS to the running shell. */
+export type LiveTarget =
+  | { readonly kind: "surface"; readonly name: string }
+  | { readonly kind: "element"; readonly tag: string };
+
+/** Where a surface document lives, from any root that contains it. */
+const SURFACE_PATH = /\/packages\/studio\/src\/surfaces\/([\w-]+)\.json$/;
+/** Where a kit component lives, from any root that contains it. */
+const ELEMENT_PATH = /\/packages\/ui\/components\/(jx-[\w-]+)\.json$/;
+
+/**
+ * Join a project root and a path the way the platform reports them, and normalise the separators so
+ * a Windows root and a POSIX-relative path meet in one spelling.
+ */
+function joined(projectRoot: string, path: string): string {
+  const root = projectRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+  const rel = path.replaceAll("\\", "/").replace(/^\.?\//, "");
+  return `${root}/${rel}`;
+}
+
+/**
+ * Which surface or element a saved path is, or null for every other file.
+ *
+ * Matched by suffix against the root JOINED to the path rather than by which project is open, so
+ * the same answer comes from the kit opened as its own project (`components/jx-tree.json` under
+ * `packages/ui`), from Studio opened as one (`src/surfaces/menu.json` under `packages/studio`), or
+ * from any root above them. A path that is neither — including every file of every other project —
+ * is null, and null is the lane doing nothing.
+ *
+ * @param projectRoot The open project's root, as the platform reports it.
+ * @param path The saved path, relative to that root.
+ */
+export function liveSurfaceTarget(
+  projectRoot: string | null | undefined,
+  path: string | null | undefined,
+): LiveTarget | null {
+  if (!projectRoot || !path) {
+    return null;
+  }
+  const full = joined(projectRoot, path);
+  const surface = SURFACE_PATH.exec(full);
+  if (surface) {
+    return { kind: "surface", name: surface[1]! };
+  }
+  const element = ELEMENT_PATH.exec(full);
+  if (element) {
+    return { kind: "element", tag: element[1]! };
+  }
+  return null;
+}
+
+/** What one save did. */
+export interface LiveSurfaceResult {
+  readonly target: LiveTarget;
+  /** How many roots were re-mounted. Zero is a document nothing on screen was drawn from. */
+  readonly remounted: number;
+  /** How many canvas frames were told of an element's redefinition. Absent for a surface. */
+  readonly canvases?: number;
+  /** Why nothing was applied, when nothing was. */
+  readonly refused?: string;
+}
+
+/**
+ * The URL a frame resolves a saved kit component against: the file's own URL under the project,
+ * which is where the frame fetched the definition it holds and where its sibling `$ref`s live.
+ *
+ * @param projectRoot The open project's root.
+ * @param path The saved path, relative to it.
+ */
+export function canvasBaseFor(projectRoot: string, path: string): string {
+  return new URL(path.replaceAll("\\", "/").replace(/^\.?\//, ""), documentBase(projectRoot)).href;
+}
+
+/**
+ * Apply a saved document to the running shell.
+ *
+ * A surface is re-registered under its name — the same call the bundle makes at boot, so the
+ * runtime's own resolution paths see the new document too — and every root of that name is
+ * re-mounted. An element is redefined through the runtime (embedding.md §7) and every root whose
+ * render instantiated it is re-mounted, which is what turns a redefinition into something visible:
+ * an instance already connected keeps the definition it rendered until it is re-mounted.
+ *
+ * A surface name nothing has registered is refused rather than registered: a new file under
+ * `src/surfaces/` has no adapter to mount it, so registering it would promise a mount nothing will
+ * make. An element whose document names a different tag than its file is refused too — the file is
+ * what the kit's registry keys on, and a document that disagrees with its own name is a mistake to
+ * report, not one to define under either spelling.
+ *
+ * @param target What the saved file is.
+ * @param doc The document the tab just wrote.
+ */
+export async function applyLiveSave(
+  target: LiveTarget,
+  doc: JxDocument,
+): Promise<LiveSurfaceResult> {
+  if (target.kind === "surface") {
+    if (!surfaceDocument(target.name)) {
+      return { refused: `no surface is registered as "${target.name}"`, remounted: 0, target };
+    }
+    registerSurface(target.name, doc);
+    const roots = mountsOf(target.name);
+    await Promise.all(roots.map((m) => m.remount()));
+    return { remounted: roots.length, target };
+  }
+  if (doc.tagName !== target.tag) {
+    return {
+      refused: `the document names <${String(doc.tagName)}>, but the file is ${target.tag}.json`,
+      remounted: 0,
+      target,
+    };
+  }
+  await redefineElement(doc, KIT_BASE);
+  const roots = mountsUsing(target.tag);
+  await Promise.all(roots.map((m) => m.remount()));
+  return { remounted: roots.length, target };
+}
+
+/** The two channels a save's outcome is said on. A refusal is a problem; a re-mount is a toast. */
+export interface LiveSurfaceNotifier {
+  info: (message: string, options: { key: string; source: string }) => void;
+  warn: (message: string, options: { key: string; source: string; tier: "problem" }) => void;
+}
+
+/**
+ * What the lane needs from the shell, as the records themselves rather than closures over them, so
+ * the bootstrap hands over objects it already holds and writes no function of its own.
+ */
+export interface LiveSurfaceDeps {
+  /** The workspace record; `projectRoot` is read at save time, never captured. */
+  workspace: { readonly projectRoot: string | null };
+  notify: LiveSurfaceNotifier;
+  /**
+   * Redefine an element in every live canvas frame and render them; answers how many were told.
+   * `canvas-render.ts`'s `redefineElementOnCanvases`, injected so this module imports no canvas.
+   */
+  redefineOnCanvases: (doc: JxDocument, base: string) => number;
+}
+
+/** The sentence a result is said in. Exported so the wording is tested, not only the branch. */
+export function liveSaveNotice(result: LiveSurfaceResult): {
+  key: string;
+  level: "info" | "warn";
+  message: string;
+} {
+  const what =
+    result.target.kind === "surface" ? `surface ${result.target.name}` : result.target.tag;
+  const key = `live-chrome:${what}`;
+  if (result.refused) {
+    return { key, level: "warn", message: `Not applied to the running shell: ${result.refused}.` };
+  }
+  const canvases =
+    result.canvases === undefined || result.canvases === 0
+      ? ""
+      : result.canvases === 1
+        ? " and on the canvas"
+        : ` and on ${result.canvases} canvases`;
+  if (result.remounted === 0) {
+    return {
+      key,
+      level: "info",
+      message: `${what} saved; nothing in the shell is drawn from it${canvases ? `, redefined${canvases}` : ""}.`,
+    };
+  }
+  const places = result.remounted === 1 ? "1 place" : `${result.remounted} places`;
+  return {
+    key,
+    level: "info",
+    message: `${what} saved and re-mounted in ${places}${canvases}.`,
+  };
+}
+
+/**
+ * The save listener: decide whether the saved file is chrome, and if it is, apply it and say so.
+ *
+ * Returns the result, or null when the save was not chrome, so a caller — and a test — can tell
+ * "nothing to do" from "did nothing".
+ *
+ * @param deps The shell's workspace record and notifier.
+ */
+export function createLiveSurfaceSaver(
+  deps: LiveSurfaceDeps,
+): (path: string | null, doc: JxDocument | null) => Promise<LiveSurfaceResult | null> {
+  return async (path, doc) => {
+    const root = deps.workspace.projectRoot;
+    const target = liveSurfaceTarget(root, path);
+    if (!target || !doc || !root || !path) {
+      return null;
+    }
+    let result = await applyLiveSave(target, doc);
+    if (target.kind === "element" && !result.refused) {
+      result = { ...result, canvases: deps.redefineOnCanvases(doc, canvasBaseFor(root, path)) };
+    }
+    const notice = liveSaveNotice(result);
+    if (notice.level === "warn") {
+      deps.notify.warn(notice.message, { key: notice.key, source: "Studio", tier: "problem" });
+    } else {
+      deps.notify.info(notice.message, { key: notice.key, source: "Studio" });
+    }
+    return result;
+  };
+}