@jxsuite/studio 4.1.0 → 5.1.0

package/src/editor/shortcuts.ts

@@ -33,13 +33,13 @@
 import { childIndex, childList, getNodeAtPath, parentElementPath, projectState } from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import {
-  STAGE_CLASS,
   allCanvasSurfaces,
   canvasModeOfPane,
   surfaceForPane,
   tabOfPane,
 } from "../canvas/canvas-surface";
 import type { CanvasSurface } from "../canvas/canvas-surface";
+import { STAGE_SELECTOR } from "../surfaces/pane-grid";
 import { primarySelection } from "../tabs/selection";
 import {
   mutateDuplicateNodes,
@@ -58,7 +58,8 @@ import {
 import { openQuickSearch } from "../panels/quick-search";
 import { inspectorTab } from "../panels/right-panel";
 import { requestClose } from "../panels/tab-strip";
-import { showDialog } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openDialogSurface } from "../surfaces/dialog";
 import { rectOf } from "../utils/geometry";
 import {
   DOCK_IDS,
@@ -76,8 +77,7 @@ import { clipboardCommands, pasteNode } from "./context-menu";
 import { hasElementSelection, hasSelection, inCanvas, keyScopeStack } from "../commands/context";
 import { defaultCommands } from "../commands/defaults";
 import { setActiveRegistry } from "../commands/active-registry";
-import { CommandUnavailableError } from "../commands/registry";
-import { html } from "lit-html";
+import { runReported } from "../commands/run-reported";
 import type { CommandContext } from "../commands/context";
 import type { DockId as CommandDockId } from "../commands/defaults";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
@@ -388,11 +388,12 @@ function toggleShellDock(registry: CommandRegistry, dock: CommandDockId): void {
  *
  * `view.setAssistant` and `view.setRightTab` are `shell.ts`'s, composed into the app's registry by
  * the bootstrap — a reduced registry (a test, a future second window kind) may not carry them, and
- * a missing id must be inert rather than an exception thrown out of a keydown handler.
+ * a missing id must be inert rather than an exception thrown out of a keydown handler. A present
+ * one that refuses its arguments is not inert: `commands/run-reported.ts` files it in Problems.
  */
 function runIfPresent(registry: CommandRegistry, id: string, args: Record<string, unknown>): void {
   if (registry.get(id) && registry.isEnabled(id)) {
-    void registry.run(id, args);
+    void runReported(registry, id, args, "Keyboard");
   }
 }
 
@@ -464,9 +465,19 @@ export function nextRegion(
   return null;
 }
 
-/** The first element inside a region that can take the caret. */
+/**
+ * The first element inside a region that can take the caret.
+ *
+ * It also listed `sp-action-button`, `sp-tab`, `sp-textfield` and `sp-picker`, and those four were
+ * load-bearing while Spectrum drew the chrome: a Spectrum control keeps its real control in a
+ * SHADOW ROOT, so `querySelector` inside a region host reached the custom element and nothing else.
+ * The kit has no shadow root anywhere (`ui.md` §3.2 — no element declares `$shadow`), so each of
+ * its controls puts a native `<button>`, `<input>` or `<select>` in the region's own tree, and the
+ * native entries already in this list find them. Naming the kit tags beside them would match the
+ * WRAPPER, one node earlier in document order than the thing that takes focus.
+ */
 const REGION_FOCUSABLE =
-  'a[href], button, input, textarea, select, sp-action-button, sp-tab, sp-textfield, sp-picker, [tabindex]:not([tabindex="-1"])';
+  'a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])';
 
 /**
  * Move focus into a region and record that it moved.
@@ -569,6 +580,51 @@ const OPEN_PROJECT_REPORT: Record<Exclude<ProjectOpenOutcome, "cancelled">, stri
   opened: "Opened the project in this window.",
 };
 
+/**
+ * The three-way question itself: New Window, This Window, or neither.
+ *
+ * It was a hand-written `sp-dialog-wrapper` passed to `showDialog`, and it was never bespoke — a
+ * headline, a sentence and confirm / secondary / cancel is exactly what `surfaces/dialog.json`
+ * draws for Save-or-Discard, so the wrapper was a second answer to a settled question
+ * (studio-ui-guidelines.md §12.5). What is genuinely this flow's is only WHAT the three answers
+ * mean, which is the mapping below; the modality, the focus restoration, Escape and the backdrop
+ * are the platform's `<dialog>`, through the kit.
+ *
+ * `onClosed` resolves `cancel` the way the wrapper's `@close` did, and the settle guard is what
+ * makes the pair safe: pressing Cancel fires both the answer and, as the dialog closes,
+ * `onClosed`.
+ *
+ * @param {string} openName The project already open in this window, named in the sentence.
+ * @returns {Promise<ProjectOpenTarget | "cancel">}
+ */
+function askWhereToOpen(openName: string): Promise<ProjectOpenTarget | "cancel"> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value: ProjectOpenTarget | "cancel") => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      handle.close();
+      resolve(value);
+    };
+    const handle = openDialogSurface({
+      cancelLabel: "Cancel",
+      confirmLabel: "New Window",
+      headline: "Open Project",
+      layer: layerHost("dialog"),
+      message: `${openName} is open in this window. Where should the project you pick open?`,
+      onCancel: () => done("cancel"),
+      onClosed: () => done("cancel"),
+      onConfirm: () => done("newWindow"),
+      onSecondary: () => done("thisWindow"),
+      region: "project/open-target",
+      secondaryLabel: "This Window",
+      size: "sm",
+    });
+  });
+}
+
 /**
  * Ask where the project should open, then say what happened.
  *
@@ -592,25 +648,7 @@ export async function openProjectFlow(hooks: StudioCommandHooks): Promise<void>
     return;
   }
   const openName = projectState.name;
-  const choice = await showDialog<ProjectOpenTarget | "cancel">(
-    (done) => html`
-      <sp-dialog-wrapper
-        open
-        underlay
-        headline="Open Project"
-        confirm-label="New Window"
-        secondary-label="This Window"
-        cancel-label="Cancel"
-        size="s"
-        @confirm=${() => done("newWindow")}
-        @secondary=${() => done("thisWindow")}
-        @cancel=${() => done("cancel")}
-        @close=${() => done("cancel")}
-      >
-        <p>${openName} is open in this window. Where should the project you pick open?</p>
-      </sp-dialog-wrapper>
-    `,
-  );
+  const choice = await askWhereToOpen(openName);
   if (choice === "cancel") {
     return;
   }
@@ -864,34 +902,21 @@ export function registerStudioCommands(
  *
  * `preventDefault()` iff a command claimed the chord. A command that is VISIBLE but disabled — ⌘Z
  * with nothing to undo, Delete on the document element — still counts as claiming it: the registry
- * throws {@link CommandUnavailableError} from `run`, and swallowing the key is the honest outcome,
- * because the chord is spoken for and letting the browser act on it instead would be a surprise.
- *
- * HANDOFF: `registry.handleKeyEvent` reports the hit and runs it in one step, so a refusal can only
- * be observed by catching. It would be better for it to consult `isEnabled` itself and return the
- * id without running; `commands/registry.ts` is another workstream's file this wave.
+ * consults `isEnabled` itself and returns the id without running, and swallowing the key is the
+ * honest outcome, because the chord is spoken for and letting the browser act on it instead would
+ * be a surprise. Nothing is caught here, because nothing leaves: `handleKeyEvent` runs the hit
+ * through `commands/run-reported.ts`, so a record that refuses its arguments, a gate that closed
+ * between the check and the run, or a `run` body that throws is a Problems row under "Keyboard"
+ * rather than an exception out of the keydown listener.
  */
 function dispatchKey(registry: CommandRegistry, event: KeyboardEvent): string | undefined {
-  const commandId = claimChord(registry, event);
+  const commandId = registry.handleKeyEvent(event, keyScopeStack(registry.context()));
   if (commandId) {
     event.preventDefault();
   }
   return commandId;
 }
 
