@jxsuite/runtime 2.0.5 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "2.0.5",
+  "version": "3.0.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -18,7 +18,8 @@
     "./expression": "./src/expression.ts",
     "./pointer": "./src/pointer.ts",
     "./statements": "./src/statements.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./dist/runtime.js": "./dist/runtime.js"
   },
   "publishConfig": {
     "provenance": true
@@ -28,13 +29,13 @@
     "build:metafile": "bun build ./src/runtime.ts --outdir dist --target browser --sourcemap=linked --metafile=metafile.json",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.8.1",
+    "@jxsuite/schema": "^2.0.0",
     "@vue/reactivity": "3.5.41"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6"
+    "@happy-dom/global-registrator": "^20.11.8"
   }
 }

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 {
@@ -102,7 +103,11 @@ export async function Jx(
   target: HTMLElement = document.body,
   options?: JxRenderOptions,
 ) {
-  const base = typeof source === "string" ? new URL(source, location.href).href : location.href;
+  const base = options?.base
+    ? new URL(options.base, location.href).href
+    : typeof source === "string"
+      ? new URL(source, location.href).href
+      : location.href;
   const doc = await resolve(source);
   checkSchemaVersion(doc.$schema);
 
@@ -331,6 +336,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
@@ -597,6 +715,71 @@ function evaluateTemplate(str: string, state: JxScope): string {
   return fn(state, $map, $map?.item, $map?.index);
 }
 
+/**
+ * Whether a template is ONE expression end to end — `"${a.b}"` rather than `"a ${b}"` or
+ * `"${a}${b}"`.
+ *
+ * Depth-counted rather than pattern-matched. A greedy `/^\$\{(.+)\}$/` also matched `"${a} /
+ * ${b}"`, spliced the interior into `return (a} / ${b)`, and the SyntaxError became a silent null:
+ * the node rendered empty and a `$head` entry shipped its own template text. A brace scan is exact
+ * where a tightened regex is not — `"${`${a}-x`}"` is still one expression, and must keep its raw
+ * value.
+ *
+ * Lives here rather than in the compiler because both renderers must draw the line in the same
+ * place. It is what decides whether a value keeps its own type, and a value that is a boolean in
+ * one renderer and the string `"false"` in the other is a page that changes meaning as it
+ * hydrates.
+ *
+ * @param {string} str - Template source
+ * @returns {boolean} True when the whole string is a single `${…}`
+ */
+export function isSingleExpression(str: string): boolean {
+  if (!str.startsWith("${") || !str.endsWith("}")) {
+    return false;
+  }
+  let depth = 0;
+  for (let i = 1; i < str.length; i += 1) {
+    const c = str[i];
+    if (c === "{") {
+      depth += 1;
+    } else if (c === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return i === str.length - 1;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Evaluate a template for an ATTRIBUTE, keeping the expression's own type.
+ *
+ * `evaluateTemplate` interpolates into a string, which is what text wants and what an attribute
+ * cannot afford: `"${state.expanded}"` has to arrive as the boolean `false`, or `booleanAttrValue`
+ * never sees a boolean, `open="false"` is written, and HTML reads that as open. Only a single
+ * expression can carry a type at all — `"a ${b}"` is text by construction — which is the same line
+ * `evaluateStaticTemplate` draws in the compiler, and drawing it identically is what keeps a
+ * prerendered page and the same document rendered live in agreement.
+ *
+ * @param {string} str - Template source
+ * @param {JxScope} state - Reactive scope
+ * @returns {unknown} The expression's value, or the interpolated string
+ */
+function evaluateAttrTemplate(str: string, state: JxScope): unknown {
+  if (!isSingleExpression(str)) {
+    return evaluateTemplate(str, state);
+  }
+  const $map = state?.$map as { item?: unknown; index?: number } | undefined;
+  const fn = new Function("state", "$map", "item", "index", `return (${str.slice(2, -1)})`) as (
+    state: JxScope,
+    $map: unknown,
+    item: unknown,
+    index: number | undefined,
+  ) => unknown;
+  return fn(state, $map, $map?.item, $map?.index);
+}
+
 // ─── Step 2b: Function resolution (Shape 4) ─────────────────────────────────
 
 /** Shape of a dynamically imported module: named exports plus an optional default. */
@@ -761,6 +944,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 +1052,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 +1083,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 +1182,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 +1207,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 +1215,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 +1281,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 +1377,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);
@@ -1193,6 +1432,45 @@ export function reapplyStyle(
   applyStyle(el, styleDef ?? {}, mediaQueries, state);
 }
 
+/*
+ * HTML carries a boolean two incompatible ways, and writing one as the other inverts it in silence.
+ *
+ * A *boolean attribute* — `open`, `disabled`, `hidden`, `required` — is read by PRESENCE. Any value
+ * at all counts as true, `"false"` included, so `<details open="false">` is an OPEN `<details>`.
+ * The value must never be written; absence is the only way to say false.
+ *
+ * An *enumerated* attribute carries the word in its own text and reads an empty value as unset, so
+ * the presence form is the broken one here: bare `aria-hidden` is NOT hidden, and a dropped
+ * `contenteditable` means "inherit from the parent" rather than `false`. Every `aria-*` is in this
+ * family — ARIA has no presence attributes at all — along with the three HTML attributes below.
+ *
+ * @docs framework/concepts/elements
+ */
+const ENUMERATED_ATTRS = new Set(["contenteditable", "draggable", "spellcheck"]);
+
+/**
+ * The text an attribute's boolean value must be written with, or `null` when saying it means
+ * removing the attribute instead.
+ *
+ * An empty string is the bare form: `setAttribute(name, "")` is how the DOM spells the `open` that
+ * HTML source writes with no `=`.
+ *
+ * Shared rather than restated because two renderers must agree. The compiler writes attributes into
+ * a string of HTML and this file writes them onto live elements; were they to disagree about which
+ * family an attribute belongs to, a prerendered page would change meaning as it hydrated.
+ *
+ * @param {string} name - Attribute name, already resolved to what will be written
+ * @param {boolean} value - The resolved boolean
+ * @returns {string | null} Text to write, or null to omit the attribute
+ */
+export function booleanAttrValue(name: string, value: boolean): string | null {
+  const lower = name.toLowerCase();
+  if (lower.startsWith("aria-") || ENUMERATED_ATTRS.has(lower)) {
+    return String(value);
+  }
+  return value ? "" : null;
+}
+
 /**
  * @param {HTMLElement} el
  * @param {Record<string, import("@jxsuite/schema/types").JxAttributeValue>} attrs
@@ -1201,12 +1479,30 @@ 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) => {
+      if (typeof resolved === "boolean") {
+        const text = booleanAttrValue(attr, resolved);
+        /* `removeAttribute`, not `setAttribute(attr, "false")`. A binding that flips back has to
+           take the attribute WITH it: the element is being re-used, so anything left behind is the
+           state the page just said it had left. Asset rewriting is skipped because a boolean names
+           no asset — `canvasAssetValue` reads `src`/`href` values, which are never booleans. */
+        if (text === null) {
+          el.removeAttribute(attr);
+        } else {
+          el.setAttribute(attr, text);
+        }
+        return;
+      }
+      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(evaluateAttrTemplate(v, state)));
     } else {
-      el.setAttribute(attr, String(v));
+      write(v);
     }
   }
 }
@@ -2282,10 +2578,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 +2753,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 +2853,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 +2940,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 +3020,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,19 @@ export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
 
 export interface JxRenderOptions {
   _path?: JxPath;
+  /**
+   * Base URL the document's own references resolve against — `$ref`, `$elements`, `$head` and the
+   * asset paths beneath them.
+   *
+   * Only {@link Jx} reads it, and only when it was handed a document OBJECT rather than a URL. A URL
+   * carries its own base; an object does not, so the base defaulted to `location.href` — which is
+   * right for a page served at the project root and wrong everywhere else. A host that composes a
+   * document server-side and serves it at `/blog/hello/` needs to say that its references are still
+   * root-relative, or every one of them resolves a directory too deep.
+   */
+  base?: string;
+  /** 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.