@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/iframe-protocol.ts

@@ -12,16 +12,7 @@
 import type { AssetContext } from "./asset-resolve";
 import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxContentResult, SlashCommand } from "../editor/inline-edit";
-import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
-
-/**
- * The wire form of a value-carrying document op (the `forward` half of a recorded
- * {@link JxDocOpPair} — see {@link file://../tabs/patch-ops.ts}). It is structurally a
- * {@link JxDocOp}: it carries the inserted/replaced `node` and the set `value`, NOT just a path, so
- * the iframe can fold it into its shadow doc and re-render subtrees without ever reading the
- * parent's reactive document.
- */
-export type WireDocOp = JxDocOp;
+import type { JsonObject, JxExpressionNode, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
 export const CANVAS_MODES = ["preview", "design", "edit", "stylebook", "git-diff"] as const;
 
@@ -37,7 +28,7 @@ export const CANVAS_MODES = ["preview", "design", "edit", "stylebook", "git-diff
 export type CanvasMode = (typeof CANVAS_MODES)[number];
 
 export function isCanvasMode(value: unknown): value is CanvasMode {
-  return typeof value === "string" && (CANVAS_MODES as readonly string[]).includes(value);
+  return typeof value === "string" && CANVAS_MODES.some((mode) => mode === value);
 }
 
 /**
@@ -86,6 +77,12 @@ export interface WireDiffMark {
 /** An artboard's whole mark set. Each side receives only its own; `[]` clears. */
 export type WireDiffMarks = readonly WireDiffMark[];
 
+/** A language as the frame applies it: the BCP 47 tag for `lang`, and its direction for `dir`. */
+export interface WireLocale {
+  locale: string;
+  dir: "ltr" | "rtl";
+}
+
 /** Messages the editor (parent) sends into the canvas iframe. */
 export type ParentToIframe =
   | { kind: "init"; gen: number }
@@ -121,7 +118,7 @@ export type ParentToIframe =
        */
       assets?: AssetContext | null;
       mapperCtx: WireMapperCtx;
-      siteStyle: Record<string, unknown> | null;
+      siteStyle: JxStyle | null;
       // Forced color-scheme preview (spec.md §9.5): "light"/"dark" sets data-color-scheme on the
       // Iframe root, null clears it (auto — follow the OS).
       colorScheme: "light" | "dark" | null;
@@ -144,6 +141,13 @@ export type ParentToIframe =
        * every re-render would close the panel the author is editing.
        */
       popoverOpen?: (string | number)[] | null;
+      /**
+       * The language the artboard is drawn in, carried on `render` for `colorScheme`'s reason: a
+       * frame that boots after the pane's locale was posted (a new host, a reload) would otherwise
+       * draw an Arabic document left to right until the locale next CHANGED. Absent or null clears
+       * `lang` and `dir`.
+       */
+      locale?: WireLocale | null;
       /** The dialog to draw open after this render, for the same reason. */
       dialogOpen?: (string | number)[] | null;
       gen: number;
@@ -197,8 +201,10 @@ export type ParentToIframe =
    * 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.
+   * The host posts the language the pane DRAWS, not only an override: the preview choice, else the
+   * file's own, else the site default (`canvasLocaleOf`). `null` is a project that declares no
+   * locales: both attributes come off, and the frame falls back to whatever the rendered document
+   * declares.
    */
   | { kind: "setLocale"; locale: string | null; dir: "ltr" | "rtl" }
   /**
@@ -239,7 +245,7 @@ export type ParentToIframe =
   // Render-free; the superseding render carries the same style via its own siteStyle.
   | {
       kind: "siteStyleUpdate";
-      siteStyle: Record<string, unknown> | null;
+      siteStyle: JxStyle | null;
       media: Record<string, string>;
     }
   // Ask the iframe to measure the given document paths and post their current rects back. Used to
@@ -255,7 +261,12 @@ export type ParentToIframe =
   // In place. `gen` matches the last render so the iframe drops patches superseded by a re-render.
   | {
       kind: "patch";
-      forwardOps: WireDocOp[];
+      /**
+       * The `forward` halves of the recorded {@link JxDocOp} pairs (tabs/patch-ops.ts). Each carries
+       * the inserted/replaced `node` and the set `value`, not just a path, so the iframe folds it
+       * into its shadow doc without ever reading the parent's reactive document.
+       */
+      forwardOps: JxDocOp[];
       gen: number;
       /**
        * Paths whose DOM the RECIPIENT already has correct, because this patch is the echo of an
@@ -273,7 +284,7 @@ export type ParentToIframe =
   // Regenerates the whole scoped-CSS cascade (real @media included) without a re-render. `style` is
   // Already transposed parent-side (transposeStylebookStyle); `gen` must equal the iframe's
   // RenderedGen — a stale update is dropped (the superseding render carries the same style).
-  | { kind: "styleUpdate"; style: Record<string, unknown>; gen: number }
+  | { kind: "styleUpdate"; style: JxStyle; gen: number }
   // Enter inline editing on the node at `path` (used to re-enter after a split/insert re-renders).
   | {
       kind: "enterEdit";
@@ -381,10 +392,14 @@ export type DropInstructionType = "reorder-above" | "reorder-below" | "make-chil
 
 /**
  * The kind of thing being dragged. `tree-node` carries the source's existing document path (a
- * move); `block` carries nothing on the wire — its full `fragment` (a {@link JxMutableNode}) is
- * retained PARENT-SIDE keyed by `dragSeq` and never crosses the boundary.
+ * move); `block` carries only its fragment's tag on the wire — its full `fragment` (a
+ * {@link JxMutableNode}) is retained PARENT-SIDE keyed by `dragSeq` and never crosses the boundary.
+ * The tag is what lets the iframe keep a block out of a paragraph (`iframe-drop.ts`); an OS file
+ * drag has none, and is placed as a block.
  */
-export type DragSrcKind = { type: "tree-node"; path: (string | number)[] } | { type: "block" };
+export type DragSrcKind =
+  | { type: "tree-node"; path: (string | number)[] }
+  | { type: "block"; tag?: string };
 
 /**
  * A display-only drop preview the iframe posts on `dragOver`: where the drop indicator should draw
@@ -490,7 +505,7 @@ export type IframeToParent =
   // `S.canvas.scope` so the data-explorer panel shows live data instead of "pending" (the iframe,
   // 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: "dataScope"; gen: number; scope: JsonObject }
   // The frame's own quiescence, ANSWERED rather than polled (studio.md §13.5).
   // Nothing in the parent realm can see inside a cross-origin frame, so a parent that wanted to
   // Know whether the canvas had settled could only sleep. The frame samples itself at its own rAF

package/src/canvas/iframe-render.ts

@@ -37,8 +37,9 @@ import { classifyRenderNode, jxPathSelector, serializeJxPath } from "./path-mapp
 import { elementForPath } from "./iframe-position";
 import type { AssetContext } from "./asset-resolve";
 import { SITE_STYLE_ID, buildSiteStyleCSS } from "@jxsuite/site/site-style";
-import type { CanvasMode, WireDiffMarks } from "./iframe-protocol";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { CanvasMode, WireDiffMarks, WireLocale } from "./iframe-protocol";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocument, JxElement, JxStyle } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
 
 /**
@@ -61,18 +62,12 @@ export interface RenderHandle {
   ctx: IframeRenderCtx;
 }
 
-interface HeadEntry {
-  tagName?: string;
-  attributes?: Record<string, unknown>;
-  textContent?: string;
-}
-
 /**
  * Register the document's `$elements` (components) in this iframe realm so the runtime can render
  * them.
  */
 export async function registerElements(doc: JxDocument, docBase: string): Promise<void> {
-  const elements = (doc as { $elements?: unknown[] }).$elements;
+  const elements = doc.$elements;
   if (!Array.isArray(elements)) {
     return;
   }
@@ -81,13 +76,16 @@ export async function registerElements(doc: JxDocument, docBase: string): Promis
   await Promise.all(
     elements.map(async (entry) => {
       const task = (async () => {
-        if (typeof entry === "string") {
+        if (isString(entry)) {
           const specifier =
             entry.startsWith("/") || entry.startsWith(".") ? entry : `/node_modules/${entry}`;
           await import(specifier);
-        } else if (entry && typeof entry === "object" && "$ref" in entry) {
-          await defineElement(new URL(String((entry as { $ref: string }).$ref), docBase).href);
-        } else if (entry && typeof entry === "object") {
+        } else if (isNonNullObject(entry) && "$ref" in entry) {
+          await defineElement(new URL(String(entry.$ref), docBase).href);
+        } else if (isNonNullObject(entry)) {
+          /* SAFETY: an `$elements` entry that is neither a specifier nor a `$ref` is an inline
+           * component definition by the schema (JxDocument is JxElement with a literal tagName).
+           * A malformed one throws inside this task, which the race below catches and logs. */
           await defineElement(entry as JxDocument, docBase);
         }
       })();
@@ -633,6 +631,10 @@ export const STYLEBOOK_CSS = `
 .element-card-preview > * {
   max-width: 100%;
   margin: 0;
+}
+/* A list keeps its inline-start padding: its markers are drawn in it, and with none they are
+   clipped by the card ("1." shows as "."). Every other specimen sits flush in its card. */
+.element-card-preview > :not(ol, ul, menu) {
   padding: 0;
 }
 .element-card-preview > hr {
@@ -696,11 +698,11 @@ export function syncStylebookCss(doc: Document, mode: CanvasMode): void {
  * selectors can win (spec.md §9.5), and so removed tokens can't linger on reused iframes.
  */
 export function applySiteStyle(
-  siteStyle: Record<string, unknown> | null | undefined,
+  siteStyle: JxStyle | null | undefined,
   mediaQueries: Record<string, string> = {},
 ): void {
   const existing = document.head.querySelector(`#${SITE_STYLE_ID}`);
-  if (!siteStyle || typeof siteStyle !== "object") {
+  if (!siteStyle || !isNonNullObject(siteStyle)) {
     existing?.remove();
     return;
   }
@@ -730,6 +732,49 @@ export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark"
   }
 }
 
+/** The `lang` and `dir` a frame's root booted with, which a frame with no language goes back to. */
+export interface LocaleBaseline {
+  lang: string | null;
+  dir: string | null;
+}
+
+/** Read the root's `lang` and `dir` as the frame booted them (`canvas.html` is `lang="en"`). */
+export function captureLocaleBaseline(doc: Document): LocaleBaseline {
+  const root = doc.documentElement;
+  return { dir: root.getAttribute("dir"), lang: root.getAttribute("lang") };
+}
+
+/** Write one root attribute, or remove it for null. */
+function setRootAttribute(root: Element, name: string, value: string | null): void {
+  if (value === null) {
+    root.removeAttribute(name);
+  } else {
+    root.setAttribute(name, value);
+  }
+}
+
+/**
+ * Set the artboard's language (studio.md §20.2): `lang` and `dir` on the frame's root, the only
+ * writer of either. `dir` is what makes an RTL document actually mirror, and `lang` is what CSS's
+ * `:lang()` and the font stack select on. The root survives a render, which replaces only the
+ * container's children, so the value holds until the next one arrives.
+ *
+ * `null`, a project that declares no locales, restores the language the frame booted with rather
+ * than removing it, so applying the value on every render does not strip `canvas.html`'s
+ * `lang="en"` from every canvas of a monolingual project. A left-to-right language writes no
+ * `dir="ltr"`, as the built page never does (`site-architecture.md` §13.4): it restores the booted
+ * `dir`.
+ */
+export function applyPreviewLocale(
+  doc: Document,
+  locale: WireLocale | null,
+  baseline: LocaleBaseline,
+): void {
+  const root = doc.documentElement;
+  setRootAttribute(root, "lang", locale?.locale ?? baseline.lang);
+  setRootAttribute(root, "dir", locale?.dir === "rtl" ? "rtl" : baseline.dir);
+}
+
 /**
  * Draw the popover at `path` open, and every other one closed.
  *
@@ -746,15 +791,15 @@ export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark"
  * @docs studio/interface/canvas
  */
 export function applyCanvasPopoverOpen(root: ParentNode, path: string | null): void {
-  for (const el of root.querySelectorAll("[data-jx-popover-open]")) {
-    delete (el as HTMLElement).dataset.jxPopoverOpen;
+  for (const el of root.querySelectorAll<HTMLElement>("[data-jx-popover-open]")) {
+    delete el.dataset.jxPopoverOpen;
   }
   if (path === null) {
     return;
   }
-  const target = root.querySelector(`[data-jx-popover]${jxPathSelector(path)}`);
+  const target = root.querySelector<HTMLElement>(`[data-jx-popover]${jxPathSelector(path)}`);
   if (target) {
-    (target as HTMLElement).dataset.jxPopoverOpen = "";
+    target.dataset.jxPopoverOpen = "";
   }
 }
 
@@ -783,26 +828,27 @@ export function applyCanvasPopoverOpen(root: ParentNode, path: string | null): v
  * backdrop and all.
  */
 export function applyCanvasDialogOpen(root: ParentNode, path: string | null): void {
-  for (const el of root.querySelectorAll("[data-jx-dialog-open]")) {
-    delete (el as HTMLElement).dataset.jxDialogOpen;
+  for (const el of root.querySelectorAll<HTMLElement>("[data-jx-dialog-open]")) {
+    delete el.dataset.jxDialogOpen;
   }
   if (path === null) {
     return;
   }
-  const target = root.querySelector(`dialog${jxPathSelector(path)}`);
+  const target = root.querySelector<HTMLElement>(`dialog${jxPathSelector(path)}`);
   if (target) {
-    (target as HTMLElement).dataset.jxDialogOpen = "";
+    target.dataset.jxDialogOpen = "";
   }
 }
 
 /** Inject the document's `$head` (link/meta/script) into the iframe's <head>, de-duped by href/src. */
 export function injectHead(doc: JxDocument, assets: AssetContext | null = null): void {
-  const head = (doc as { $head?: HeadEntry[] }).$head;
+  const head = doc.$head;
   if (!Array.isArray(head)) {
     return;
   }
   for (const entry of head) {
-    if (!entry?.tagName) {
+    // A `$head` array read off disk can hold a null or a tagless entry; neither emits anything.
+    if (!isNonNullObject(entry) || !entry.tagName) {
       continue;
     }
     const tag = String(entry.tagName).toLowerCase();
@@ -810,10 +856,10 @@ export function injectHead(doc: JxDocument, assets: AssetContext | null = null):
     if (tag === "script" && !entry.attributes?.src) {
       continue;
     }
-    const attrs = { ...entry.attributes } as Record<string, unknown>;
+    const attrs = { ...entry.attributes };
     for (const key of ["href", "src"]) {
       const val = attrs[key];
-      if (typeof val !== "string" || val === "") {
+      if (!isString(val) || val === "") {
         continue;
       }
       if (!val.startsWith("/") && !val.startsWith(".") && !val.startsWith("http")) {
@@ -833,7 +879,7 @@ export function injectHead(doc: JxDocument, assets: AssetContext | null = null):
       el.setAttribute(k, String(v));
     }
     if (entry.textContent) {
-      el.textContent = entry.textContent;
+      el.textContent = String(entry.textContent);
     }
     document.head.append(el);
   }
@@ -856,7 +902,7 @@ export function makeStamper(ctx: PathMapCtx) {
       (island) => path.length > island.length && island.every((seg, i) => path[i] === seg),
     );
 
-  return (created: Node, path: (string | number)[], def: unknown) => {
+  return (created: Node, path: (string | number)[], def: JxElement | string) => {
     if (!(created instanceof HTMLElement)) {
       return;
     }
@@ -866,7 +912,10 @@ export function makeStamper(ctx: PathMapCtx) {
     // Editable tree and re-render a live instance with default state. Mark the root so the
     // Runtime's element class leaves it alone (see defineElement's connectedCallback guard).
     const isDefinitionRoot =
-      path.length === 0 && (def as { tagName?: string } | null)?.tagName?.includes("-");
+      path.length === 0 &&
+      isNonNullObject(def) &&
+      isString(def.tagName) &&
+      def.tagName.includes("-");
     if (isDefinitionRoot) {
       created.dataset.jxDefinitionRoot = "";
     }
@@ -984,7 +1033,7 @@ export async function renderResolvedDocument(opts: {
   docBase: string;
   mode: CanvasMode;
   mapperCtx: PathMapCtx;
-  siteStyle?: Record<string, unknown> | null;
+  siteStyle?: JxStyle | null;
   /**
    * How this host addresses project media, or null when the canvas origin serves the site's own URL
    * space (desktop, `jx dev`) and references need no resolution at all.
@@ -1037,7 +1086,7 @@ export async function renderResolvedDocument(opts: {
   // Iframe clears it (page-level templates are inert in design/edit via prepareForEditMode, so only
   // Component internals get stamped).
   setStampPropBindings(opts.mode === "design" || opts.mode === "edit");
-  applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
+  applySiteStyle(opts.siteStyle, opts.doc.$media ?? {});
   injectHead(opts.doc, assets);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
   // The substitute rules for the attributes the de-link above renamed. Same predicate as the
@@ -1052,7 +1101,7 @@ export async function renderResolvedDocument(opts: {
   // But no own `$media` resolves the breakpoint to its real query (the iframe path calls buildScope
   // Directly and never the runtime's `Jx()` entry, which is the only other place _rootMedia is set).
   // Set it every render (even to `{}`) so a stale map from a previous document cannot leak.
-  setRootMedia((opts.doc as { $media?: Record<string, string> }).$media ?? {});
+  setRootMedia(opts.doc.$media ?? {});
   // Register components BEFORE renderNode. The runtime only applies a custom element's `$props` when
   // That element is ALREADY defined (renderNode gates renderCustomElementWithProps on a truthy
   // `customElements.get(tagName)`); if we register after render, every component paints with its
@@ -1066,8 +1115,8 @@ export async function renderResolvedDocument(opts: {
   // The scope MUST be the runtime's (runScoped): renderNode creates its binding effects with the
   // Runtime's copy of @vue/reactivity, and scope collection is per module instance — a studio
   // EffectScope here collects nothing and dispose() would leak every effect of this render.
-  const { result: el, stop } = runScoped(
-    () => renderNode(opts.doc, $defs, { _path: [], onNodeCreated }) as HTMLElement,
+  const { result: el, stop } = runScoped(() =>
+    renderNode(opts.doc, $defs, { _path: [], onNodeCreated }),
   );
   opts.container.replaceChildren(el);
   applyCanvasPopoverOpen(opts.container, opts.popoverOpen ?? null);

package/src/canvas/iframe-slash.ts

@@ -21,7 +21,17 @@ import type { IframeToParent, ParentToIframe } from "./iframe-protocol";
 
 type SlashNavKey = Extract<IframeToParent, { kind: "slashNav" }>["key"];
 
-const NAV_KEYS = new Set(["ArrowUp", "ArrowDown", "Enter", "Escape"]);
+const NAV_KEYS = new Set<string>([
+  "ArrowUp",
+  "ArrowDown",
+  "Enter",
+  "Escape",
+] satisfies SlashNavKey[]);
+
+/** Whether `key` is one of the four keys the parent menu navigates by. */
+function isNavKey(key: string): key is SlashNavKey {
+  return NAV_KEYS.has(key);
+}
 
 /**
  * Register the bridge SlashController for this iframe realm and wire its keyboard/dismissal
@@ -55,28 +65,31 @@ export function startIframeSlashBridge(
       open = true;
       lastPostedFilter = filter;
       const r = rectOf(anchorEl);
-      channel.post({
+      const message: Extract<IframeToParent, { kind: "slashShow" }> = {
         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 } : {}),
-      });
+      };
+      /* 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. */
+      if (cbs.showFilter === true) {
+        message.showFilter = true;
+      }
+      channel.post(message);
     },
   };
   setSlashController(controller);
 
   const onKeyDown = (e: KeyboardEvent) => {
-    if (!open || !NAV_KEYS.has(e.key)) {
+    if (!open || !isNavKey(e.key)) {
       return;
     }
     e.preventDefault();
     e.stopPropagation();
-    channel.post({ key: e.key as SlashNavKey, kind: "slashNav" });
+    channel.post({ key: e.key, kind: "slashNav" });
   };
   const onMouseDown = () => {
     // The parent menu's outside-click listener can't see iframe clicks — any in-iframe press while

package/src/canvas/iframe-subtree.ts

@@ -12,9 +12,10 @@
  */
 
 import { releaseElementStyles, renderNode, runScoped } from "@jxsuite/runtime";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import { getNodeAtPath } from "../state";
 import { makeStamper } from "./iframe-render";
-import { prepareForEditMode } from "../utils/edit-display";
+import { prepareForEditMode, sampleRowAt } from "../utils/edit-display";
 import { stripEventHandlers } from "../utils/strip-events";
 import type { IframeRenderCtx } from "./iframe-render";
 import type { JxPath } from "../state";
@@ -39,11 +40,17 @@ export function renderSubtreeIframe(
   docPath: JxPath,
   ctx: IframeRenderCtx,
 ): HTMLElement | Text {
+  /* SAFETY: a widening of getNodeAtPath's declared return. A patch path addresses an entry of a
+   * `children` array, which the schema types as `JxMutableNode | string`, and a missing step
+   * answers undefined, so those three cases are the whole range. */
   const node = getNodeAtPath(shadowDoc, docPath) as JxMutableNode | string | undefined;
   if (node === undefined) {
     throw new Error(`iframe-patch-node-not-found:${docPath.join("/")}`);
   }
-  const def = typeof node === "string" ? node : prepareForEditMode(stripEventHandlers(node));
+  // Inside a repeater, the template is drawn with the sample row the full render used.
+  const def = isString(node)
+    ? node
+    : prepareForEditMode(stripEventHandlers(node), sampleRowAt(shadowDoc, docPath));
   const { result: rendered, stop } = runScoped(() =>
     renderNode(def, ctx.defs, {
       _path: docPathToRenderPath(docPath, ctx),
@@ -98,7 +105,7 @@ function docPathToRenderPath(docPath: JxPath, ctx: IframeRenderCtx): (string | n
   const { mapperCtx } = ctx;
   if (mapperCtx.layoutWrapped && mapperCtx.pageContentPrefix && docPath[0] === "children") {
     const [, idx] = docPath;
-    return typeof idx === "number"
+    return isNumber(idx)
       ? [
           ...mapperCtx.pageContentPrefix,
           idx + (mapperCtx.pageContentOffset ?? 0),

package/src/canvas/npm-modules.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a live render imports an `npm:` package from (spec.md §5.3, 4c).
+ *
+ * The dev server answers `/node_modules/<package>/<subpath>` by resolving the package's `exports`
+ * and bundling the entry on demand (`@jxsuite/server`), the same URL space a bare `$elements`
+ * specifier and a bare `$head` asset are already fetched from. Both realms that render a project
+ * live install it into the runtime (`setNpmModuleResolver`): the canvas frame against its own
+ * address, and the editor window, which draws the Site panel's and the Content home's previews,
+ * against the project's asset origin.
+ *
+ * Dependency-free so it rides in the slim canvas bundle.
+ */
+
+/**
+ * The URL a package specifier is imported from, under `base`.
+ *
+ * @param specifier - `@scope/pkg/subpath`, as the document wrote it after `npm:`
+ * @param base - The origin (or any URL on it) that serves the project
+ */
+export function npmModuleUrl(specifier: string, base: string): string {
+  return new URL(`/node_modules/${specifier}`, base).href;
+}

package/src/canvas/path-mapping.ts

@@ -11,6 +11,8 @@
  * result for the `data-jx-path` attribute.
  */
 
+import { isJsonObject, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 
 /**
@@ -83,22 +85,27 @@ export function wrapsPageContent(path: JxPath, prefix: JxPath | null): boolean {
  * 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 `data-jx-*` attributes.
  */
-export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx): RenderNodeClass {
+export function classifyRenderNode(
+  path: JxPath,
+  def: JxElement | string,
+  ctx: PathMapCtx,
+): RenderNodeClass {
   // 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;
+  const marker = ctx.layoutWrapped && isNonNullObject(def) ? def["$__layout"] : undefined;
   if (marker) {
-    const origin = (typeof marker === "object" ? marker : {}) as Partial<LayoutMarker>;
+    // A legacy bare `true` marker carries no origin, so it reads as an empty one.
+    const origin = isJsonObject(marker) ? marker : {};
+    const { file, path: originPath } = origin;
     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 : [],
+      layoutFile: isString(file) ? file : "",
+      /* SAFETY: markLayoutNodes (canvas-live-render.ts) is the only writer of `$__layout`, and the
+       * `path` it stamps is a LayoutMarker's JxPath. */
+      layoutPath: Array.isArray(originPath) ? (originPath as JxPath) : [],
     };
   }
 
@@ -112,10 +119,9 @@ export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx):
     if (path.length >= pfx.length && pfx.every((seg, i) => path[i] === seg)) {
       const rest = path.slice(pfx.length);
       const [containerIdx] = rest;
-      mappedPath =
-        typeof containerIdx === "number"
-          ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
-          : ["children", ...rest];
+      mappedPath = isNumber(containerIdx)
+        ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
+        : ["children", ...rest];
     }
   }
 
@@ -154,5 +160,6 @@ export function serializeJxPath(path: JxPath): string {
 
 /** Decode a `data-jx-path` attribute back into a document path. */
 export function parseJxPath(serialized: string): JxPath {
+  // SAFETY: only serializeJxPath writes `data-jx-path`, and it is JSON.stringify of a JxPath.
   return JSON.parse(serialized) as JxPath;
 }

package/src/canvas/popover-path.ts

@@ -14,6 +14,7 @@
 import { activeTab } from "../workspace/workspace";
 import { getNodeAtPath } from "../state";
 import { documentHasPopover, isPopover } from "@jxsuite/schema/overlays";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { INVOKER_TAGS, POPOVER_TAGS } from "@jxsuite/ui";
 import { primarySelection } from "../tabs/selection";
 import type { JxMutableNode } from "@jxsuite/schema/types";
@@ -49,7 +50,7 @@ export function ancestorPopoverPath(
   for (let end = path.length; end >= 0; end -= 1) {
     const prefix = path.slice(0, end);
     const node = getNodeAtPath(doc, prefix);
-    if (node && typeof node === "object" && isPopover(node, KIT_SCOPE)) {
+    if (isNonNullObject(node) && isPopover(node, KIT_SCOPE)) {
       return prefix;
     }
   }
@@ -72,13 +73,16 @@ export function ancestorPopoverPath(
  * @returns The popover's path, or null.
  */
 export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
+  /* SAFETY: a widening, not a narrowing. A tab built by createTab always carries a document, but
+   * the command is a public entry point and the contract (pinned in popover-state.test.ts) is that
+   * a tab record without one answers null rather than throwing inside getNodeAtPath. */
   const doc = tab.doc.document as JxMutableNode | undefined;
   if (!doc) {
     return null;
   }
   if (explicit) {
     const node = getNodeAtPath(doc, explicit);
-    return node && typeof node === "object" && isPopover(node, KIT_SCOPE) ? explicit : null;
+    return isNonNullObject(node) && isPopover(node, KIT_SCOPE) ? explicit : null;
   }
   return ancestorPopoverPath(doc, primarySelection(tab.session.selection));
 }
@@ -101,6 +105,6 @@ export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
  * @returns True when the focused document declares at least one popover.
  */
 export function activeDocumentHasPopover(): boolean {
-  const doc = activeTab.value?.doc.document as JxMutableNode | undefined;
+  const doc = activeTab.value?.doc.document;
   return doc ? documentHasPopover(doc, KIT_SCOPE) : false;
 }

package/src/canvas/popover-state.ts

@@ -31,7 +31,6 @@ import { effect, pauseTracking, resetTracking } from "../reactivity";
 import { postPopoverOpen, revealCanvasPath } from "./iframe-host";
 import { primarySelection } from "../tabs/selection";
 import { updateSession } from "../store";
-import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { Tab } from "../tabs/tab";
 
@@ -59,7 +58,7 @@ export function setOpenPopover(tab: Tab, path: JxPath | null): void {
 
 /** Open the popover containing `path`, if any. Returns whether anything changed. */
 function openPopoverFor(tab: Tab, path: JxPath | null): boolean {
-  const target = ancestorPopoverPath(tab.doc.document as JxMutableNode, path);
+  const target = ancestorPopoverPath(tab.doc.document, path);
   if (target === null || samePath(tab.session.ui.openPopover, target)) {
     return false;
   }