-/** The id of the command that claimed the chord, whether it ran or refused. */
-function claimChord(registry: CommandRegistry, event: KeyboardEvent): string | undefined {
-  const stack = keyScopeStack(registry.context());
-  try {
-    return registry.handleKeyEvent(event, stack);
-  } catch (error) {
-    if (error instanceof CommandUnavailableError) {
-      return error.commandId;
-    }
-    throw error;
-  }
-}
-
 // ─── Pointer and wheel gestures ───────────────────────────────────────────────
 
 /**
@@ -928,7 +953,7 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
   document.addEventListener(
     "wheel",
     (e: WheelEvent) => {
-      if ((e.ctrlKey || e.metaKey) && !(e.target as Element | null)?.closest(`.${STAGE_CLASS}`)) {
+      if ((e.ctrlKey || e.metaKey) && !(e.target as Element | null)?.closest(STAGE_SELECTOR)) {
         e.preventDefault();
       }
     },
@@ -1005,7 +1030,9 @@ export function installStageGestures(surface: CanvasSurface): () => void {
           requestEditZoom(editZoom * (1 + -e.deltaY * 0.005), surface);
           return;
         }
-        const sc = canvasWrap.querySelector<HTMLElement>(".content-edit-canvas");
+        /* The stage's own scroller, by the `part` the stage document draws it with — the same
+           attribute every other consumer of the canvas's chrome now addresses it by. */
+        const sc = canvasWrap.querySelector<HTMLElement>('[part="edit-canvas"]');
         if (sc) {
           e.preventDefault();
           sc.scrollTop += e.deltaY;

package/src/editor/slash-menu.ts

@@ -1,17 +1,33 @@
 /// <reference lib="dom" />
 /**
- * Slash-menu.js — Shared slash command menu for element insertion
+ * The slash menu — the shared element-insertion list, and the flow behind it.
  *
- * A single implementation used by both inline-edit (Edit/Content modes) and component inline
- * editing (Design mode). Renders a Spectrum-styled popover with keyboard navigation. Uses a
- * document-level capturing keydown listener so it intercepts Enter/Arrow/Escape before any
- * element-level handlers.
+ * One implementation used by inline editing in both realms (Edit/Content and Design mode), by the
+ * block action bar's convert menu, and by the canvas `+`. `surfaces/slash-menu.json` is the panel —
+ * its markup, its ARIA and every value in its style — and this module is the decisions: what is on
+ * offer, what the filter matches, which row is active, and what a pick does.
+ *
+ * **Why this is not `surfaces/menu.json`.** Every other Studio menu is that surface, and §12.5 says
+ * a second list of actions is a defect — but a `jx-menu` owns DOM focus by contract: showing one
+ * moves the caret onto its first row. This panel exists to filter a caret that is somewhere else,
+ * inside the canvas's `contenteditable` and usually inside the canvas IFRAME, and every character
+ * typed after the `/` has to keep landing there. A panel that takes the keyboard ends the
+ * interaction it exists to serve. So the panel is a listbox that marks its active row and never
+ * takes focus, and the keys are taken where they actually land — a document-level capturing
+ * listener for this realm, and {@link handleSlashMenuKey} called straight across the bridge for the
+ * other one. That listener is not a focus trap and cannot become one: it forwards four keys to the
+ * same driver the bridge uses, and everything else keeps going to the caret.
+ *
+ * Light dismissal, the top layer and Escape-on-the-topmost-popover are the platform's, through the
+ * `jx-popover` the document is rooted in; the `mousedown` capture listener that used to hand-roll
+ * the first of those went with the Spectrum markup.
+ *
+ * @docs studio/editing/slash-commands
  */
 
-import { html, render as litRender, nothing } from "lit-html";
-import { ref } from "lit-html/directives/ref.js";
-import { getLayerSlot } from "../ui/layers";
+import { openSlashMenuSurface } from "../surfaces/slash-menu";
 import { rectOf } from "../utils/geometry";
+import type { SlashMenuRow, SlashMenuSurface, SlashMenuView } from "../surfaces/slash-menu";
 
 interface SlashCommand {
   label: string;
@@ -61,16 +77,12 @@ let activeIdx = 0;
 
 /** What the current open() asked for, so a repaint driven by the keyboard reproduces it. */
 let showFilter = false;
+/** What the panel's own filter field holds. Empty for an anchored menu, which has no field. */
+let filterText = "";
 let filteredItems: SlashCommand[] = [];
 let open = false;
 let _anchorRect: SlashMenuAnchorRect | null = null;
-let _filterEl: HTMLInputElement | null = null;
-let _popoverEl: HTMLElement | null = null;
-
-/** @returns {HTMLElement} */
-function getHost() {
-  return getLayerSlot("popover", "slash-menu");
-}
+let _surface: SlashMenuSurface | null = null;
 
 // ─── Public API ───────────────────────────────────────────────────────────────
 
@@ -87,7 +99,7 @@ export function isSlashMenuOpen() {
  * @param {SlashMenuCallbacks} cbs
  */
 export function showSlashMenu(anchorEl: HTMLElement, filter: string, cbs: SlashMenuCallbacks) {
-  showAt(rectOf(anchorEl), filter, cbs);
+  showAt(rectOf(anchorEl), filter, cbs, anchorEl);
 }
 
 /**
@@ -107,17 +119,55 @@ export function showSlashMenuAtRect(
   showAt(rect, filter, cbs);
 }
 
+/** Everything on offer right now: what the caller named, or the standard set. */
+function source(): SlashCommand[] {
+  return callbacks?.commands || SLASH_COMMANDS;
+}
+
+/** The offers a filter leaves standing. An empty filter leaves all of them. */
+function matching(filter: string, from: SlashCommand[]): SlashCommand[] {
+  return filter
+    ? from.filter(
+        (c) => c.label.toLowerCase().includes(filter) || c.tag.toLowerCase().includes(filter),
+      )
+    : from;
+}
+
+/** What the panel should be showing, from the state above. */
+function view(): SlashMenuView {
+  const rect = _anchorRect;
+  return {
+    activeIndex: activeIdx,
+    filter: filterText,
+    rows: filteredItems.map((cmd): SlashMenuRow => ({
+      description: cmd.description,
+      key: cmd.tag,
+      label: cmd.label,
+    })),
+    showFilter,
+    // The gap between the anchor and the panel is the `--jx-popover-offset` token the element
+    // Already applies, so this is the anchor's own edge rather than an edge plus a guess.
+    x: rect ? rect.left : 0,
+    y: rect ? rect.bottom : 0,
+  };
+}
+
+/** Push the current state to the open panel. A no-op when there is none. */
+function paint(): void {
+  _surface?.update(view());
+}
+
 /** Shared body of the two show entry points. */
-function showAt(rect: SlashMenuAnchorRect, filter: string, cbs: SlashMenuCallbacks) {
+function showAt(
+  rect: SlashMenuAnchorRect,
+  filter: string,
+  cbs: SlashMenuCallbacks,
+  anchor?: Element | null,
+) {
   callbacks = cbs;
   _anchorRect = rect;
 
-  const source = cbs.commands || SLASH_COMMANDS;
-  filteredItems = filter
-    ? source.filter(
-        (c) => c.label.toLowerCase().includes(filter) || c.tag.toLowerCase().includes(filter),
-      )
-    : source;
+  filteredItems = matching(filter, cbs.commands || SLASH_COMMANDS);
 
   if (filteredItems.length === 0 && !cbs.showFilter) {
     dismissSlashMenu();
@@ -125,120 +175,86 @@ function showAt(rect: SlashMenuAnchorRect, filter: string, cbs: SlashMenuCallbac
   }
 
   activeIdx = 0;
-
   showFilter = cbs.showFilter || false;
-  render();
 
-  if (!open) {
-    open = true;
-    document.addEventListener("keydown", onKeydown, true); // Capture phase
-    requestAnimationFrame(() => {
-      document.addEventListener("mousedown", onOutsideClick, true);
-    });
+  if (_surface) {
+    paint();
+    return;
   }
 
-  if (cbs.showFilter) {
-    requestAnimationFrame(() => {
-      if (_filterEl) {
-        _filterEl.focus();
+  open = true;
+  filterText = "";
+  document.addEventListener("keydown", onKeydown, true); // Capture phase
+  _surface = openSlashMenuSurface(
+    view(),
+    {
+      activateRow: (index) => {
+        const cmd = filteredItems[index];
+        if (cmd) {
+          select(cmd);
+        }
+      },
+      dismissed: onPlatformDismiss,
+      hover: (index) => {
+        activeIdx = index;
+        paint();
+      },
+      input: onFilterInput,
+    },
+    anchor ?? null,
+  );
+  if (showFilter) {
+    const surface = _surface;
+    void surface.ready.then(() => {
+      if (_surface === surface) {
+        surface.focusFilter();
       }
     });
   }
 }
 
-export function dismissSlashMenu() {
-  if (!open) {
-    return;
-  }
+/**
+ * Forget everything about the open menu and hand back whoever asked for it.
+ *
+ * Split out because there are two ways one closes — this module closing it, and the PLATFORM
+ * closing it (a click outside, Escape on the topmost popover) — and both have to leave exactly the
+ * same state behind.
+ */
+function teardown(): SlashMenuCallbacks | null {
   const cbs = callbacks;
   open = false;
   callbacks = null;
   _anchorRect = null;
-  _filterEl = null;
-  _popoverEl = null;
   filteredItems = [];
+  filterText = "";
+  activeIdx = 0;
   document.removeEventListener("keydown", onKeydown, true);
-  document.removeEventListener("mousedown", onOutsideClick, true);
-  litRender(nothing, getHost());
+  return cbs;
+}
+
+export function dismissSlashMenu() {
+  if (!open) {
+    return;
+  }
+  const surface = _surface;
+  _surface = null;
+  const cbs = teardown();
+  surface?.close();
   // After teardown so a re-entrant show from the callback sees a closed menu. select() relies on
   // This ordering too: dismiss (→ onDismiss) fires BEFORE onSelect.
   cbs?.onDismiss?.();
 }
 
-// ─── Internal ─────────────────────────────────────────────────────────────────
-
-/* No parameter: `showFilter` is module state now, so there is one answer to what this
-   menu is, and a keyboard repaint cannot disagree with the open() that created it. */
-function render() {
-  const rect = _anchorRect;
-  if (!rect) {
+/** The platform closed the panel — a click outside, or Escape reaching the topmost popover. */
+function onPlatformDismiss(): void {
+  if (!open) {
     return;
   }
-
-  litRender(
-    html`
-      <sp-popover
-        open
-        data-jx-region="overlay.menu:slash-menu"
-        ${ref((el) => {
-          _popoverEl = (el as HTMLElement | undefined) || null;
-        })}
-        style="position:fixed;left:${rect.left}px;top:${
-          rect.bottom + 4
-        }px;z-index:9999;max-height:320px;overflow-y:auto"
-      >
-        ${
-          showFilter
-            ? html`<input
-                class="slash-filter"
-                type="text"
-                placeholder="Filter…"
-                autocomplete="off"
-                style="display:block;width:100%;box-sizing:border-box;padding:6px 10px;border:none;border-bottom:1px solid var(--border, #444);outline:none;font-size:13px;background:transparent;color:inherit"
-                ${ref((el) => {
-                  _filterEl = (el as HTMLInputElement | undefined) || null;
-                })}
-                @input=${onFilterInput}
-              />`
-            : nothing
-        }
-        <sp-menu style="min-width:220px">
-          ${
-            filteredItems.length > 0
-              ? filteredItems.map(
-                  (cmd, i) => html`
-                    <sp-menu-item
-                      ?focused=${i === activeIdx}
-                      @click=${(e: Event) => {
-                        e.preventDefault();
-                        e.stopPropagation();
-                        select(cmd);
-                      }}
-                    >
-                      ${cmd.label}
-                      ${
-                        cmd.description
-                          ? html`<span slot="description">${cmd.description}</span>`
-                          : nothing
-                      }
-                    </sp-menu-item>
-                  `,
-                )
-              : html`<sp-menu-item disabled>No matches</sp-menu-item>`
-          }
-        </sp-menu>
-      </sp-popover>
-    `,
-    getHost(),
-  );
+  _surface = null;
+  teardown()?.onDismiss?.();
 }
 
-/** @param {MouseEvent} e */
-function onOutsideClick(e: MouseEvent) {
-  if (_popoverEl && !_popoverEl.contains(e.target as Node)) {
-    dismissSlashMenu();
-  }
-}
+// ─── Internal ─────────────────────────────────────────────────────────────────
 
 /** @param {SlashCommand} cmd */
 function select(cmd: SlashCommand) {
@@ -247,41 +263,12 @@ function select(cmd: SlashCommand) {
   cbs?.onSelect(cmd);
 }
 
-/** @param {Event} e */
-function onFilterInput(e: Event) {
-  const input = e.target as HTMLInputElement;
-  const filter = input.value.toLowerCase();
-
-  const source = callbacks?.commands || SLASH_COMMANDS;
-  filteredItems = filter
-    ? source.filter(
-        (c) => c.label.toLowerCase().includes(filter) || c.tag.toLowerCase().includes(filter),
-      )
-    : source;
-
+/** @param {string} value */
+function onFilterInput(value: string) {
+  filterText = value;
+  filteredItems = matching(value.toLowerCase(), source());
   activeIdx = 0;
-  render();
-
-  // Re-focus input after re-render
-  requestAnimationFrame(() => {
-    if (_filterEl && _filterEl !== document.activeElement) {
-      _filterEl.focus();
-      _filterEl.selectionStart = _filterEl.value.length;
-      _filterEl.selectionEnd = _filterEl.value.length;
-    }
-  });
-}
-
-/**
- * Scroll the active row into view after a repaint.
- *
- * The only imperative half of the keyboard model, and it stays imperative on purpose: where a row
- * sits in a scroller is a measurement, not something a template can express. Everything else —
- * WHICH row is active — is now a binding, because it has to be.
- */
-function revealActive(): void {
-  const rows = getHost().querySelectorAll("sp-menu-item:not([disabled])");
-  rows[activeIdx]?.scrollIntoView({ block: "nearest" });
+  paint();
 }
 
 /**
@@ -289,29 +276,35 @@ function revealActive(): void {
  * was pressed in the iframe realm — a synthetic keydown redispatch on this document would lose the
  * capture-first + stopPropagation semantics the menu relies on to shield other handlers).
  *
+ * The offers are read from the array behind the panel rather than from its rows: the rows are a
+ * rendering, and a key that arrives while the document is still reconciling would otherwise be
+ * counting a list that has not caught up.
+ *
+ * Nothing here scrolls the new row into view, and that is the kit's rather than an omission: the
+ * panel writes ONE id, the listbox's `active`, and `mountListbox` is what turns that into a row's
+ * `selected` and brings it back on screen. Measurement belongs to the element that can see the
+ * box.
+ *
  * @param {string} key — "ArrowDown" | "ArrowUp" | "Enter" | "Escape"
  */
 export function handleSlashMenuKey(key: string): void {
   if (!open) {
     return;
   }
-
-  const items = getHost().querySelectorAll("sp-menu-item:not([disabled])") as NodeListOf<Element>;
+  const count = filteredItems.length;
 
   if (key === "ArrowDown") {
-    if (items.length === 0) {
+    if (count === 0) {
       return;
     }
-    activeIdx = (activeIdx + 1) % items.length;
-    render();
-    revealActive();
+    activeIdx = (activeIdx + 1) % count;
+    paint();
   } else if (key === "ArrowUp") {
-    if (items.length === 0) {
+    if (count === 0) {
       return;
     }
-    activeIdx = (activeIdx - 1 + items.length) % items.length;
-    render();
-    revealActive();
+    activeIdx = (activeIdx - 1 + count) % count;
+    paint();
   } else if (key === "Enter") {
     const cmd = filteredItems[activeIdx];
     if (cmd) {

package/src/files/components.ts

@@ -3,6 +3,7 @@
 import { getPlatform } from "../platform";
 import { projectState } from "../store";
 import type { ComponentMeta } from "../types";
+import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** A discovered component: project components carry a file path; package components may not. */
@@ -26,6 +27,44 @@ export async function loadComponentRegistry() {
   }
 }
 
+/**
+ * Bring the registry up to date with a document that was just saved.
+ *
+ * The registry is the snapshot the platform's scan took when the project opened, and a saved
+ * component definition used to leave it behind: give a prop `format: "image"` in the definition and
+ * every instance's Component Settings kept drawing the text box the snapshot knew, until the
+ * project was reopened. The saved document is the same input the scan reads, through the same
+ * extractor (`componentMetaFrom`, shared by all three backends), so the entry is rebuilt from it
+ * here rather than by a rescan of every JSON file in the project. A definition that stopped being a
+ * component (its `tagName` lost its hyphen) leaves the registry by the same rule the scan applies.
+ *
+ * @param {string | null} path - The saved document's project-relative path; `null` for an unsaved
+ *   draft, which no scan would have seen either.
+ * @param {unknown} doc - The saved document.
+ * @returns {boolean} Whether the registry changed, so a caller knows to repaint what reads it.
+ */
+export function noteComponentSaved(path: string | null, doc: unknown): boolean {
+  if (!path) {
+    return false;
+  }
+  const index = componentRegistry.findIndex((c) => c.path === path);
+  const meta = componentMetaFrom(doc, path);
+  if (!meta) {
+    if (index === -1) {
+      return false;
+    }
+    componentRegistry.splice(index, 1);
+    return true;
+  }
+  const entry = meta as ComponentEntry;
+  if (index === -1) {
+    componentRegistry.push(entry);
+  } else {
+    componentRegistry[index] = entry;
+  }
+  return true;
+}
+
 /**
  * Build a fresh instance definition for a component: $props from prop defaults, plus the
  * component's slot fallback children cloned in as starting content so editors can edit from the