@jxsuite/studio 6.1.1 → 6.1.2

package/src/state.ts

@@ -12,7 +12,15 @@
  */
 
 import type { ProjectState } from "./types";
-import { displayTagName, isRef } from "@jxsuite/schema/guards";
+import {
+  displayTagName,
+  isBoolean,
+  isMappedArray,
+  isNonNullObject,
+  isNumber,
+  isRef,
+  isString,
+} from "@jxsuite/schema/guards";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export type JxPath = (string | number)[];
@@ -20,23 +28,10 @@ export type JxPath = (string | number)[];
 // ─── Path utilities ───────────────────────────────────────────────────────────
 
 /**
- * Walk the document tree and return the node at the given path.
- *
- * @param {JxMutableNode} doc
- * @param {JxPath} path
- * @returns {JxMutableNode}
+ * Walk the document tree and return the node at the given path, or `undefined` when a step falls
+ * off the tree (a path gone stale since it was taken). One walk, shared with the document ops.
  */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
-  let node = doc;
-  for (const key of path) {
-    if (node == null) {
-      return undefined as unknown as JxMutableNode;
-    }
-    // Paths address nodes by construction; non-node leaves surface as undefined above.
-    node = node[key] as JxMutableNode;
-  }
-  return node;
-}
+export { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 
 /**
  * The node's children when they are a static array (the edit-mode invariant); an empty array for
@@ -56,11 +51,11 @@ export function childList(node: JxMutableNode | null | undefined): (JxMutableNod
  * `$switch` cases. Runs once when a document is loaded into a tab so every in-studio doc — and its
  * history checkpoints — uses the member form before any mutation.
  *
- * @param {unknown} node
- * @returns {unknown} The same node (mutated)
+ * @param {T} node
+ * @returns {T} The same node (mutated)
  */
-export function normalizeArrayChildren(node: unknown): unknown {
-  if (!node || typeof node !== "object") {
+export function normalizeArrayChildren<T>(node: T): T {
+  if (!isNonNullObject(node)) {
     return node;
   }
   if (Array.isArray(node)) {
@@ -69,14 +64,12 @@ export function normalizeArrayChildren(node: unknown): unknown {
     }
     return node;
   }
+  /* SAFETY: A non-array object reached from a document root, a children array, a repeater `map` or
+     a `$switch` case is a node definition, and JxMutableNode is the editor's open node shape. */
   const n = node as JxMutableNode;
   const { children } = n;
-  if (
-    children &&
-    typeof children === "object" &&
-    !Array.isArray(children) &&
-    (children as JxMutableNode).$prototype === "Array"
-  ) {
+  if (isMappedArray(children)) {
+    // SAFETY: A legacy whole-children repeater is the same repeater node that becomes the member.
     n.children = [children as JxMutableNode];
   }
   if (Array.isArray(n.children)) {
@@ -84,10 +77,10 @@ export function normalizeArrayChildren(node: unknown): unknown {
       normalizeArrayChildren(child);
     }
   }
-  if (n.$prototype === "Array" && n.map && typeof n.map === "object") {
+  if (n.$prototype === "Array" && isNonNullObject(n.map)) {
     normalizeArrayChildren(n.map);
   }
-  if (n.cases && typeof n.cases === "object") {
+  if (isNonNullObject(n.cases)) {
     for (const caseDef of Object.values(n.cases)) {
       normalizeArrayChildren(caseDef);
     }
@@ -209,7 +202,7 @@ function collectRows(
   skipSelf: boolean,
 ): void {
   // Text node children: bare primitives get a "text" row
-  if (typeof doc === "string" || typeof doc === "number" || typeof doc === "boolean") {
+  if (isString(doc) || isNumber(doc) || isBoolean(doc)) {
     if (!skipSelf) {
       out.push({ depth, node: doc, nodeType: "text", path });
     }
@@ -220,13 +213,13 @@ function collectRows(
   // Recurse into its single template at `[...path, "map"]`. This is reached both when the array is
   // A member of a children array (path `[…, "children", i]`) and the legacy whole-children form
   // (path `[…, "children"]`).
-  if ((doc as JxMutableNode).$prototype === "Array") {
+  if (doc.$prototype === "Array") {
     if (!skipSelf) {
       out.push({ depth, node: doc, nodeType: "map", path });
     }
-    const mapDef = (doc as JxMutableNode).map;
-    if (mapDef && typeof mapDef === "object") {
-      collectRows(mapDef as JxMutableNode, [...path, "map"], depth + 1, out, false);
+    const mapDef = doc.map;
+    if (isNonNullObject(mapDef)) {
+      collectRows(mapDef, [...path, "map"], depth + 1, out, false);
     }
     return;
   }
@@ -247,36 +240,33 @@ function collectRows(
       const childPath = [...path, "children", i];
       collectRows(children[i]!, childPath, depth + 1, out, false);
     }
-  } else if (
-    children &&
-    typeof children === "object" &&
-    (children as JxMutableNode).$prototype === "Array"
-  ) {
+  } else if (isMappedArray(children)) {
     // Legacy whole-children repeater: the array occupies the children slot itself.
+    // SAFETY: The repeater in the children slot is the same repeater node a children member is.
     collectRows(children as JxMutableNode, [...path, "children"], depth + 1, out, false);
   }
 
   // $switch — emit each case as a virtual child
-  if (doc.$switch && doc.cases && typeof doc.cases === "object") {
+  if (doc.$switch && isNonNullObject(doc.cases)) {
     for (const [caseName, caseDef] of Object.entries(doc.cases)) {
       const casePath = [...path, "cases", caseName];
-      if (caseDef && typeof caseDef === "object" && (caseDef as JxMutableNode).$ref) {
+      if (isNonNullObject(caseDef) && caseDef.$ref) {
         out.push({
           depth: depth + 1,
-          node: caseDef as JxMutableNode,
+          node: caseDef,
           nodeType: "case-ref",
           path: casePath,
         });
-      } else if (caseDef && typeof caseDef === "object") {
+      } else if (isNonNullObject(caseDef)) {
         out.push({
           depth: depth + 1,
-          node: caseDef as JxMutableNode,
+          node: caseDef,
           nodeType: "case",
           path: casePath,
         });
         // Recurse into case children — skipSelf, because the "case" row above already stands in for
         // The case node itself (with its own nodeType).
-        collectRows(caseDef as JxMutableNode, casePath, depth + 2, out, true);
+        collectRows(caseDef, casePath, depth + 2, out, true);
       }
     }
   }
@@ -285,10 +275,10 @@ function collectRows(
 /**
  * Get a display label for a node (for layers + overlays).
  *
- * @param {JxMutableNode | null} node
+ * @param {JxMutableNode | null | undefined} node
  * @returns {string}
  */
-export function nodeLabel(node: JxMutableNode | null) {
+export function nodeLabel(node: JxMutableNode | null | undefined) {
   if (!node) {
     return "?";
   }
@@ -306,14 +296,14 @@ export function nodeLabel(node: JxMutableNode | null) {
   }
   if (node.tagName === "slot") {
     const name = node.attributes?.name;
-    return typeof name === "string" && name.trim() ? `slot: ${name.trim()}` : "slot";
+    return isString(name) && name.trim() ? `slot: ${name.trim()}` : "slot";
   }
   /* `displayTagName`, because a tag may be CHOSEN rather than written: this label reached the
      Outline row, the Inspector's header and the jump bar, and a raw read rendered `[object Object]`
      in all three. `a|div` is the honest answer — one element, tag decided at creation. */
   const tag = displayTagName(node.tagName) || "div";
   const suffix = node.$switch ? " ⇆" : "";
-  if (typeof node.textContent === "string" && node.textContent.length > 0) {
+  if (isString(node.textContent) && node.textContent.length > 0) {
     return `${tag} — ${node.textContent.slice(0, 24)}${suffix}`;
   }
   return tag + suffix;
@@ -340,5 +330,7 @@ export function setProjectState(ps: ProjectState | null) {
  * @returns {ProjectState}
  */
 export function requireProjectState() {
+  /* SAFETY: The contract above restricts callers to paths reached after `setProjectState` installed
+     a project (a project command, a panel that only mounts with one open); nothing here checks it. */
   return projectState as ProjectState;
 }

package/src/store.ts

@@ -9,9 +9,10 @@
 
 // ─── Re-exports from state.js ────────────────────────────────────────────────
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import { INPUT_DEBOUNCE } from "./ui/timing";
 import type { JxPath } from "./state";
-import type { Tab } from "./tabs/tab";
+import type { Tab, TabUi } from "./tabs/tab";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export {
@@ -36,18 +37,38 @@ export {
    each of which meant "the pane I am acting on" and got "the pane that happens to be focused". A
    stage belongs to a pane (`canvas/canvas-surface.ts`), a pane's cell is built by
    `panels/pane-grid.ts`, and every one of those readers now takes its surface. */
-export let activityBar = null as unknown as HTMLElement;
-export let leftPanel = null as unknown as HTMLElement;
-export let rightPanel = null as unknown as HTMLElement;
-export let toolbarEl = null as unknown as HTMLElement;
-export let statusbarEl = null as unknown as HTMLElement;
+
+/* Null until `initShellRefs()`, which `studio.ts` calls at boot right after mounting the shell
+   document; a render asked for before that (a test, or a command run ahead of the shell) reads null. */
+export let activityBar: HTMLElement | null = null;
+export let leftPanel: HTMLElement | null = null;
+export let rightPanel: HTMLElement | null = null;
+export let toolbarEl: HTMLElement | null = null;
+export let statusbarEl: HTMLElement | null = null;
+
+/** The shell region whose `id` is given, or null when the mounted shell has none. */
+function shellRef(id: string): HTMLElement | null {
+  const element = document.querySelector(`#${id}`);
+  return element instanceof HTMLElement ? element : null;
+}
 
 export function initShellRefs() {
-  activityBar = document.querySelector("#activity-bar") as HTMLElement;
-  leftPanel = document.querySelector("#left-panel") as HTMLElement;
-  rightPanel = document.querySelector("#right-panel") as HTMLElement;
-  toolbarEl = document.querySelector("#toolbar") as HTMLElement;
-  statusbarEl = document.querySelector("#statusbar") as HTMLElement;
+  activityBar = shellRef("activity-bar");
+  leftPanel = shellRef("left-panel");
+  rightPanel = shellRef("right-panel");
+  toolbarEl = shellRef("toolbar");
+  statusbarEl = shellRef("statusbar");
+}
+
+/**
+ * A shell region for a caller that cannot work without it. Reading one before `initShellRefs()` has
+ * found it is a boot-order bug, so it throws a TypeError that names the region.
+ */
+export function requireShellRef(ref: HTMLElement | null, id: string): HTMLElement {
+  if (!ref) {
+    throw new TypeError(`#${id} is not in the shell yet; initShellRefs() has not found it`);
+  }
+  return ref;
 }
 
 // ─── Shared constants ────────────────────────────────────────────────────────
@@ -130,6 +151,11 @@ export { stripEventHandlers } from "./utils/strip-events";
 
 const _renderers = new Map<string, () => void>();
 
+/** Whether a renderer's return value is a thenable — an `async` renderer that is still painting. */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (isNonNullObject(value) || isFunction(value)) && "then" in value && isFunction(value.then);
+}
+
 /**
  * How many registered renderers are mid-paint right now.
  *
@@ -154,9 +180,9 @@ function runRenderer(name: string, fn: () => void) {
   };
   let pending: PromiseLike<unknown> | null = null;
   try {
-    const result = fn() as unknown;
-    if (typeof (result as PromiseLike<unknown> | null)?.then === "function") {
-      pending = result as PromiseLike<unknown>;
+    const result = fn();
+    if (isThenable(result)) {
+      pending = result;
     }
   } catch (error) {
     console.error(`Renderer "${name}" failed:`, error);
@@ -165,7 +191,7 @@ function runRenderer(name: string, fn: () => void) {
     done();
     return;
   }
-  pending.then(done, (error: unknown) => {
+  pending.then(done, (error) => {
     console.error(`Renderer "${name}" failed:`, error);
     done();
   });
@@ -232,8 +258,8 @@ export function updateSession(
     selection?: JxPath[];
     hover?: JxPath | null;
     clipboard?: JxMutableNode | null;
-    ui?: Record<string, unknown>;
-    canvas?: Record<string, unknown>;
+    ui?: Partial<TabUi>;
+    canvas?: Partial<Tab["session"]["canvas"]>;
   },
 ) {
   if (tab) {
@@ -241,20 +267,16 @@ export function updateSession(
       tab.session.selection = patch.selection;
     }
     if (patch.hover !== undefined) {
-      tab.session.hover = patch.hover as JxPath | null;
+      tab.session.hover = patch.hover;
     }
     if (patch.clipboard !== undefined) {
-      tab.session.clipboard = patch.clipboard!;
+      tab.session.clipboard = patch.clipboard;
     }
     if (patch.ui) {
-      for (const [k, v] of Object.entries(patch.ui)) {
-        (tab.session.ui as unknown as Record<string, unknown>)[k] = v;
-      }
+      Object.assign(tab.session.ui, patch.ui);
     }
     if (patch.canvas) {
-      for (const [k, v] of Object.entries(patch.canvas)) {
-        (tab.session.canvas as unknown as Record<string, unknown>)[k] = v;
-      }
+      Object.assign(tab.session.canvas, patch.canvas);
     }
   }
 }
@@ -263,12 +285,12 @@ export function updateSession(
  * Update a single UI field on `tab`.
  *
  * @param {Tab | null} tab — the tab this field belongs to. `null` is a no-op.
- * @param {string} field
- * @param {unknown} value
+ * @param {K} field
+ * @param {TabUi[K]} value
  */
-export function updateUi(tab: Tab | null, field: string, value: unknown) {
+export function updateUi<K extends keyof TabUi>(tab: Tab | null, field: K, value: TabUi[K]) {
   if (tab) {
-    (tab.session.ui as unknown as Record<string, unknown>)[field] = value;
+    tab.session.ui[field] = value;
   }
 }
 
@@ -276,12 +298,10 @@ export function updateUi(tab: Tab | null, field: string, value: unknown) {
  * Update `tab`'s canvas async state (status, scope, error).
  *
  * @param {Tab | null} tab — the tab whose stage produced this state. `null` is a no-op.
- * @param {object} patch
+ * @param {Partial<Tab["session"]["canvas"]>} patch
  */
-export function updateCanvas(tab: Tab | null, patch: Record<string, unknown>) {
+export function updateCanvas(tab: Tab | null, patch: Partial<Tab["session"]["canvas"]>) {
   if (tab) {
-    for (const [k, v] of Object.entries(patch)) {
-      (tab.session.canvas as Record<string, unknown>)[k] = v;
-    }
+    Object.assign(tab.session.canvas, patch);
   }
 }

package/src/studio.ts

@@ -21,6 +21,7 @@ import {
   registerRenderer,
   render,
   requireProjectState,
+  requireShellRef,
   setProjectState,
   toolbarEl,
   updateSession,
@@ -117,13 +118,12 @@ import {
 import {
   loadProject as _loadProject,
   openProject as _openProject,
-  renderFilesTemplate,
   findHomePage,
   loadDirectory,
+  loadProjectDirectories,
   openFileInPane,
   openFileInTab,
   openLastSessionOrHome,
-  registerFileTreeDnD,
   reloadCleanTab,
   reloadTabsIfChanged,
 } from "./files/files";
@@ -136,9 +136,7 @@ import {
   configureCollabParser,
   configureCollabSerializer,
 } from "./collab/collab-session";
-import { renderImportsTemplate } from "./panels/imports-panel";
-import { invalidateLayoutPickerCache, renderHeadTemplate } from "./panels/head-panel";
-import { exportCemManifest as _exportCemManifest } from "./services/cem-export";
+import { invalidateLayoutPickerCache } from "./panels/head-panel";
 import { installAutomationHook } from "./services/automation";
 import { invalidateLibrary } from "./browse/library-pane";
 import { invalidateMediaCache } from "./ui/media-picker";
@@ -175,7 +173,6 @@ import {
   cloneRepository,
   loadDiffForLens,
   registerSourceControlCommands,
-  renderGitPanel,
   noteFileSaved,
 } from "./panels/git-panel";
 
@@ -191,7 +188,7 @@ import { chordsInScopes } from "./commands/keymap";
 import { FRAME_KEY_SCOPES } from "./canvas/iframe-keys";
 import { createLiveContext } from "./commands/live-context";
 import { hasAiCredentials } from "./services/ai-models";
-import { mount as mountActivityBar } from "./surfaces/rail";
+import { mount } from "./surfaces/rail";
 import * as toolbarPanel from "./surfaces/commandbar";
 import * as overlaysPanel from "./panels/overlays";
 import * as frontmatterPanelMod from "./panels/frontmatter-panel";
@@ -268,7 +265,7 @@ import { registerI18nCommands } from "./i18n/i18n-commands";
 import { convertToComponent } from "./editor/convert-to-component";
 import type { GitDiffState } from "./types";
 import type { Tab } from "./tabs/tab";
-import type { JxDocument, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
+import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 import { setBundleBase } from "./services/bundle-base";
 import { mountBootFailureTree, mountShellTree } from "./shell/tree";
 
@@ -499,7 +496,7 @@ initShellRefs();
 mountShell();
 
 // Mount extracted panel modules
-toolbarPanel.mount(toolbarEl, {
+toolbarPanel.mount(requireShellRef(toolbarEl, "toolbar"), {
   closeFunctionEditor: () => closeFunctionEditor(),
   getCanvasMode,
   openProject: () => openProject(),
@@ -641,9 +638,8 @@ window.addEventListener("beforeunload", (e: BeforeUnloadEvent) => {
   // Author may cancel the close, and the record is the same either way.
   flushSession();
   if (hasUnsavedTabs()) {
+    // The HTML standard's trigger for the leave-page prompt; the legacy `returnValue` is deprecated.
     e.preventDefault();
-    // Legacy browsers require a truthy returnValue to trigger the native confirm prompt.
-    e.returnValue = "";
   }
 });
 
@@ -743,11 +739,8 @@ function installPaneRenderEffects(paneId: string): void {
   installDerivationEffects(paneId, derivationDeps);
   effect(() => {
     const tab = tabOfPane(paneId);
-    if (tab) {
-      const doc = tab.doc.document;
-      if (doc && consumePatchedDocument(doc, paneId)) {
-        return;
-      }
+    if (tab && consumePatchedDocument(tab.doc.document, paneId)) {
+      return;
     }
     scheduleCanvasRender(paneId);
   });
@@ -871,7 +864,6 @@ leftPanelMod.mount({
   navigateToComponent,
   registerComponentsDnD,
   registerElementsDnD,
-  registerFileTreeDnD,
   registerLayersDnD,
   renderCanvas: () => renderCanvas(),
   // The Data panel's Refresh: a canvas re-render that ALSO lets automatic `Request` state entries
@@ -894,10 +886,6 @@ leftPanelMod.mount({
     }
     renderCanvas(paneId);
   },
-  renderFilesTemplate,
-  renderGitPanel,
-  renderHeadTemplate,
-  renderImportsTemplate,
   mountSignalsPanel,
   setCanvasMode,
   setGitDiffState: (state: GitDiffState | null) => {
@@ -919,7 +907,7 @@ renderStatusbar();
 // The status bar mounts the jump bar too: the focused pane's breadcrumb trail is its DOCUMENT
 // Field, and the only breadcrumb in the shell.
 mountStatusbar();
-mountActivityBar();
+mount();
 
 /* The background-click deselect moved into `editor/shortcuts.ts`'s `installStageGestures`, beside
    the wheel and the middle-drag, because it is a STAGE gesture: it compared against the app's one
@@ -983,10 +971,10 @@ if (!_projectParam) {
   const _bootPlatform = getPlatform();
   // oxlint-disable-next-line unicorn/prefer-top-level-await -- fire-and-forget: must not block the initial render
   void _bootPlatform
-    .activate?.()
+    .activate()
     // No project is bound yet, so this call only warms the canvasUrl; a backend that refuses it
     // Still gets the render below rather than an unhandled rejection.
-    ?.catch((error: unknown) => {
+    .catch((error) => {
       // A refusal that offers an action is the action flow's to explain; it is not a fault.
       if (!isActionRequired(error)) {
         console.error("Boot activation failed:", error);
@@ -1018,18 +1006,14 @@ if (_projectParam) {
       // Report a bare `Error: <message>` because the only identifying fact was still block-scoped.
       let fileRelPath = _urlParams.get("file") || _projectParam;
       try {
-        const siteCtx = platform.resolveSiteContext
-          ? await platform.resolveSiteContext(_projectParam)
-          : { sitePath: null };
+        const siteCtx = await platform.resolveSiteContext(_projectParam);
 
         if (siteCtx.sitePath) {
           // Set PAL project root to absolute path so file ops work
           if (siteCtx.sitePath) {
             platform.projectRoot = siteCtx.sitePath;
             // Await activation so the server resolves project-relative static files
-            if (platform.activate) {
-              await platform.activate();
-            }
+            await platform.activate();
           }
 
           resetIgnoreCache();
@@ -1053,31 +1037,9 @@ if (_projectParam) {
           await ensureDependenciesInstalled();
           await loadComponentRegistry();
 
-          // Load directory tree and populate projectDirs from conventional dirs found
-          const conventionalDirs = new Set([
-            "pages",
-            "layouts",
-            "components",
-            "content",
-            "data",
-            "public",
-            "styles",
-          ]);
-          /* Through `loadDirectory`, not `platform.listDirectory`: this is the second copy of the
-             conventional-dir walk (the first is `openProject` in files/files.ts), and the loader is
-             what reads the `.gitignore` chain governing each directory. Listing around it left the
-             `?project=` boot as the one door into a project whose tree knew no ignore rules. */
-          await loadDirectory(".");
-          const dirEntries = requireProjectState().dirs.get(".") ?? [];
-          const foundDirs = [];
-          for (const e of dirEntries) {
-            if (e.type === "directory" && conventionalDirs.has(e.name)) {
-              foundDirs.push(e.name);
-              requireProjectState().expanded.add(e.path || e.name);
-              await loadDirectory(e.path || e.name);
-            }
-          }
-          requireProjectState().projectDirs = foundDirs;
+          /* Through `loadDirectory` (inside `loadProjectDirectories`), not `platform.listDirectory`:
+             the loader is what reads the `.gitignore` chain governing each directory. */
+          await loadProjectDirectories();
           void maybePromptJxsuiteUpdate(siteCtx.sitePath);
         }
 
@@ -1144,7 +1106,7 @@ if (_projectParam) {
           openTab({
             id: fileRelPath,
             documentPath: fileRelPath,
-            document: parsedDoc as JxMutableNode,
+            document: parsedDoc,
             ...(frontmatter != null && { frontmatter }),
             layout,
             sourceFormat: fileFormat?.name ?? null,
@@ -1365,6 +1327,9 @@ async function openRecentProject(root: string) {
     void loadFormats();
     refreshExtensionUi(platform);
     const content = await platform.readFile("project.json");
+    /* SAFETY: This is `project.json` at the root the user chose to open, the project's own config
+       file whose schema is ProjectConfig; Studio edits it in that shape and does not re-validate it
+       on open, as the folder-picker path in `platforms/devserver.ts` does not either. */
     const config = JSON.parse(content) as ProjectConfig;
 
     closeAllTabs();
@@ -1389,26 +1354,9 @@ async function openRecentProject(root: string) {
     activity.step("Install dependencies");
     await ensureDependenciesInstalled();
     activity.step("Read the project");
-    await loadDirectory(".");
+    await loadProjectDirectories();
     await loadComponentRegistry();
 
-    const conventionalDirs = new Set([
-      "pages",
-      "layouts",
-      "components",
-      "content",
-      "data",
-      "public",
-      "styles",
-    ]);
-    const entries = requireProjectState().dirs.get(".") || [];
-    for (const e of entries) {
-      if (e.type === "directory" && conventionalDirs.has(e.name)) {
-        requireProjectState().expanded.add(e.path || e.name);
-        await loadDirectory(e.path || e.name);
-      }
-    }
-
     addRecentProject(requireProjectState().name, root);
     setActivityTab("files");
     renderLeftPanel();
@@ -1561,7 +1509,9 @@ const liveChrome = createLiveSurfaceSaver({
    registry reactively. */
 setDocumentSavedListener((path, doc) => {
   void noteFileSaved(path);
-  void liveChrome(path, doc as unknown as JxDocument);
+  /* SAFETY: The listener fires for a tab's saved ROOT document, and a root document is a
+     JxDocument held in the editor's mutable node form; `liveChrome` only acts on surface paths. */
+  void liveChrome(path, doc as JxDocument);
   if (noteComponentSaved(path, doc)) {
     renderPropertiesPanel();
     renderLeftPanel();

package/src/style/live-preview.ts

@@ -32,5 +32,5 @@ import { activeTab } from "../workspace/workspace";
 export function pushProjectStylesToCanvas(): void {
   postSiteStyleToLiveHosts();
   const style = transposeStylebookStyle(getEffectiveStyle(activeTab.value?.doc.document?.style));
-  postStyleUpdateToStylebookHosts(style as Record<string, unknown>);
+  postStyleUpdateToStylebookHosts(style);
 }

package/src/style/project-styles.ts

@@ -24,6 +24,7 @@
  * `style["--token"]` and `style["@--ctx"]["--token"]` shapes the compiler already consumes.
  */
 
+import { ensureNestedStyle, getNestedStyle, isNumber, isString } from "@jxsuite/schema/guards";
 import { parseMediaEntries, schemeOfQuery } from "../utils/canvas-media";
 import { varDisplayName } from "../utils/studio-utils";
 
@@ -140,7 +141,7 @@ export function listTokens(style: JxStyle | null | undefined): ProjectToken[] {
     if (!name.startsWith("--")) {
       continue;
     }
-    if (typeof value !== "string" && typeof value !== "number") {
+    if (!isString(value) && !isNumber(value)) {
       continue;
     }
     out.push({ group: groupIdOfToken(name), label: tokenLabel(name), name, value });
@@ -242,9 +243,8 @@ export interface TokenOverride {
  * @param {JxStyle} style
  * @param {TokenContext} context
  */
-function overrideBlock(style: JxStyle, context: TokenContext): Record<string, unknown> | undefined {
-  const block = style[context.key];
-  return block && typeof block === "object" ? (block as Record<string, unknown>) : undefined;
+function overrideBlock(style: JxStyle, context: TokenContext): JxStyle | undefined {
+  return getNestedStyle(style, context.key);
 }
 
 /**
@@ -261,7 +261,7 @@ export function readTokenOverride(
   token: string,
 ): string | number | undefined {
   const value = overrideBlock(style, context)?.[token];
-  return typeof value === "string" || typeof value === "number" ? value : undefined;
+  return isString(value) || isNumber(value) ? value : undefined;
 }
 
 /**
@@ -284,8 +284,7 @@ export function writeTokenOverride(
   value: string,
 ): void {
   if (value) {
-    const block = (style[context.key] ??= {}) as Record<string, unknown>;
-    block[token] = value;
+    ensureNestedStyle(style, context.key)[token] = value;
     return;
   }
   const block = overrideBlock(style, context);