npm - @dom-expressions/runtime - Versions diffs - 0.50.0-next.16 → 0.50.0-next.17 - Mend

@dom-expressions/runtime 0.50.0-next.16 → 0.50.0-next.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,30 @@
 # dom-expressions
+## 0.50.0-next.17
+### Patch Changes
+- ef2864e: Add a client-side asset registry and an `inline-style` server asset type, closing the CSS lifecycle loop for SSR'd applications.
+  **`acquireAsset(descriptor)` (client)** — ref-counted ownership of shared document assets. Consumers (routers, lazy wrappers, metadata components) acquire an asset when content that needs it mounts and call the returned release function on cleanup:
+  ```js
+  const release = acquireAsset({ type: "style", href: "/assets/route.css" });
+  // … on unmount:
+  release();
+  ```
+  - First acquire creates the element in `<head>` — or adopts an SSR/stream-emitted one (links matched by `href`, inline styles by their `data-asset` id) instead of duplicating it.
+  - Last release removes the element after a short grace period, so release/re-acquire cycles during route transitions keep the live stylesheet instead of flashing unstyled content.
+  - Supported descriptors: `{ type: "style", href, attrs? }`, `{ type: "inline-style", id, content?, attrs? }`, `{ type: "module", href }`.
+  - Additionally, `{ policy: "exclusive", key, value, get, set }` provides singleton-slot semantics (last-writer-wins with restore-on-release) as the substrate for future `<Title>`/`<Meta>`-style metadata components.
+  **`registerAsset("inline-style", { id, content, attrs? })` (server)** — registers CSS by content rather than URL, for styles that have no `.css` file to link (dev-mode CSS collected from the bundler's module graph, critical CSS). Entries dedupe by `id` and emit as `<style data-asset="…">` tags: in `<head>` for anything registered before the shell flushes, inline in the stream for late boundary styles. Extra `attrs` pass through to the tag (e.g. `data-vite-dev-id` so Vite's HMR client adopts the server-rendered style in dev). Unlike stylesheet links, inline styles never gate streamed fragment reveal — they are applied as soon as they are parsed.
+- 241ff76: Fix a spread element with dynamic props being left unclaimed on hydration. `mergeProps` with a function source creates a memo, which consumes a hydration child id. The ssr generate evaluated `mergeProps(...)` in `ssrElement`'s argument position — before the element's own hydration key was allocated — while the client claims the element (`getNextElement`) before applying the spread. The element's id shifted by one on the server and the client re-created it instead of claiming (later siblings re-synced, hiding the drift; a `<title>` rendered this way duplicated on every hydration). The ssr generate now defers the merge behind a thunk when hydratable and `ssrElement` allocates the hydration key before resolving function props, matching the client's allocation order.
+- 2c6852f: Root-level inserts no longer wipe foreign sibling nodes when clearing or replacing their content. Streaming appends late-flushed `<link rel="stylesheet">` tags to the end of `<body>`, inside the region a document-level hydration root tracks; previously a root expression that emptied (`textContent = ""` fast path) or swapped to text took those links with it, dropping loaded CSS (FOUC). `insert` now removes only the nodes it tracks when the parent contains children it doesn't own, keeping the fast path when it owns everything. Also documents that `registerModule` / `loadModuleAssets` mapping keys are opaque to the runtime — the reactive library chooses them (e.g. hydration ids) on both sides of the wire.
+- 2275d59: Align SSR serialization of non-string attribute values (arrays, objects) with client-side `setAttribute` coercion so both environments produce the same final attribute string.
 ## 0.50.0-next.16
 ### Patch Changes

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@dom-expressions/runtime",
   "description": "A Fine-Grained Runtime for Performant DOM Rendering",
-  "version": "0.50.0-next.16",
+  "version": "0.50.0-next.17",
   "author": "Ryan Carniato",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     "csstype": "^3.1",
     "seroval": "~1.5.0",
     "seroval-plugins": "~1.5.0",
