@jxsuite/studio 6.1.1 → 6.1.2

package/src/canvas/iframe-insert.ts

@@ -17,6 +17,7 @@
  * (happy-dom's `elementFromPoint` returns null) and lives in iframe-interaction.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
 import { parseJxPath } from "./path-mapping";
 import { rectOf } from "../utils/geometry";
 import { childIndex, parentElementPath } from "../state";
@@ -48,7 +49,7 @@ function isRowLayout(parent: HTMLElement): boolean {
   const isGrid = display === "grid" || display === "inline-grid";
   return (
     (isFlex && style.flexDirection.startsWith("row")) ||
-    (isGrid && (style.gridAutoFlow ?? "").startsWith("column"))
+    (isGrid && style.gridAutoFlow.startsWith("column"))
   );
 }
 
@@ -78,11 +79,11 @@ export function computeInsertZones(
   shadowDoc: JxMutableNode,
 ): InsertZone[] | null {
   void shadowDoc;
-  const serialized = targetEl.dataset?.jxPath;
+  const serialized = targetEl.dataset.jxPath;
   if (serialized == null) {
     return null;
   }
-  const targetPath = parseJxPath(serialized) as JxPath;
+  const targetPath = parseJxPath(serialized);
 
   // Empty container: one centered "+" that inserts as the container's first child.
   if (targetEl.classList.contains(EMPTY_CONTAINER_CLASS)) {
@@ -99,7 +100,7 @@ export function computeInsertZones(
     return null;
   }
   const childIdx = childIndex(targetPath);
-  if (typeof childIdx !== "number") {
+  if (!isNumber(childIdx)) {
     return null;
   }
 

package/src/canvas/iframe-interaction.ts

@@ -7,6 +7,7 @@
  */
 
 import { jxPathSelector, parseJxPath, serializeJxPath } from "./path-mapping";
+import { isFunction } from "@jxsuite/schema/guards";
 import { rectOf } from "../utils/geometry";
 import { computeInsertZones, insertZonesKey } from "./iframe-insert";
 import { getActiveElement, isEditing } from "../editor/inline-edit";
@@ -32,9 +33,10 @@ function isCanvasLeave(e: Event, doc: Document): boolean {
 
 /** Walk up from an element to the nearest ancestor carrying a `data-jx-path`; null if none. */
 function nearestPathEl(start: Element | null): HTMLElement | null {
-  let el = start instanceof Element ? (start as HTMLElement) : null;
+  let el = start instanceof Element ? start : null;
   while (el) {
-    if (el.dataset?.jxPath) {
+    // Only HTML elements are stamped (`makeStamper` skips everything else), so only they can match.
+    if (el instanceof HTMLElement && el.dataset.jxPath) {
       return el;
     }
     el = el.parentElement;
@@ -57,6 +59,7 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
   if (!el) {
     return null;
   }
+  // SAFETY: nearestPathEl returns only an element whose `data-jx-path` is a non-empty string.
   return measureHit(el, el.dataset.jxPath as string);
 }
 
@@ -75,8 +78,9 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
  * from a node that is on screen is a worse failure than drawing one for a node that is not.
  */
 function isRendered(el: Element): boolean {
-  const check = (el as { checkVisibility?: (o?: object) => boolean }).checkVisibility;
-  return typeof check === "function" ? check.call(el, { checkVisibilityCSS: true }) : true;
+  // Absent on engines that predate it, whatever lib.dom says.
+  const check: Element["checkVisibility"] | undefined = el.checkVisibility;
+  return isFunction(check) ? check.call(el, { checkVisibilityCSS: true }) : true;
 }
 
 /**
@@ -92,10 +96,7 @@ function isRendered(el: Element): boolean {
  * The serialized path is the same string the renderer stamps, so a stored selection path
  * round-trips back to its element.
  */
-export function measureHits(
-  paths: (string | number)[][],
-  doc: Document = document,
-): { hits: NodeHit[]; hidden: (string | number)[][] } {
+export function measureHits(paths: (string | number)[][], doc: Document = document) {
   const hits: NodeHit[] = [];
   const hidden: (string | number)[][] = [];
   for (const path of paths) {
@@ -119,8 +120,15 @@ export function measureHits(
  * {@link file://./iframe-drop.ts}'s `startGrabDetector` receives its deps rather than reaching for
  * module state.
  */
+type InvokerAction = Extract<IframeToParent, { kind: "popoverTargetClick" }>["action"];
+
 /** The three `popovertargetaction` keywords. Anything else falls back to the HTML default. */
-const INVOKER_ACTIONS = new Set(["toggle", "show", "hide"]);
+const INVOKER_ACTIONS = new Set<string>(["toggle", "show", "hide"] satisfies InvokerAction[]);
+
+/** Whether an attribute value is one of the {@link INVOKER_ACTIONS} keywords. */
+function isInvokerAction(value: string): value is InvokerAction {
+  return INVOKER_ACTIONS.has(value);
+}
 
 /**
  * Report an invoker click, when the click landed on one and it names an addressable popover.
@@ -152,14 +160,14 @@ function postPopoverInvoke(
      need escaping — a rule this file already keeps in exactly one place (`jxPathSelector`) and
      should not gain a second spelling of. The set scanned is the addressable POPOVERS, which is
      also the set the answer has to come from, so the scan is the test. */
-  const panels = invoker.ownerDocument.querySelectorAll("[data-jx-popover]");
-  const panel = [...panels].find((el) => el.id === id) as HTMLElement | undefined;
+  const panels = invoker.ownerDocument.querySelectorAll<HTMLElement>("[data-jx-popover]");
+  const panel = [...panels].find((el) => el.id === id);
   const serialized = panel?.dataset.jxPath;
   if (!serialized) {
     return;
   }
   const raw = invoker.getAttribute("popovertargetaction") ?? "toggle";
-  const action = INVOKER_ACTIONS.has(raw) ? (raw as "toggle" | "show" | "hide") : "toggle";
+  const action = isInvokerAction(raw) ? raw : "toggle";
   channel.post({ action, kind: "popoverTargetClick", targetPath: parseJxPath(serialized) });
 }
 
@@ -190,10 +198,10 @@ function postCommandInvoke(
   }
   // Scanned, not selected, for the reason `postPopoverInvoke` gives; the addressable overlays are
   // The de-popovered panels and the stamped dialogs.
-  const overlays = invoker.ownerDocument.querySelectorAll(
+  const overlays = invoker.ownerDocument.querySelectorAll<HTMLElement>(
     "[data-jx-popover], dialog[data-jx-path]",
   );
-  const overlay = [...overlays].find((el) => el.id === id) as HTMLElement | undefined;
+  const overlay = [...overlays].find((el) => el.id === id);
   const serialized = overlay?.dataset.jxPath;
   if (!serialized) {
     return;
@@ -270,7 +278,7 @@ export function startInteraction(
     channel.post({ kind: "paneFocus" });
   };
 
-  const onClick = (e: Event) => {
+  const onClick = (e: MouseEvent) => {
     /*
      * Preview keeps anchors live, so a click would navigate this iframe and destroy the render (and
      * the editing session with it). Report the intent so the parent can open the real page in a real
@@ -303,9 +311,8 @@ export function startInteraction(
       // Ctrl/Cmd is the accumulate gesture (studio-ui-guidelines.md §8.1). The iframe reports the
       // Modifier and nothing else — it holds no selection state, so what a modified click MEANS is
       // The parent's to decide, exactly as the unmodified click already was.
-      const mouse = e as MouseEvent;
       channel.post({
-        additive: mouse.ctrlKey === true || mouse.metaKey === true,
+        additive: e.ctrlKey === true || e.metaKey === true,
         hit,
         kind: "hit",
       });
@@ -394,11 +401,10 @@ export function startInteraction(
     reportInsertZones(target, { x: moveX, y: moveY });
   };
 
-  const onMove = (e: Event) => {
-    const pe = e as PointerEvent;
+  const onMove = (e: PointerEvent) => {
     moveTarget = e.target;
-    moveX = pe.clientX;
-    moveY = pe.clientY;
+    moveX = e.clientX;
+    moveY = e.clientY;
     if (movePending) {
       return;
     }
@@ -415,8 +421,7 @@ export function startInteraction(
     }
   };
 
-  const onContextMenu = (e: Event) => {
-    const me = e as MouseEvent;
+  const onContextMenu = (e: MouseEvent) => {
     // Preview keeps the NATIVE menu: the Jx element menu's verbs (duplicate, delete, paste, wrap)
     // Are document edits, and preview does not edit. Copy Link Address does what it says instead.
     if (isPreview()) {
@@ -447,8 +452,8 @@ export function startInteraction(
     channel.post({
       kind: "contextMenu",
       path: hit.path,
-      x: me.clientX,
-      y: me.clientY,
+      x: e.clientX,
+      y: e.clientY,
     });
   };
 

package/src/canvas/iframe-overlay.ts

@@ -47,7 +47,7 @@ export function parentCursorToIframe(
   cursor: { x: number; y: number },
   iframeRect: { left: number; top: number },
   scale = 1,
-): { x: number; y: number } {
+) {
   return {
     x: (cursor.x - iframeRect.left) / scale,
     y: (cursor.y - iframeRect.top) / scale,

package/src/canvas/iframe-patch.ts

@@ -15,7 +15,8 @@
  */
 
 import { reapplyStyle } from "@jxsuite/runtime";
-import { getNodeAtPath } from "../state";
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 import { applyDocOpToDoc } from "../tabs/doc-op-apply";
 import { parseJxPath, serializeJxPath } from "./path-mapping";
 import { disposeSubtree, renderSubtreeIframe } from "./iframe-subtree";
@@ -25,7 +26,7 @@ import {
   templateToEditDisplay,
 } from "../utils/edit-display";
 import type { IframeRenderCtx } from "./iframe-render";
-import type { WireDocOp } from "./iframe-protocol";
+import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxPath } from "../state";
 import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
@@ -36,7 +37,7 @@ import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
  */
 export function applyIframePatch(
   shadowDoc: JxMutableNode,
-  forwardOps: WireDocOp[],
+  forwardOps: JxDocOp[],
   container: HTMLElement,
   ctx?: IframeRenderCtx,
   echoPaths?: JxPath[],
@@ -98,7 +99,7 @@ function requireCtx(ctx: IframeRenderCtx | undefined): IframeRenderCtx {
 
 function applyOpToDom(
   doc: JxMutableNode,
-  op: WireDocOp,
+  op: JxDocOp,
   container: HTMLElement,
   ctx: IframeRenderCtx | undefined,
 ): void {
@@ -138,7 +139,7 @@ function applyOpToDom(
       return;
     }
     default: {
-      // The WireDocOp union is exhaustively handled above; this guards a future op kind.
+      // The JxDocOp union is exhaustively handled above; this guards a future op kind.
       throw new Error(`iframe-patch-unsupported-op:${JSON.stringify(op)}`);
     }
   }
@@ -292,7 +293,7 @@ function remapChildPaths(
       continue;
     }
     const idx = p[depth + 1];
-    if (typeof idx !== "number" || idx < fromIndex) {
+    if (!isNumber(idx) || idx < fromIndex) {
       continue;
     }
     if (!parentPath.every((seg, i) => p[i] === seg)) {
@@ -338,7 +339,9 @@ function patchStyle(
 ): void {
   const el = requireElement(container, path);
   const node = getNodeAtPath(doc, path);
-  const mediaQueries = (ctx?.defs?.["$media"] as Record<string, string> | undefined) ?? {};
+  /* SAFETY: buildScope writes `$media` only from the document's own `$media` map or the runtime's
+   * root media map, both Record<string, string>, and the host scope may not supply the key. */
+  const mediaQueries = (ctx?.defs["$media"] as Record<string, string> | undefined) ?? {};
   reapplyStyle(el, editModeStyle(node?.style), mediaQueries);
 }
 
@@ -372,20 +375,20 @@ function findElement(container: HTMLElement, path: (string | number)[]): HTMLEle
  * top-level template-string values are blanked so no reactive bindings are created for them.
  */
 function editModeStyle(style: JxStyle | undefined): JxStyle | undefined {
-  if (!style || typeof style !== "object") {
+  if (!style || !isNonNullObject(style)) {
     return undefined;
   }
-  const out: Record<string, unknown> = {};
+  const out: JxStyle = {};
   for (const [k, v] of Object.entries(style)) {
     /* OMITTED, not blanked. It used to be written as `""`, which was a silent no-op while a
        declaration went to `el.style` and is a malformed declaration now that it goes into a rule.
        Dropping the key is what blanking always meant: the property falls back to the cascade. */
-    if (typeof v === "string" && v.includes("${")) {
+    if (isString(v) && v.includes("${")) {
       continue;
     }
     out[k] = v;
   }
-  return out as JxStyle;
+  return out;
 }
 
 /**
@@ -393,15 +396,15 @@ function editModeStyle(style: JxStyle | undefined): JxStyle | undefined {
  * template-string and $ref display rules (and the legacy patcher's textDisplayValue).
  */
 function textDisplayValue(node: JxMutableNode | undefined): string {
-  const v = (node as { textContent?: unknown } | undefined)?.textContent;
+  const v = node?.textContent;
   if (v == null) {
     return "";
   }
-  if (typeof v === "string") {
+  if (isString(v)) {
     return v.includes("${") ? templateToEditDisplay(v) : v;
   }
-  if (typeof v === "object" && (v as Record<string, unknown>).$ref) {
-    const ref = String((v as Record<string, unknown>).$ref);
+  if (isNonNullObject(v) && v.$ref) {
+    const ref = String(v.$ref);
     const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
     return `{${label}}`;
   }

package/src/canvas/iframe-position.ts

@@ -33,6 +33,12 @@ export interface DocRange {
   head: DocPos;
 }
 
+/** A live DOM caret position: a node and an offset into it, as a Selection endpoint carries. */
+export interface DomPosition {
+  node: Node;
+  offset: number;
+}
+
 /** Whether an element is a block the caret may live inside. Injected so the editable set is policy. */
 export type EditablePredicate = (el: HTMLElement) => boolean;
 
@@ -91,7 +97,7 @@ export function elementForPath(container: HTMLElement, path: JxPath): HTMLElemen
 
 /** The block's rendered text length — the maximum valid offset within it. */
 export function blockTextLength(block: HTMLElement): number {
-  return block.textContent?.length ?? 0;
+  return block.textContent.length;
 }
 
 /**
@@ -126,11 +132,12 @@ export function offsetOf(block: HTMLElement, node: Node, offset: number): number
  * every offset-based editor carries at a line break, and it is invisible for the paths that use
  * this (caret restore after a patch, and block-boundary edits, which clamp to 0 / length anyway).
  */
-export function domPositionAt(block: HTMLElement, offset: number): { node: Node; offset: number } {
+export function domPositionAt(block: HTMLElement, offset: number): DomPosition {
   const target = Math.max(0, Math.min(offset, blockTextLength(block)));
   const walker = block.ownerDocument.createTreeWalker(block, NodeFilter.SHOW_TEXT);
   let seen = 0;
   let last: Text | null = null;
+  // SAFETY: the walker was created with NodeFilter.SHOW_TEXT, so every node it yields is a Text.
   let current = walker.nextNode() as Text | null;
   while (current) {
     const len = current.length;
@@ -139,6 +146,7 @@ export function domPositionAt(block: HTMLElement, offset: number): { node: Node;
     }
     seen += len;
     last = current;
+    // SAFETY: the same SHOW_TEXT walker as above, so the next node is a Text or the walk's end.
     current = walker.nextNode() as Text | null;
   }
   // No text node reaches the target: either the block has no text at all (caret goes to the element
@@ -169,10 +177,7 @@ export function toDocPos(
  * block whose text shrank under a remote edit lands at the block's new end instead of being
  * dropped.
  */
-export function toDomPosition(
-  container: HTMLElement,
-  pos: DocPos,
-): { node: Node; offset: number } | null {
+export function toDomPosition(container: HTMLElement, pos: DocPos): DomPosition | null {
   const el = elementForPath(container, pos.path);
   return el ? domPositionAt(el, pos.offset) : null;
 }
@@ -246,6 +251,7 @@ export function adjacentBlock(
   const key = serializeJxPath(path);
   const index = blocks.findIndex((el) => el.dataset.jxPath === key);
   const neighbour = index === -1 ? undefined : blocks[index + direction];
+  // SAFETY: blocksInOrder collects only elements matching `[data-jx-path]`, so the attribute is set.
   return neighbour
     ? { el: neighbour, path: parseJxPath(neighbour.dataset.jxPath as string) }
     : null;

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);
 }
 
 /**
@@ -121,7 +112,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;
@@ -239,7 +230,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 +246,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 +269,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";
@@ -490,7 +486,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

@@ -38,7 +38,8 @@ 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 { 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);
         }
       })();
@@ -696,11 +694,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;
   }
@@ -746,15 +744,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 +781,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 +809,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 +832,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 +855,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 +865,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 +986,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 +1039,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 +1054,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 +1068,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);