@jxsuite/studio 6.1.0 → 6.1.2

package/src/ui/value-source.ts

@@ -43,7 +43,16 @@ import {
   tagExpressionSchema,
   tagNameSchema,
 } from "@jxsuite/schema/defs";
-import { isFunctionDef, isRef, isTemplateString } from "@jxsuite/schema/guards";
+import {
+  isFunctionDef,
+  isJsonObject,
+  isNonNullObject,
+  isRef,
+  isString,
+  isTemplateString,
+} from "@jxsuite/schema/guards";
+import type { ReadonlyJsonObject, ReadonlyJsonValue } from "@jxsuite/schema/project-schemas";
+import type { JsonValue, JxDocumentValue } from "@jxsuite/schema/types";
 
 /** A rung of the value ladder — one way a document position can produce its value. */
 export type SlotMode = "literal" | "ref" | "template" | "expression" | "function";
@@ -73,7 +82,7 @@ export const VALUE_SOURCE_HINTS: Record<SlotMode, string> = {
 };
 
 /** Detect which rung of the ladder a raw document value occupies. */
-export function slotMode(value: unknown): SlotMode {
+export function slotMode(value: JxDocumentValue | JsonValue | undefined): SlotMode {
   if (isRef(value)) {
     return "ref";
   }
@@ -83,7 +92,7 @@ export function slotMode(value: unknown): SlotMode {
   if (isTemplateString(value)) {
     return "template";
   }
-  if (value && typeof value === "object" && "$expression" in value) {
+  if (isNonNullObject(value) && "$expression" in value) {
     return "expression";
   }
   return "literal";
@@ -91,8 +100,6 @@ export function slotMode(value: unknown): SlotMode {
 
 // ─── Schema walk ────────────────────────────────────────────────────────────
 
-type SchemaNode = Record<string, unknown>;
-
 /**
  * The `on*` property shape that `@jxsuite/schema`'s generator synthesises for every EventHandler
  * IDL attribute (`buildEventHandlerProperties`). It is the only slot position with no declared
@@ -107,40 +114,45 @@ export const EVENT_HANDLER_SCHEMA = {
 } as const;
 
 /** The `$defs` a slot position can actually reach. Anything else is a bug, not a silent no-rung. */
-const REACHABLE_DEFS: Record<string, SchemaNode> = {
-  ExpressionEntry: expressionEntrySchema as unknown as SchemaNode,
-  FunctionDef: functionDefSchema as unknown as SchemaNode,
-  RefObject: refObjectSchema as unknown as SchemaNode,
-  StyleObject: styleObjectSchema as unknown as SchemaNode,
-};
+const REACHABLE_DEFS = new Map<string, ReadonlyJsonObject>([
+  ["ExpressionEntry", expressionEntrySchema],
+  ["FunctionDef", functionDefSchema],
+  ["RefObject", refObjectSchema],
+  ["StyleObject", styleObjectSchema],
+]);
 
 /** A `{ $ref: … }` binding object: `required: ["$ref"]` with a `$ref` property. */
-function isRefObjectSchema(node: SchemaNode): boolean {
-  const { required } = node;
+function isRefObjectSchema(node: ReadonlyJsonObject): boolean {
+  const { properties, required } = node;
   return (
     Array.isArray(required) &&
     required.includes("$ref") &&
-    Boolean((node.properties as SchemaNode | undefined)?.$ref)
+    isJsonObject(properties) &&
+    Boolean(properties.$ref)
   );
 }
 
 /** A `{ $expression: … }` entry. */
-function isExpressionEntrySchema(node: SchemaNode): boolean {
+function isExpressionEntrySchema(node: ReadonlyJsonObject): boolean {
   const { required } = node;
   return Array.isArray(required) && required.includes("$expression");
 }
 
 /** A `$prototype: "Function"` declaration. */
-function isFunctionDefSchema(node: SchemaNode): boolean {
-  const proto = (node.properties as SchemaNode | undefined)?.$prototype as SchemaNode | undefined;
-  return proto?.const === "Function";
+function isFunctionDefSchema(node: ReadonlyJsonObject): boolean {
+  const { properties } = node;
+  return (
+    isJsonObject(properties) &&
+    isJsonObject(properties.$prototype) &&
+    properties.$prototype.const === "Function"
+  );
 }
 
 /**
  * A string branch that will accept `${…}`. A pattern/enum/const-constrained string will not — a
  * `TagName` or a `#/state/…` pointer is a string, but not a place a template may be typed.
  */
-function isFreeStringSchema(node: SchemaNode): boolean {
+function isFreeStringSchema(node: ReadonlyJsonObject): boolean {
   return (
     node.type === "string" &&
     node.pattern === undefined &&
@@ -155,23 +167,24 @@ interface WalkState {
   found: Set<SlotMode>;
   /** Pointers the walk could not resolve — surfaced so a schema move fails loudly. */
   unresolved: Set<string>;
-  seen: Set<SchemaNode>;
+  seen: Set<ReadonlyJsonObject>;
 }
 
-function walk(node: unknown, state: WalkState): void {
-  if (!node || typeof node !== "object") {
+function walk(schema: ReadonlyJsonValue | undefined, state: WalkState): void {
+  /* An array is an object too, but it names no keyword: the walk below found nothing in one, so
+     refusing it here is the same answer reached sooner. */
+  if (!isJsonObject(schema)) {
     return;
   }
-  const schema = node as SchemaNode;
   if (state.seen.has(schema)) {
     return;
   }
   state.seen.add(schema);
 
-  const pointer = typeof schema.$ref === "string" ? schema.$ref : undefined;
+  const pointer = isString(schema.$ref) ? schema.$ref : undefined;
   if (pointer !== undefined && Object.keys(schema).length === 1) {
     const name = pointer.startsWith("#/$defs/") ? pointer.slice("#/$defs/".length) : pointer;
-    const target = REACHABLE_DEFS[name];
+    const target = REACHABLE_DEFS.get(name);
     if (target) {
       walk(target, state);
     } else {
@@ -218,7 +231,7 @@ function walk(node: unknown, state: WalkState): void {
     state.found.add("literal");
     return;
   }
-  if (typeof schema.type === "string" && SCALAR_TYPES.has(schema.type)) {
+  if (isString(schema.type) && SCALAR_TYPES.has(schema.type)) {
     state.found.add("literal");
   }
 }
@@ -230,7 +243,7 @@ export interface DerivedCaps {
 }
 
 /** Derive the rungs a subschema permits, and report any pointer the walk could not follow. */
-export function deriveSlotCapsDetailed(schema: unknown): DerivedCaps {
+export function deriveSlotCapsDetailed(schema: ReadonlyJsonValue | undefined): DerivedCaps {
   const state: WalkState = { found: new Set(), seen: new Set(), unresolved: new Set() };
   walk(schema, state);
   return {
@@ -240,7 +253,7 @@ export function deriveSlotCapsDetailed(schema: unknown): DerivedCaps {
 }
 
 /** Derive the rungs a subschema permits, in ladder order. */
-export function deriveSlotCaps(schema: unknown): SlotMode[] {
+export function deriveSlotCaps(schema: ReadonlyJsonValue | undefined): SlotMode[] {
   return deriveSlotCapsDetailed(schema).caps;
 }
 
@@ -322,7 +335,7 @@ export type SlotPosition = keyof typeof SLOT_POSITION_SCHEMAS;
  * There is deliberately no third form. A caller may not state which rungs it wants: the rungs are
  * derived from a schema or they are not derived at all.
  */
-export type SlotCapsSource = SlotPosition | { schema: unknown };
+export type SlotCapsSource = SlotPosition | { schema: ReadonlyJsonValue };
 
 const capsCache = new Map<SlotPosition, SlotMode[]>();
 
@@ -339,7 +352,7 @@ export function capsForPosition(position: SlotPosition): SlotMode[] {
 
 /** The rungs on offer for a {@link SlotCapsSource} — a named position, or a schema handed in. */
 export function slotCaps(source: SlotCapsSource): SlotMode[] {
-  return typeof source === "string" ? capsForPosition(source) : deriveSlotCaps(source.schema);
+  return isString(source) ? capsForPosition(source) : deriveSlotCaps(source.schema);
 }
 
 /**
@@ -351,7 +364,7 @@ export function slotCaps(source: SlotCapsSource): SlotMode[] {
  * own config at runtime — which no plugin schema declares because it is not the plugin's to
  * declare. Both are stated here, once, rather than assumed at each form.
  */
-export function configFieldSchema(field: unknown): { anyOf: unknown[] } {
+export function configFieldSchema(field: ReadonlyJsonValue): ReadonlyJsonObject {
   const declared = deriveSlotCaps(field).length > 0 ? field : { type: "string" };
   return { anyOf: [declared, { $ref: "#/$defs/RefObject" }] };
 }

package/src/ui/virtual-window.ts

@@ -28,6 +28,7 @@
 
 /// <reference lib="dom" />
 
+import { isFunction } from "@jxsuite/schema/guards";
 import { rectOf } from "../utils/geometry";
 
 /** The measurement a window is computed from. Everything is in CSS pixels. */
@@ -244,7 +245,7 @@ export function createVirtualWindow(options: VirtualWindowOptions): VirtualWindo
   };
 
   let resizeObserver: ResizeObserver | null = null;
-  if (typeof ResizeObserver === "function") {
+  if (isFunction(globalThis.ResizeObserver)) {
     resizeObserver = new ResizeObserver(measureNextFrame);
     resizeObserver.observe(scroller);
     if (list) {
@@ -373,7 +374,7 @@ export function listWindow(
   return computeWindow({
     columns: spec.columns ?? 1,
     count: spec.count,
-    ...(spec.overscanRows === undefined ? {} : { overscanRows: spec.overscanRows }),
+    overscanRows: spec.overscanRows ?? DEFAULT_OVERSCAN_ROWS,
     rowHeight: spec.rowHeight,
     scrollTop: listScrollTop(scroller, list),
     viewportHeight: scroller.clientHeight,

package/src/utils/base64.ts

@@ -11,6 +11,8 @@
  * backends answer a base64 string for the same reason they accept one, and the caller wants bytes.
  */
 
+import { isString } from "@jxsuite/schema/guards";
+
 /** Bytes per `String.fromCodePoint` call — spreading a whole large file blows the call stack. */
 const CHUNK = 32_768;
 
@@ -28,7 +30,7 @@ export function bytesToBase64(bytes: Uint8Array): string {
  * have always received base64 strings, so existing callers keep working.
  */
 export async function toBase64(data: string | File | Blob | ArrayBuffer): Promise<string> {
-  if (typeof data === "string") {
+  if (isString(data)) {
     return data;
   }
   const buffer = data instanceof ArrayBuffer ? data : await data.arrayBuffer();

package/src/utils/edit-display.ts

@@ -5,18 +5,50 @@
  * placeholders).
  */
 
-import type { JxMutableNode } from "@jxsuite/schema/types";
-import { displayTagName } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
+import { displayTagName, isNodeObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { isDocumentContainer } from "./strip-events";
+import type { RebuiltNode } from "./strip-events";
 
 const mediaTags = new Set(["img", "video", "source", "iframe", "audio"]);
-const TRANSPARENT_PX =
+/** A 1×1 transparent GIF: what an unresolvable `src` binding shows in edit mode. */
+export const TRANSPARENT_PX =
   "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
 // A neutral, visible gray placeholder for image-like bindings in edit mode (e.g. a component `image`
 // Prop bound to ${...}). The component renders <img src={prop}> internally, so a transparent pixel
 // Would collapse to nothing — a gray SVG box reads as an intentional placeholder instead.
-const PLACEHOLDER_IMG =
+export const PLACEHOLDER_IMG =
   "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20width='32'%20height='32'%3E%3Crect%20width='32'%20height='32'%20fill='%23d0d0d0'/%3E%3C/svg%3E";
 
+/**
+ * Swap every image under `host` that fails to load for {@link PLACEHOLDER_IMG}, until `signal`
+ * aborts.
+ *
+ * For previews drawn in the PARENT realm, where nothing ran {@link prepareForEditMode}: a library
+ * card's file, a component whose image prop is a `${}` binding with nothing to bind it, a document
+ * whose `src` is empty. The browser drew each as its broken-image glyph. `error` does not bubble,
+ * so the listener captures — which also covers images a preview renders after it is mounted. An
+ * empty `src` fires `error` too, so it needs no separate test; an image already showing the
+ * placeholder is left alone, so a placeholder that cannot load (it always can) does not loop.
+ *
+ * @param {Element} host
+ * @param {AbortSignal} signal
+ */
+export function placeholderBrokenImages(host: Element, signal: AbortSignal): void {
+  host.addEventListener(
+    "error",
+    (event) => {
+      const { target } = event;
+      if (target instanceof HTMLImageElement && target.getAttribute("src") !== PLACEHOLDER_IMG) {
+        target.setAttribute("src", PLACEHOLDER_IMG);
+        target.removeAttribute("srcset");
+        target.dataset.placeholder = "";
+      }
+    },
+    { capture: true, signal },
+  );
+}
+
 // Prop/attribute names that feed an <img>/background, so a ${...} binding would otherwise render a
 // Broken image in edit mode. Matched by exact name or common camelCase suffix (featuredImage, heroBg).
 const IMAGE_KEY_RE =
@@ -132,6 +164,7 @@ export function templateToEditDisplay(str: string) {
 export function restoreTemplateExpressions(el: HTMLElement) {
   const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
   while (walker.nextNode()) {
+    // SAFETY: the walker was created with NodeFilter.SHOW_TEXT, so every node it stops on is Text.
     const node = walker.currentNode as Text;
     if (node.data.includes("\u276A")) {
       node.data = node.data.replaceAll(/\u276A\s*(.*?)\s*\u276B/g, "${$1}");
@@ -146,52 +179,64 @@ export function restoreTemplateExpressions(el: HTMLElement) {
  * edit-only device — it is never compiled or rendered in preview.
  *
  * @param {JxMutableNode} arrayObj
- * @returns {Record<string, unknown>}
+ * @returns {JxMutableNode}
  */
-function arrayToPerimeter(arrayObj: JxMutableNode): Record<string, unknown> {
+function arrayToPerimeter(arrayObj: JxMutableNode): JxMutableNode {
   const template = arrayObj.map;
   return {
-    children:
-      template && typeof template === "object"
-        ? [prepareForEditMode(template as JxMutableNode)]
-        : [],
+    children: isNonNullObject(template) ? [prepareForEditMode(template)] : [],
     className: "repeater-perimeter",
     tagName: "div",
   };
 }
 
+/**
+ * The text a `$ref` binding shows in edit mode: its pointer, with the `#/state/` prefix dropped.
+ *
+ * @param {string} ref
+ */
+function refDisplayLabel(ref: string): string {
+  const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
+  return `{${label}}`;
+}
+
 /**
  * Prepare a document for edit-mode rendering. Replaces template strings with readable literal text,
  * $prototype:Array with placeholders, and $ref bindings with display labels. Preserves state so the
- * runtime can still initialise scope.
+ * runtime can still initialise scope. Arrays are prepared member by member, and primitives and a
+ * cleared (`undefined`) key return unchanged, so the walker can recurse through any document
+ * value.
  *
  * @param {JxMutableNode} node
  * @returns {JxMutableNode}
  */
-export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
-  if (!node || typeof node !== "object") {
-    return node;
-  }
+export function prepareForEditMode(node: JxMutableNode): JxMutableNode;
+export function prepareForEditMode(node: JxDocumentValue): JxDocumentValue;
+export function prepareForEditMode(node: JxDocumentValue | undefined): JxDocumentValue | undefined;
+export function prepareForEditMode(node: JxDocumentValue | undefined): JxDocumentValue | undefined {
   if (Array.isArray(node)) {
     // Arrays of nodes round-trip element-wise; the array itself is not a node.
-    return (node as JxMutableNode[]).map((n) => prepareForEditMode(n)) as unknown as JxMutableNode;
+    return node.map((n) => prepareForEditMode(n));
+  }
+  if (!isNodeObject(node)) {
+    return node;
   }
 
   // A mapped-array node itself → its edit-mode perimeter (e.g. when the patcher re-renders an
   // Array node directly). Members inside a children array funnel here via the children branch.
-  if ((node as Record<string, unknown>).$prototype === "Array") {
-    return arrayToPerimeter(node) as unknown as JxMutableNode;
+  if (node.$prototype === "Array") {
+    return arrayToPerimeter(node);
   }
 
-  const /** @type {Record<string, unknown>} */ obj = node as Record<string, unknown>;
+  const obj = node;
 
-  const out: Record<string, unknown> = {};
+  const out: RebuiltNode = {};
   let needsMediaPlaceholder = false;
-  const isMediaElement = mediaTags.has((obj.tagName as string) || "");
+  const isMediaElement = isString(obj.tagName) && mediaTags.has(obj.tagName);
 
   // Check if this media element lacks a resolvable src (top-level or in attributes)
   if (isMediaElement) {
-    const attrs = obj.attributes as Record<string, unknown> | undefined;
+    const attrs = obj.attributes;
     const topSrc = obj.src;
     const attrSrc = attrs?.src;
     const topPoster = obj.poster;
@@ -206,11 +251,11 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
   for (const [k, v] of Object.entries(obj)) {
     if (k === "state" || k === "$media" || k === "$elements") {
       out[k] = v; // Preserve as-is for runtime resolution
-    } else if (k === "$props" && v && typeof v === "object") {
+    } else if (k === "$props" && isDocumentContainer(v)) {
       // Process $props values: convert template strings to display format
-      const propsOut: Record<string, unknown> = {};
+      const propsOut: RebuiltNode = {};
       for (const [pk, pv] of Object.entries(v)) {
-        if (typeof pv === "string" && pv.includes("${")) {
+        if (isString(pv) && pv.includes("${")) {
           // Image-like prop → neutral placeholder (the component renders it as an <img src>); link
           // Targets → inert ""; everything else → the readable ❪ expr ❫ binding text.
           if (isImageUrlKey(pk)) {
@@ -220,10 +265,8 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
           } else {
             propsOut[pk] = templateToEditDisplay(pv);
           }
-        } else if (pv && typeof pv === "object" && (pv as Record<string, unknown>).$ref) {
-          const ref = (pv as Record<string, unknown>).$ref as string;
-          const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
-          propsOut[pk] = `{${label}}`;
+        } else if (isNodeObject(pv) && pv.$ref) {
+          propsOut[pk] = refDisplayLabel(pv.$ref);
         } else {
           propsOut[pk] = pv;
         }
@@ -233,25 +276,21 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
       if (Array.isArray(v)) {
         // Each member recurses; array pseudo-elements become a single repeater-perimeter element
         // (via the top-level array case) so they stay a 1:1 DOM node among their siblings.
-        out.children = v.map((c) => prepareForEditMode(c as JxMutableNode));
-      } else if (
-        v &&
-        typeof v === "object" &&
-        (v as Record<string, unknown>).$prototype === "Array"
-      ) {
+        out.children = v.map((c) => prepareForEditMode(c));
+      } else if (isNodeObject(v) && v.$prototype === "Array") {
         // Legacy whole-children repeater → a single perimeter as the sole child.
-        out.children = [prepareForEditMode(v as JxMutableNode)];
+        out.children = [prepareForEditMode(v)];
       } else {
-        out.children = prepareForEditMode(v as JxMutableNode);
+        out.children = prepareForEditMode(v);
       }
-    } else if (k === "cases" && obj.$switch && v && typeof v === "object") {
+    } else if (k === "cases" && obj.$switch && isDocumentContainer(v)) {
       // Replace $switch cases with a placeholder showing the first case or a label
-      const caseKeys = Object.keys(v);
-      if (caseKeys.length > 0) {
-        const firstCase = (v as Record<string, unknown>)[caseKeys[0]!];
+      const [firstEntry] = Object.entries(v);
+      if (firstEntry) {
+        const [, firstCase] = firstEntry;
         out.children =
-          firstCase && typeof firstCase === "object" && !(firstCase as Record<string, unknown>).$ref
-            ? [prepareForEditMode(firstCase as JxMutableNode)]
+          isDocumentContainer(firstCase) && !(isNodeObject(firstCase) && firstCase.$ref)
+            ? [prepareForEditMode(firstCase)]
             : [
                 {
                   style: {
@@ -265,29 +304,26 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
                     padding: "6px 10px",
                   },
                   tagName: "div",
-                  textContent: `[$switch: ${caseKeys.join(" | ")}]`,
+                  textContent: `[$switch: ${Object.keys(v).join(" | ")}]`,
                 },
               ];
       }
-    } else if (k === "attributes" && isMediaElement && v && typeof v === "object") {
+    } else if (k === "attributes" && isMediaElement && isDocumentContainer(v)) {
       // Process attributes for media elements: replace src/poster with transparent pixel
-      const attrs = v as Record<string, unknown>;
-      const processed: Record<string, unknown> = {};
-      for (const [ak, av] of Object.entries(attrs)) {
+      const processed: RebuiltNode = {};
+      for (const [ak, av] of Object.entries(v)) {
         if (ak === "src" || ak === "poster") {
-          if (typeof av === "string" && av !== "" && !av.includes("${")) {
+          if (isString(av) && av !== "" && !av.includes("${")) {
             processed[ak] = av;
           } else {
             needsMediaPlaceholder = true;
             processed[ak] = TRANSPARENT_PX;
           }
-        } else if (typeof av === "string" && av.includes("${")) {
+        } else if (isString(av) && av.includes("${")) {
           const isUrlAttr = ak === "href" || ak === "action";
           processed[ak] = isUrlAttr ? "" : templateToEditDisplay(av);
-        } else if (av && typeof av === "object" && (av as Record<string, unknown>).$ref) {
-          const ref = (av as Record<string, unknown>).$ref as string;
-          const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
-          processed[ak] = `{${label}}`;
+        } else if (isNodeObject(av) && av.$ref) {
+          processed[ak] = refDisplayLabel(av.$ref);
         } else {
           processed[ak] = av;
         }
@@ -298,10 +334,10 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
          cannot be resolved; omitting the property lets the cascade answer, which is exactly what
          the `""` this used to write meant while declarations went inline. As a RULE, `color: ` is
          a malformed declaration instead of a no-op. Mirrored by iframe-patch's editModeStyle. */
-      if (v && typeof v === "object") {
-        const s: Record<string, unknown> = {};
+      if (isDocumentContainer(v)) {
+        const s: RebuiltNode = {};
         for (const [sk, sv] of Object.entries(v)) {
-          if (typeof sv !== "string" || !sv.includes("${")) {
+          if (!isString(sv) || !sv.includes("${")) {
             s[sk] = sv;
           }
         }
@@ -309,10 +345,9 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
       } else {
         out.style = v;
       }
-    } else if (typeof v === "string" && v.includes("${")) {
+    } else if (isString(v) && v.includes("${")) {
       // Template string in a display property → show raw expression
-      const isMediaSrc =
-        (k === "src" || k === "poster") && mediaTags.has((obj.tagName as string) || "");
+      const isMediaSrc = (k === "src" || k === "poster") && isMediaElement;
       if (isMediaSrc) {
         needsMediaPlaceholder = true;
         out[k] = TRANSPARENT_PX;
@@ -320,42 +355,36 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
         const isUrlAttr = k === "src" || k === "href" || k === "poster" || k === "action";
         out[k] = isUrlAttr ? "" : templateToEditDisplay(v);
       }
-    } else if (v && typeof v === "object" && (v as Record<string, unknown>).$ref) {
+    } else if (isNodeObject(v) && v.$ref) {
       // $ref binding → show ref path as literal text
-      const ref = (v as Record<string, unknown>).$ref as string;
-      const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
-      const isMediaSrc =
-        (k === "src" || k === "poster") && mediaTags.has((obj.tagName as string) || "");
+      const label = refDisplayLabel(v.$ref);
+      const isMediaSrc = (k === "src" || k === "poster") && isMediaElement;
       if (isMediaSrc) {
         needsMediaPlaceholder = true;
         out[k] = TRANSPARENT_PX;
       } else {
-        out[k] = `{${label}}`;
+        out[k] = label;
       }
     } else {
       // Empty src/poster on media elements → use transparent pixel placeholder
-      if (
-        (k === "src" || k === "poster") &&
-        v === "" &&
-        mediaTags.has((obj.tagName as string) || "")
-      ) {
+      if ((k === "src" || k === "poster") && v === "" && isMediaElement) {
         needsMediaPlaceholder = true;
         out[k] = TRANSPARENT_PX;
       } else {
-        out[k] = prepareForEditMode(v as JxMutableNode);
+        out[k] = prepareForEditMode(v);
       }
     }
   }
 
   // Mark empty elements with placeholder classes for design-mode visibility
-  const placeholderClass = computeEmptyPlaceholderClass(out as JxMutableNode);
+  const placeholderClass = computeEmptyPlaceholderClass(out);
   if (placeholderClass) {
     out.className = out.className ? `${out.className} ${placeholderClass}` : placeholderClass;
   }
 
   // Media elements with missing/dynamic src get a placeholder class
   if (needsMediaPlaceholder) {
-    const cls = (out.className as string) || "";
+    const cls = isString(out.className) ? out.className : "";
     if (!cls.includes("empty-media-placeholder")) {
       out.className = cls ? `${cls} empty-media-placeholder` : "empty-media-placeholder";
     }

package/src/utils/element-selectors.ts

@@ -14,7 +14,7 @@
  */
 
 import { COMMON_SELECTORS } from "../store";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import { isPopover } from "@jxsuite/schema/overlays";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
@@ -62,7 +62,8 @@ function extraSelectorsFor(node: JxMutableNode): string[] {
  * @returns The offerable selectors.
  */
 export function selectorsForNode(node: JxMutableNode | null | undefined): string[] {
-  if (!node || typeof node !== "object") {
+  // The style panel reads the node with getNodeAtPath, which can answer a bare string text child.
+  if (!isNonNullObject(node)) {
     return [...COMMON_SELECTORS];
   }
   return [...new Set([...COMMON_SELECTORS, ...extraSelectorsFor(node)])];

package/src/utils/google-fonts.ts

@@ -1,5 +1,6 @@
 /** Google Fonts helpers — shared between head-panel (per-page) and head-editor (project-level). */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxHeadEntry } from "@jxsuite/schema/types";
 
 export const GFONTS_CSS_PREFIX = "https://fonts.googleapis.com/css2?";
@@ -11,29 +12,30 @@ export const GFONTS_PRECONNECT_ORIGINS = [
 /**
  * Check if a `$head` entry is a Google Fonts stylesheet link.
  *
- * @param {JxHeadEntry} entry
+ * @param {JxHeadEntry | null | undefined} entry A `$head` slot; a JSON array can hold `null`.
  * @returns {boolean}
  */
-export function isGoogleFontEntry(entry: JxHeadEntry) {
+export function isGoogleFontEntry(entry: JxHeadEntry | null | undefined) {
   return (
     entry?.tagName === "link" &&
-    entry?.attributes?.rel === "stylesheet" &&
-    typeof entry?.attributes?.href === "string" &&
-    (entry.attributes.href as string).startsWith(GFONTS_CSS_PREFIX)
+    entry.attributes?.rel === "stylesheet" &&
+    isString(entry.attributes.href) &&
+    entry.attributes.href.startsWith(GFONTS_CSS_PREFIX)
   );
 }
 
 /**
  * Check if a `$head` entry is a Google Fonts preconnect link.
  *
- * @param {JxHeadEntry} entry
+ * @param {JxHeadEntry | null | undefined} entry A `$head` slot; a JSON array can hold `null`.
  * @returns {boolean}
  */
-export function isGoogleFontPreconnect(entry: JxHeadEntry) {
+export function isGoogleFontPreconnect(entry: JxHeadEntry | null | undefined) {
   return (
     entry?.tagName === "link" &&
-    entry?.attributes?.rel === "preconnect" &&
-    GFONTS_PRECONNECT_ORIGINS.includes(entry?.attributes?.href as string)
+    entry.attributes?.rel === "preconnect" &&
+    isString(entry.attributes.href) &&
+    GFONTS_PRECONNECT_ORIGINS.includes(entry.attributes.href)
   );
 }
 
@@ -68,14 +70,13 @@ export function buildGoogleFontUrl(family: string) {
  */
 export function ensureGoogleFontPreconnects(head: JxHeadEntry[]) {
   for (const origin of GFONTS_PRECONNECT_ORIGINS) {
+    // A `$head` array is JSON, so a slot can hold `null` whatever the element type says.
     const exists = head.some(
-      (e: JxHeadEntry) =>
-        e?.tagName === "link" &&
-        e?.attributes?.rel === "preconnect" &&
-        e?.attributes?.href === origin,
+      (e: JxHeadEntry | null | undefined) =>
+        e?.tagName === "link" && e.attributes?.rel === "preconnect" && e.attributes.href === origin,
     );
     if (!exists) {
-      const attrs: Record<string, string | boolean> = {
+      const attrs: NonNullable<JxHeadEntry["attributes"]> = {
         href: origin,
         rel: "preconnect",
       };