-    "@dom-expressions/babel-plugin-jsx": "0.50.0-next.16"
+    "@dom-expressions/babel-plugin-jsx": "0.50.0-next.17"
   },
   "scripts": {
     "test": "jest --no-cache",

package/src/client.d.ts CHANGED Viewed

@@ -103,6 +103,19 @@ export function getNextMatch(start: Node, elementName: string): Element;
 export function getNextMarker(start: Node): [Node, Array<Node>];
 export function useAssets(fn: () => JSX.Element): void;
 export function getAssets(): string;
+export type AssetDescriptor =
+  | { type: "style"; href: string; attrs?: Record<string, string> }
+  | { type: "inline-style"; id: string; content?: string; attrs?: Record<string, string> }
+  | { type: "module"; href: string }
+  | ExclusiveAssetDescriptor<any>;
+export interface ExclusiveAssetDescriptor<T> {
+  policy: "exclusive";
+  key: string;
+  value: T;
+  get(): T;
+  set(value: T): void;
+}
+export function acquireAsset(descriptor: AssetDescriptor): () => void;
 export function HydrationScript(props?: { nonce?: string; eventNames?: string[] }): JSX.Element;
 export function generateHydrationScript(options?: {
   nonce?: string;

package/src/client.js CHANGED Viewed

@@ -459,27 +459,147 @@ export function assign(node, props, skipChildren, prevProps = {}, skipRef = fals
   }
 }
-// Module asset loading for hydration
+// ---- Asset Registry ----
+//
+// Ref-counted client-side ownership of shared document assets. Consumers
+// (routers, lazy wrappers, metadata components) acquire an asset when content
+// that needs it mounts and release it on cleanup; the element is created — or
+// an SSR/stream-emitted one adopted — on the first acquire and removed
+// shortly after the last release. The removal grace period lets quick
+// release/re-acquire cycles (route transitions sharing CSS) reuse the live
+// element instead of flashing unstyled content while it reloads.
+//
+// Descriptor forms:
+//   { type: "style", href, attrs? }               → <link rel="stylesheet">
+//   { type: "inline-style", id, content?, attrs? } → <style data-asset={id}>
+//   { type: "module", href }                       → <link rel="modulepreload">
+//   { policy: "exclusive", key, value, get, set }  → singleton slot
+//
+// Exclusive slots implement last-writer-wins with restore-on-release (the
+// title/meta ownership model): the newest acquire's value is applied via
+// `set`; releasing it re-applies the previous writer's value, and the
+// original document value (captured with `get` on first acquire) once every
+// writer has released.
+const ASSET_REMOVAL_GRACE = 100;
+const assetRegistry = new Map();
+function assetEntryKey(descriptor) {
+  if (descriptor.policy === "exclusive") return "x|" + descriptor.key;
+  return descriptor.type === "inline-style"
+    ? "i|" + descriptor.id
+    : descriptor.type + "|" + descriptor.href;
+}
+// Attribute-compared lookup (instead of an attribute selector) so href/id
+// values never need selector escaping.
+function findAssetElement(selector, attr, value) {
+  const nodes = document.querySelectorAll(selector);
+  for (let i = 0; i < nodes.length; i++) {
+    if (nodes[i].getAttribute(attr) === value) return nodes[i];
+  }
+  return null;
+}
+function mountAssetElement(descriptor) {
+  let el;
+  if (descriptor.type === "inline-style") {
+    el = findAssetElement("style[data-asset]", "data-asset", descriptor.id);
+    if (!el) {
+      el = document.createElement("style");
+      el.setAttribute("data-asset", descriptor.id);
+      el.textContent = descriptor.content || "";
+    }
+  } else {
+    const rel = descriptor.type === "module" ? "modulepreload" : "stylesheet";
+    el = findAssetElement(`link[rel="${rel}"]`, "href", descriptor.href);
+    if (!el) {
+      el = document.createElement("link");
+      el.rel = rel;
+      el.href = descriptor.href;
+    }
+  }
+  if (descriptor.attrs) {
+    for (const name in descriptor.attrs) el.setAttribute(name, descriptor.attrs[name]);
+  }
+  if (!el.isConnected) document.head.appendChild(el);
+  return el;
+}
+export function acquireAsset(descriptor) {
+  const key = assetEntryKey(descriptor);
+  let entry = assetRegistry.get(key);
+  if (descriptor.policy === "exclusive") {
+    if (!entry) {
+      entry = { original: descriptor.get(), set: descriptor.set, writers: [] };
+      assetRegistry.set(key, entry);
+    }
+    const writer = { value: descriptor.value };
+    entry.writers.push(writer);
+    entry.set(writer.value);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const index = entry.writers.indexOf(writer);
+      const wasTop = index === entry.writers.length - 1;
+      entry.writers.splice(index, 1);
+      if (!wasTop) return;
+      if (entry.writers.length) {
+        entry.set(entry.writers[entry.writers.length - 1].value);
+      } else {
+        entry.set(entry.original);
+        assetRegistry.delete(key);
+      }
+    };
+  }
+  if (!entry) {
+    entry = { count: 0, element: null, timer: null };
+    assetRegistry.set(key, entry);
+  }
+  if (entry.timer) {
+    clearTimeout(entry.timer);
+    entry.timer = null;
+  }
+  entry.count++;
+  if (!entry.element || !entry.element.isConnected) entry.element = mountAssetElement(descriptor);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--entry.count > 0) return;
+    entry.timer = setTimeout(() => {
+      assetRegistry.delete(key);
+      entry.element && entry.element.remove();
+    }, ASSET_REMOVAL_GRACE);
+  };
+}
+// Module asset loading for hydration. `mapping` pairs opaque keys with
+// client-loadable entry URLs. Keys are chosen by the reactive library's
+// server-side lazy() (e.g. hydration ids) and are never interpreted here —
+// they only need to match what the client-side lazy() looks up in
+// `_$HY.modules` after preload.
 function loadModuleAssets(mapping) {
   const hy = globalThis._$HY;
   if (!hy) return;
   const pending = [];
-  for (const moduleUrl in mapping) {
-    if (hy.modules[moduleUrl]) continue;
-    const entryUrl = mapping[moduleUrl];
-    if (!hy.loading[moduleUrl]) {
-      hy.loading[moduleUrl] = import(/* @vite-ignore */ entryUrl).then(
+  for (const key in mapping) {
+    if (hy.modules[key]) continue;
+    const entryUrl = mapping[key];
+    if (!hy.loading[key]) {
+      hy.loading[key] = import(/* @vite-ignore */ entryUrl).then(
         mod => {
-          hy.modules[moduleUrl] = mod;
+          hy.modules[key] = mod;
         },
         err => {
           // drop the rejected entry so a later boundary/navigation can retry
-          delete hy.loading[moduleUrl];
+          delete hy.loading[key];
           throw err;
         }
       );
     }
-    pending.push(hy.loading[moduleUrl]);
+    pending.push(hy.loading[key]);
   }
   return pending.length ? Promise.all(pending).then(() => {}) : undefined;
 }
@@ -899,7 +1019,16 @@ function insertExpression(parent, value, current, marker) {
     const tc = typeof current;
     if (tc === "string" || tc === "number") {
       parent.firstChild.data = value;
-    } else parent.textContent = value;
+    } else {
+      const owned = ownedChildCount(current);
+      if (owned === -1 || owned === parent.childNodes.length) parent.textContent = value;
+      else {
+        // Foreign nodes present (e.g. stream-injected stylesheet links) —
+        // replace only our own nodes, keeping text content leading.
+        removeOwnedChildren(parent, current);
+        parent.insertBefore(document.createTextNode(value), parent.firstChild);
+      }
+    }
   } else if (value === undefined) {
     cleanChildren(parent, current, marker);
   } else if (value.nodeType) {
@@ -928,7 +1057,7 @@ function insertExpression(parent, value, current, marker) {
         appendNodes(parent, value, marker);
       } else reconcileArrays(parent, current, value, marker);
     } else {
-      current && cleanChildren(parent);
+      current && cleanChildren(parent, current);
       appendNodes(parent, value);
     }
   } else if ("_DX_DEV_") console.warn(`Unrecognized value. Skipped inserting`, value);
@@ -977,8 +1106,45 @@ function appendNodes(parent, array, marker = null) {
   }
 }
