@jxsuite/runtime 2.0.4 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.8.0",
+    "@jxsuite/schema": "^1.9.0",
     "@vue/reactivity": "3.5.41"
   },
   "devDependencies": {

package/src/runtime.ts

@@ -42,6 +42,7 @@ import {
   isTemplateString,
   paramNames,
 } from "@jxsuite/schema/guards";
+import { formatSrcset, parseSrcset } from "@jxsuite/schema/asset-paths";
 import { runStatements } from "./statements.ts";
 import { readCookie, serializeCookie } from "./cookie.ts";
 import type {
@@ -331,6 +332,119 @@ function canvasAttrName(el: HTMLElement, key: string): string {
   return key;
 }
 
+/**
+ * Rewrite one asset reference for a host that does not serve the site's own URL space.
+ *
+ * The runtime writes a reference VERBATIM — `el.src = "/hero.jpg"` — so the browser resolves it
+ * against the document, and the document is whatever page the renderer happens to be running in. On
+ * a real site and on an editing server that serves the project tree, that is correct and this hook
+ * stays null. On a multi-tenant editor origin it is not: `/hero.jpg` resolves against the editor,
+ * misses, and — behind a single-page-app fallback — comes back as HTML at HTTP 200, so the image
+ * renders broken and nothing is logged.
+ *
+ * A function rather than data because it cannot be one: the values it must fix are produced INSIDE
+ * reactive effects (`{"$ref": "#/state/hero"}` is not a string until the effect runs), so no
+ * document walk can see them. The Studio canvas iframe sets this at render time.
+ *
+ * Returning null leaves the value exactly as written, and a null resolver makes every call site
+ * below the identity — so production rendering is byte-identical.
+ *
+ * @param {CanvasAssetResolver | null} fn - The resolver, or null to restore verbatim rendering
+ */
+export type CanvasAssetResolver = (value: string, key: string) => string | null;
+
+let _canvasAssetResolver: CanvasAssetResolver | null = null;
+export function setCanvasAssetResolver(fn: CanvasAssetResolver | null) {
+  _canvasAssetResolver = fn;
+}
+
+/** Attribute/property names whose value is an asset reference, on any element. */
+const ASSET_KEYS = new Set(["src", "poster", "data"]);
+
+/** Names whose value is a `srcset`-shaped candidate list rather than one reference. */
+const SRCSET_KEYS = new Set(["srcset", "imagesrcset"]);
+
+/**
+ * Elements on which `href` names an ASSET rather than a destination.
+ *
+ * `<a href>` and `<area href>` are places to go, not files to load; rewriting one would send a
+ * click at the file that backs the page instead of at the page. `<link href>` is the opposite — a
+ * stylesheet, an icon, a preload — and is the reason `$head` needs this at all.
+ */
+const HREF_ASSET_TAGS = new Set(["LINK"]);
+
+/** True when writing `key` on a `<tagName>` writes an asset reference. */
+function isAssetKey(tagName: string, key: string): boolean {
+  return ASSET_KEYS.has(key) || (key === "href" && HREF_ASSET_TAGS.has(tagName));
+}
+
+/**
+ * The value to actually write for `key` on a `<tagName>` — resolved when it is an asset reference,
+ * and the input itself in every other case, including whenever no resolver is installed.
+ *
+ * `srcset` is split into its candidates and resolved one at a time, because it is N references in
+ * one attribute and a resolver handed the whole string would have to re-implement HTML's parser to
+ * find them.
+ */
+function canvasAssetValue(tagName: string, key: string, value: string): string {
+  if (!_canvasAssetResolver || value === "") {
+    return value;
+  }
+  const name = key.toLowerCase();
+  if (SRCSET_KEYS.has(name)) {
+    const candidates = parseSrcset(value);
+    let changed = false;
+    const next = candidates.map((candidate) => {
+      const resolved = _canvasAssetResolver?.(candidate.url, name) ?? null;
+      if (resolved === null || resolved === candidate.url) {
+        return candidate;
+      }
+      changed = true;
+      return { descriptor: candidate.descriptor, url: resolved };
+    });
+    return changed ? formatSrcset(next) : value;
+  }
+  if (!isAssetKey(tagName, name)) {
+    return value;
+  }
+  return _canvasAssetResolver(value, name) ?? value;
+}
+
+/** Every `url(...)` inside a CSS value, unquoted or quoted with either quote. */
+const CSS_URL_RE = /\burl\(\s*(?<q>["']?)(?<u>[^"')]*)\k<q>\s*\)/g;
+
+/**
+ * Resolve every `url()` inside a CSS value.
+ *
+ * Applied to CSS rather than to a list of properties because in CSS a `url()` is ALWAYS a resource
+ * reference — `background-image`, `mask`, `cursor`, `@font-face src`, `list-style-image` and every
+ * shorthand that contains them — so enumerating the properties would be a list that goes stale
+ * while the syntax does not.
+ */
+function canvasStyleUrls(value: string): string {
+  if (!_canvasAssetResolver || !value.includes("url(")) {
+    return value;
+  }
+  return value.replaceAll(CSS_URL_RE, (whole, quote: string, url: string) => {
+    const resolved = url === "" ? null : (_canvasAssetResolver?.(url, "url()") ?? null);
+    return resolved === null ? whole : `url(${quote}${resolved}${quote})`;
+  });
+}
+
+/**
+ * A style scalar as the canvas wants it written: assets resolved, then viewport units transposed.
+ *
+ * Exported because the canvas emits some CSS itself — the site-level `style` block, which never
+ * passes through {@link applyStyle} — and a second implementation of "what the canvas does to a
+ * style value" is a second thing to keep in step.
+ *
+ * @param {string} value - A CSS declaration value
+ * @returns {string} The value as the canvas should write it
+ */
+export function canvasStyleValue(value: string): string {
+  return transposeCanvasUnits(canvasStyleUrls(value));
+}
+
 /**
  * Studio-canvas prop-binding markers. When on, `bindProperty` stamps `data-jx-bound-prop="<key>"`
  * on elements whose `textContent` is an invertible single-key state binding — the pure template
@@ -761,6 +875,32 @@ export const RESERVED_KEYS = new Set([
 /** Refs already warned about, so the §13 diagnostic fires once per distinct target. */
 const warnedRefChildren = new Set<string>();
 
+/** Foreign-content namespaces the HTML parser switches into, and the runtime must too. */
+const SVG_NS = "http://www.w3.org/2000/svg";
+const MATHML_NS = "http://www.w3.org/1998/Math/MathML";
+
+/**
+ * The namespace an element belongs in, given the one its parent established.
+ *
+ * The static build emits markup text, so the HTML parser applied foreign-content rules for it and
+ * SVG worked there. The runtime built every node with `document.createElement`, which is HTML-only,
+ * so the same document rendered blank in the Studio canvas and in any hydrated component — the
+ * editor and the deployed site disagreeing, with only the editor wrong.
+ *
+ * @param {string} tagName
+ * @param {string | null | undefined} inherited - The namespace the parent element established
+ * @returns {string | null} Null means HTML
+ */
+function elementNamespace(tagName: string, inherited: string | null | undefined): string | null {
+  if (tagName === "svg") {
+    return SVG_NS;
+  }
+  if (tagName === "math") {
+    return MATHML_NS;
+  }
+  return inherited ?? null;
+}
+
 export function renderNode(
   def: JxElement | string | number | boolean,
   state: JxScope,
@@ -843,7 +983,19 @@ export function renderNode(
     return renderSwitch(def, localState, options);
   }
 
-  const el = document.createElement(tagName);
+  const ns = elementNamespace(tagName, options?._ns);
+  /*
+   * `foreignObject` is itself an SVG element, and is the documented way back into HTML: its
+   * DESCENDANTS are HTML, so the element and its children carry different namespaces.
+   */
+  const childNs = tagName === "foreignObject" ? null : ns;
+  /*
+   * A namespaced node comes back as Element; every apply* helper below is typed for HTMLElement
+   * and touches only members both share (style, dataset, setAttribute, append).
+   */
+  const el = (ns
+    ? document.createElementNS(ns, tagName)
+    : document.createElement(tagName)) as unknown as HTMLElement;
 
   if (options?.onNodeCreated) {
     options.onNodeCreated(el, path, def, localState);
@@ -862,12 +1014,16 @@ export function renderNode(
   if (isMappedArray(kids)) {
     // Legacy whole-children repeater: the items render directly into `el` (which keeps its own
     // TagName, e.g. <ul>), with no extra wrapper element.
-    const arrOpts = options ? { ...options, _path: [...path, "children"] } : undefined;
+    const arrOpts =
+      options || childNs ? { ...options, _ns: childNs, _path: [...path, "children"] } : undefined;
     renderMappedArrayInto(el, kids, localState, arrOpts);
   } else if (Array.isArray(kids)) {
     for (let i = 0; i < kids.length; i++) {
       const child = kids[i]!;
-      const childOpts = options ? { ...options, _path: [...path, "children", i] } : undefined;
+      const childOpts =
+        options || childNs
+          ? { ...options, _ns: childNs, _path: [...path, "children", i] }
+          : undefined;
       if (isMappedArray(child)) {
         // Array pseudo-element among siblings: expand inline, no wrapper.
         renderMappedArrayInto(el, child, localState, childOpts);
@@ -957,6 +1113,24 @@ function bindProperty(el: HTMLElement, key: string, val: unknown, state: JxScope
   if (boundProp) {
     el.dataset.jxBoundProp = boundProp;
   }
+  /* An `<img>` in a document says `{"tagName": "img", "src": "/hero.jpg"}`, so `src` arrives HERE
+     as a top-level key and is written as a DOM PROPERTY — `attributes: { src }` is the rarer
+     spelling. Both are the same reference and both need the same resolution. */
+  const asAsset = (resolved: unknown): unknown =>
+    typeof resolved === "string" ? canvasAssetValue(el.tagName, key, resolved) : resolved;
+  /*
+   * `className` on an SVGElement is a read-only SVGAnimatedString, so assigning it throws in the
+   * strict mode an ES module always runs under. It is the most common Jx element property, so the
+   * attribute form is the only one that works on both.
+   */
+  const write = (resolved: unknown): void => {
+    const node = el as unknown as Element;
+    if (key === "className" && !(node instanceof HTMLElement)) {
+      node.setAttribute("class", resolved == null ? "" : String(resolved));
+      return;
+    }
+    target[key] = resolved;
+  };
   if (isRefObj(val)) {
     const refVal = val as { $ref: string };
     if (key === "id") {
@@ -964,7 +1138,7 @@ function bindProperty(el: HTMLElement, key: string, val: unknown, state: JxScope
       return;
     }
     effect(() => {
-      target[key] = resolveRef(refVal.$ref, state);
+      write(asAsset(resolveRef(refVal.$ref, state)));
     });
     return;
   }
@@ -972,12 +1146,12 @@ function bindProperty(el: HTMLElement, key: string, val: unknown, state: JxScope
   // Universal ${} reactivity — template strings in element properties
   if (isTemplateString(val)) {
     effect(() => {
-      target[key] = evaluateTemplate(val as string, state);
+      write(asAsset(evaluateTemplate(val as string, state)));
     });
     return;
   }
 
-  target[key] = val;
+  write(asAsset(val));
 }
 
 /**
@@ -1038,22 +1212,22 @@ export function applyStyle(
     if (prop.startsWith("--")) {
       if (isTemplateString(val)) {
         effect(() => {
-          el.style.setProperty(prop, transposeCanvasUnits(evaluateTemplate(val, state)));
+          el.style.setProperty(prop, canvasStyleValue(evaluateTemplate(val, state)));
         });
       } else {
-        el.style.setProperty(prop, transposeCanvasUnits(scalar));
+        el.style.setProperty(prop, canvasStyleValue(scalar));
       }
     } else if (isTemplateString(val)) {
       effect(() => {
-        (el.style as unknown as Record<string, string>)[prop] = transposeCanvasUnits(
+        (el.style as unknown as Record<string, string>)[prop] = canvasStyleValue(
           evaluateTemplate(val, state),
         );
       });
     } else if (mediaOverriddenProps.has(prop)) {
-      // Goes through toCSSText (which transposes) — don't double-transpose here.
+      // Goes through toCSSText (which resolves and transposes) — don't do either twice here.
       baseDecls[prop] = scalar;
     } else {
-      (el.style as unknown as Record<string, string>)[prop] = transposeCanvasUnits(scalar);
+      (el.style as unknown as Record<string, string>)[prop] = canvasStyleValue(scalar);
     }
   }
 
@@ -1134,11 +1308,7 @@ export function applyStyle(
     if (key === "@--") {
       continue;
     } // Base canvas width, not a real media query
-    const query = key.startsWith("@--")
-      ? (mediaQueries[key.slice(1)] ?? key.slice(1))
-      : key.startsWith("@(")
-        ? key.slice(1)
-        : null;
+    const query = resolveAtQuery(key, mediaQueries);
     const atRule = query === null ? key : `@media ${query}`;
     const scope = `[data-jx="${uid}"]`;
     const scheme = query === null ? null : pureSchemeOf(query);
@@ -1201,12 +1371,17 @@ export function reapplyStyle(
 function applyAttributes(el: HTMLElement, attrs: Record<string, JxAttributeValue>, state: JxScope) {
   for (const [k, v] of Object.entries(attrs)) {
     const attr = canvasAttrName(el, k);
+    /* Inside the effects, not before them. A `$ref` or `${…}` value is not a string until the
+       effect runs — which is exactly why the document walk this replaced could never see it. */
+    const write = (resolved: unknown) => {
+      el.setAttribute(attr, canvasAssetValue(el.tagName, k, String(resolved ?? "")));
+    };
     if (isRefObj(v)) {
-      effect(() => el.setAttribute(attr, String(resolveRef(v.$ref, state) ?? "")));
+      effect(() => write(resolveRef(v.$ref, state)));
     } else if (isTemplateString(v)) {
-      effect(() => el.setAttribute(attr, String(evaluateTemplate(v, state))));
+      effect(() => write(evaluateTemplate(v, state)));
     } else {
-      el.setAttribute(attr, String(v));
+      write(v);
     }
   }
 }
@@ -2282,10 +2457,43 @@ export function camelToKebab(s: string) {
 export function toCSSText(rules: Record<string, unknown> | object) {
   return Object.entries(rules)
     .filter(([k, v]) => !isNestedSelector(k) && (v === null || typeof v !== "object"))
-    .map(([p, v]) => `${camelToKebab(p)}: ${transposeCanvasUnits(String(v))}`)
+    .map(([p, v]) => `${camelToKebab(p)}: ${canvasStyleValue(String(v))}`)
     .join("; ");
 }
 
+// ─── Style At-Rules ───────────────────────────────────────────────────────────
+
+/**
+ * The four CSS media types. A media _type_ is bare — `@media print` — while a media _feature_ is
+ * parenthesised, so `@media (print)` reads as a boolean feature named `print`, which does not exist
+ * and evaluates false.
+ */
+const MEDIA_TYPES = new Set(["all", "print", "screen", "speech"]);
+
+/**
+ * The media query an `@`-prefixed style key names, or null when the key is some other at-rule
+ * (`@supports`, `@starting-style`) that is emitted verbatim.
+ *
+ * `@--name` resolves through the project's `$media` map. `@(…)` carries its own parentheses, so
+ * they are stripped only when what they wrap is a bare media type: `@(print)` must become `@media
+ * print`, while `@(min-width: 40rem)` keeps them.
+ *
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @returns {string | null}
+ * @docs framework/concepts/styling
+ */
+export function resolveAtQuery(atKey: string, mediaQueries: Record<string, string>): string | null {
+  if (atKey.startsWith("@--")) {
+    return mediaQueries[atKey.slice(1)] ?? atKey.slice(1);
+  }
+  if (atKey.startsWith("@(")) {
+    const inner = atKey.slice(2, -1).trim();
+    return MEDIA_TYPES.has(inner.toLowerCase()) ? inner : atKey.slice(1);
+  }
+  return null;
+}
+
 // ─── Color Schemes ────────────────────────────────────────────────────────────
 
 /**
@@ -2424,15 +2632,17 @@ function injectHead(entries: JxHeadEntry[], _base: string) {
     // Resolve href/src: bare npm specifiers -> /node_modules/ path
     for (const key of ["href", "src"] as const) {
       const v = attrs[key];
-      if (
-        typeof v === "string" &&
-        v &&
-        !v.startsWith("/") &&
-        !v.startsWith(".") &&
-        !v.startsWith("http")
-      ) {
+      if (typeof v !== "string" || v === "") {
+        continue;
+      }
+      if (!v.startsWith("/") && !v.startsWith(".") && !v.startsWith("http")) {
+        /* The bare-specifier lane owns `/node_modules/<pkg>`, which is the HOST's URL space and
+           not the project's. A canvas resolver must never claim it: the file is not in the
+           repository, so there is nothing for it to resolve to. */
         attrs[key] = `/node_modules/${v}`;
+        continue;
       }
+      attrs[key] = canvasAssetValue(tag.toUpperCase(), key, v);
     }
 
     // Deduplicate: skip if an identical element already exists
@@ -2522,7 +2732,8 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
 
       const state = await buildScope(def, {}, base);
 
-      // Read properties from directive encoding (markdown → data-jx-props)
+      // Read properties from the data-jx-props payload the site build writes on a
+      // Non-static instance, so an upgrade re-renders with the authored props, not the defaults.
       const propsAttr = this.dataset.jxProps;
       if (propsAttr) {
         try {
@@ -2608,6 +2819,14 @@ export async function defineElement(source: string | JxDocument, baseUrl?: strin
       applyStyle(this, def.style ?? {}, (state["$media"] as Record<string, string>) ?? {}, state);
       applyAttributes(this, def.attributes ?? {}, state);
 
+      /*
+       * Root-level `textContent` is a definition's content just as much as `children` is — it is
+       * the shape spec.md §17.2 recommends when every child would be a bare string — and it was
+       * dropped here, so such a component rendered empty everywhere the interpreter runs.
+       */
+      if (!Array.isArray(def.children) && def.textContent !== undefined) {
+        bindProperty(this, "textContent", def.textContent, state);
+      }
       const children = Array.isArray(def.children) ? def.children : [];
       for (const childDef of children) {
         this.append(renderNode(childDef, state));
@@ -2680,20 +2899,27 @@ function renderCustomElementWithProps(
     if (refusePrivateProp(key, "$props")) {
       continue;
     }
+    /* The same resolution `bindProperty` gives an ordinary element. A `$props: { src }` on a custom
+       element is an asset reference authored at the USAGE site, so it belongs to the document that
+       wrote it — a media prop the component forwards into its own `<img>` is resolved separately,
+       inside the component's render, against the same context. */
+    const write = (resolved: unknown): void => {
+      (el as unknown as Record<string, unknown>)[key] =
+        typeof resolved === "string" ? canvasAssetValue(el.tagName, key, resolved) : resolved;
+    };
     if (isRefObj(val)) {
       const refVal = val;
-      const resolved = resolveRef(refVal.$ref, state);
-      (el as unknown as Record<string, unknown>)[key] = resolved;
+      write(resolveRef(refVal.$ref, state));
       // Reactive forwarding: re-set the property when the source changes
       effect(() => {
-        (el as unknown as Record<string, unknown>)[key] = resolveRef(refVal.$ref, state);
+        write(resolveRef(refVal.$ref, state));
       });
     } else if (isTemplateString(val)) {
       effect(() => {
-        (el as unknown as Record<string, unknown>)[key] = evaluateTemplate(val, state);
+        write(evaluateTemplate(val, state));
       });
     } else {
-      (el as unknown as Record<string, unknown>)[key] = val;
+      write(val);
     }
   }
 

package/src/types.ts

@@ -15,6 +15,8 @@ export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
 
 export interface JxRenderOptions {
   _path?: JxPath;
+  /** The namespace the parent element established — SVG and MathML descendants inherit it. */
+  _ns?: string | null;
   /**
    * Called for each created node. `state` is the local scope the node's children render with —
    * callers can capture it to re-render a subtree in isolation later.