+// Number of parent children the tracked `current` value accounts for, or -1
+// when unknown (initial render / untracked content — the whole parent is
+// considered owned, preserving the designed clear-on-first-render behavior).
+function ownedChildCount(current) {
+  if (Array.isArray(current)) return current.length;
+  if (current == null) return -1;
+  if (current === "") return 0; // `textContent = ""` left no node behind
+  return 1; // single node, or a string/number rendered as one text node
+}
+// Remove only the nodes tracked by `current` from a root-level (markerless)
+// region, leaving foreign siblings in place.
+function removeOwnedChildren(parent, current) {
+  if (Array.isArray(current)) {
+    for (let i = 0; i < current.length; i++) {
+      const el = current[i];
+      if (el.parentNode === parent) el.remove();
+    }
+  } else if (current.nodeType) {
+    if (current.parentNode === parent) current.remove();
+  } else {
+    // string/number content lives in a leading text node (set via
+    // `textContent = value`, before any foreign node was appended).
+    const first = parent.firstChild;
+    if (first && first.nodeType === 3) first.remove();
+  }
+}
 function cleanChildren(parent, current, marker, replacement) {
-  if (marker === undefined) return (parent.textContent = "");
+  if (marker === undefined) {
+    // Root-level clear (no marker). `textContent = ""` wipes every child,
+    // which is only safe when the nodes we track are the parent's only
+    // children. Streaming can append foreign nodes to the root (late-flushed
+    // stylesheet <link>s land at the end of <body>) and those must survive a
+    // re-render — wiping them drops loaded CSS.
+    const owned = ownedChildCount(current);
+    if (owned === -1 || owned === parent.childNodes.length) return (parent.textContent = "");
+    return removeOwnedChildren(parent, current);
+  }
   if (current.length) {
     let inserted = false;
     for (let i = current.length - 1; i >= 0; i--) {

package/src/server.d.ts CHANGED Viewed

@@ -192,3 +192,5 @@ export function ref(
 ): void;
 /** @deprecated not supported on the server side */
 export function setStyleProperty(node: Element, name: string, value: any): void;
+/** @deprecated not supported on the server side — register assets through the render context instead */
+export function acquireAsset(descriptor: unknown): () => void;

package/src/server.js CHANGED Viewed

@@ -82,25 +82,49 @@ function createAssetTracking() {
   const boundaryModules = new Map();
   const boundaryStyles = new Map();
   const emittedAssets = new Set();
+  const inlineStyles = new Map();
   let currentBoundaryId = null;
   return {
     boundaryModules,
     boundaryStyles,
     emittedAssets,
+    inlineStyles,
+    // Inline styles (dev CSS collected from the module graph, critical CSS)
+    // dedupe by `id` — repeated registrations reuse the same entry object so
+    // boundary Sets and the head injection never emit the same style twice.
+    registerInlineStyle(desc) {
+      let entry = inlineStyles.get(desc.id);
+      if (!entry) {
+        entry = { id: desc.id, content: desc.content || "", attrs: desc.attrs, emitted: false };
+        inlineStyles.set(desc.id, entry);
+      }
+      if (currentBoundaryId) {
+        let styles = boundaryStyles.get(currentBoundaryId);
+        if (!styles) {
+          styles = new Set();
+          boundaryStyles.set(currentBoundaryId, styles);
+        }
+        styles.add(entry);
+      }
+      return entry;
+    },
     get currentBoundaryId() {
       return currentBoundaryId;
     },
     set currentBoundaryId(v) {
       currentBoundaryId = v;
     },
-    registerModule(moduleUrl, entryUrl) {
+    // `key` is opaque to the runtime — the reactive library's server-side
+    // lazy() picks it (e.g. a hydration id) and its client-side counterpart
+    // looks preloaded modules up under the same key after loadModuleAssets.
+    registerModule(key, entryUrl) {
       const id = currentBoundaryId || "";
       let map = boundaryModules.get(id);
       if (!map) {
         map = {};
         boundaryModules.set(id, map);
       }
-      map[moduleUrl] = entryUrl;
+      map[key] = entryUrl;
     },
     getBoundaryModules(id) {
       return boundaryModules.get(id) || null;
@@ -178,16 +202,20 @@ export function renderToString(code, options = {}) {
       }
       serializer.write(id, p);
     },
-    registerAsset(type, url) {
+    registerAsset(type, value) {
+      if (type === "inline-style") {
+        tracking.registerInlineStyle(value);
+        return;
+      }
       if (tracking.currentBoundaryId && type === "style") {
         let styles = tracking.boundaryStyles.get(tracking.currentBoundaryId);
         if (!styles) {
           styles = new Set();
           tracking.boundaryStyles.set(tracking.currentBoundaryId, styles);
         }
-        styles.add(url);
+        styles.add(value);
       }
-      tracking.emittedAssets.add(url);
+      tracking.emittedAssets.add(value);
     }
   };
   applyAssetTracking(sharedConfig.context, tracking, manifest);
@@ -204,6 +232,7 @@ export function renderToString(code, options = {}) {
   serializer.close();
   html = injectAssets(sharedConfig.context.assets, html);
   html = injectPreloadLinks(tracking.emittedAssets, html, nonce);
+  html = injectInlineStyles(tracking.inlineStyles, html, nonce);
   if (scripts.length) html = injectScripts(html, scripts, options.nonce);
   return html;
 }
@@ -313,19 +342,30 @@ export function renderToStream(code, options = {}) {
     async: true,
     assets: [],
     nonce,
-    registerAsset(type, url) {
+    registerAsset(type, value) {
+      if (type === "inline-style") {
+        const entry = tracking.registerInlineStyle(value);
+        // Boundary-attributed inline styles flush with their fragment; a late
+        // registration outside any boundary has no other emission point, so
+        // write the tag into the stream immediately.
+        if (firstFlushed && !tracking.currentBoundaryId && !entry.emitted) {
+          entry.emitted = true;
+          buffer.write(renderInlineStyle(entry, nonce));
+        }
+        return;
+      }
       if (tracking.currentBoundaryId && type === "style") {
         let styles = tracking.boundaryStyles.get(tracking.currentBoundaryId);
         if (!styles) {
           styles = new Set();
           tracking.boundaryStyles.set(tracking.currentBoundaryId, styles);
         }
-        styles.add(url);
+        styles.add(value);
       }
-      if (!tracking.emittedAssets.has(url)) {
-        tracking.emittedAssets.add(url);
+      if (!tracking.emittedAssets.has(value)) {
+        tracking.emittedAssets.add(value);
         if (firstFlushed && type === "module") {
-          buffer.write(`<link rel="modulepreload" href="${url}">`);
+          buffer.write(`<link rel="modulepreload" href="${value}">`);
         }
       }
     },
@@ -418,10 +458,15 @@ export function renderToStream(code, options = {}) {
               serializeFragmentAssets(key, tracking.boundaryModules, context);
               const styles = collectStreamStyles(key, tracking, headStyles);
               const deferActivation = !!revealGroup;
-              if (styles.length) {
-                emitTask(`$dfs("${key}",${styles.length},${deferActivation ? 1 : 0})`);
+              // Inline styles apply as soon as the parser sees them — emit
+              // before the template, no load gating needed.
+              for (let i = 0; i < styles.inline.length; i++) {
+                buffer.write(renderInlineStyle(styles.inline[i], nonce));
+              }
+              if (styles.links.length) {
+                emitTask(`$dfs("${key}",${styles.links.length},${deferActivation ? 1 : 0})`);
                 writeTasks();
-                for (const url of styles) {
+                for (const url of styles.links) {
                   buffer.write(
                     `<link rel="stylesheet" href="${url}" onload="$dfc('${key}')" onerror="$dfc('${key}')">`
                   );
@@ -516,6 +561,7 @@ export function renderToStream(code, options = {}) {
       if (url.endsWith(".css")) headStyles.add(url);
     }
     html = injectPreloadLinks(tracking.emittedAssets, html, nonce);
+    html = injectInlineStyles(tracking.inlineStyles, html, nonce);
     serializeRootAssets();
     if (tasks.length) html = injectScripts(html, tasks, nonce);
     buffer.write(html);
@@ -870,11 +916,17 @@ export function ssrStyleProperty(name, value) {
 // review with new ssr
 export function ssrElement(tag, props, children, needsId) {
+  // The hydration key must be allocated before the props thunk runs: dynamic
+  // props (`mergeProps(() => ...)`) create a memo, which consumes a child id.
+  // The client claims the element (getNextElement) before applying the spread,
+  // so the server must allocate in the same order or the element's own id
+  // shifts by one and it is left unclaimed on hydration.
+  const hk = needsId ? ssrHydrationKey() : "";
   if (props == null) props = {};
   else if (typeof props === "function") props = props();
   const skipChildren = VOID_ELEMENTS.test(tag);
   const keys = Object.keys(props);
-  let result = `<${tag}${needsId ? ssrHydrationKey() : ""} `;
+  let result = `<${tag}${hk} `;
   for (let i = 0; i < keys.length; i++) {
     const prop = keys[i];
     if (ChildProperties.has(prop)) {
@@ -935,7 +987,16 @@ export function escape(s, attr) {
       for (let i = 0; i < s.length; i++) s[i] = escape(s[i]);
       return s;
     }
-    if (attr && t === "boolean") return s;
+    if (attr) {
+      // Nullish and boolean values pass through so callers can omit the
+      // attribute or emit it as a boolean attribute. Numbers can never
+      // contain `&` or `"`. Everything else (arrays, objects, symbols)
+      // would be stringified by the surrounding template literal anyway,
+      // so coerce to the final string here first — matching what the
+      // client DOM receives — and run it through the normal string path.
+      if (s == null || t === "boolean" || t === "number") return s;
+      return escape(String(s), attr);
+    }
     return s;
   }
   // Fast path: single forward pass over the string. Most values (color
@@ -1100,16 +1161,56 @@ function propagateBoundaryStyles(childKey, parentKey, tracking) {
   }
 }
+// Boundary style sets hold two kinds of entries: url strings (stylesheet
+// links, load-gated via $dfs) and inline style entry objects (emitted as
+// <style> tags, ready as soon as parsed). Splits them for the fragment
+// flush, consuming inline entries so they emit at most once.
 function collectStreamStyles(key, tracking, headStyles) {
   const styles = tracking.getBoundaryStyles(key);
-  if (!styles) return [];
-  const result = [];
-  for (const url of styles) {
-    if (!headStyles || !headStyles.has(url)) {
-      result.push(url);
+  const links = [];
+  const inline = [];
+  if (!styles) return { links, inline };
+  for (const entry of styles) {
+    if (typeof entry === "string") {
+      if (!headStyles || !headStyles.has(entry)) links.push(entry);
+    } else if (!entry.emitted) {
+      entry.emitted = true;
+      inline.push(entry);
     }
   }
-  return result;
+  return { links, inline };
+}
+// `</style` inside content would close the tag early; escaping the slash is
+// valid CSS and neutralizes the sequence.
+function escapeStyleContent(content) {
+  return content.replace(/<\/(style)/gi, "<\\/$1");
+}
+function renderInlineStyle(entry, nonce) {
+  let attrs = "";
+  if (entry.attrs) {
+    for (const name in entry.attrs) {
+      attrs += ` ${name}="${escape(String(entry.attrs[name]), true)}"`;
+    }
+  }
+  return `<style${nonce ? ` nonce="${nonce}"` : ""} data-asset="${escape(
+    entry.id,
+    true
+  )}"${attrs}>${escapeStyleContent(entry.content)}</style>`;
+}
+function injectInlineStyles(inlineStyles, html, nonce) {
+  if (!inlineStyles.size) return html;
+  const index = html.indexOf("</head>");
+  if (index === -1) return html;
+  let out = "";
+  for (const entry of inlineStyles.values()) {
+    if (entry.emitted) continue;
+    entry.emitted = true;
+    out += renderInlineStyle(entry, nonce);
+  }
+  return out ? html.slice(0, index) + out + html.slice(index) : html;
 }
 function injectScripts(html, scripts, nonce) {
@@ -1317,7 +1418,8 @@ export {
   notSup as getNextMarker,
   notSup as runHydrationEvents,
   notSup as ref,
-  notSup as setStyleProperty
+  notSup as setStyleProperty,
+  notSup as acquireAsset
 };
 function notSup() {