@dom-expressions/runtime 0.50.0-next.19 → 0.50.0-next.21

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # dom-expressions
 
+## 0.50.0-next.21
+
+### Patch Changes
+
+- 8e54049: Expose reusable Seroval serializer primitives from the runtime's serializer module. `createSerializer(options)` builds a streaming serializer preconfigured with the default web plugin set (custom plugins compose ahead of the defaults and can shadow them) and the ~ES2017 feature policy, targeting a caller-provided `globalIdentifier`. The SSR-specific configuration (pinned `_$HY.r` global) moves to `createHydrationSerializer(options)`, which `renderToString`/`renderToStream` now use internally — hydration output is unchanged. `DEFAULT_WEB_PLUGINS` and `resolveSerializerPlugins(customPlugins)` are also exported, the module's type declarations are corrected to match the implementation (they previously declared a nonexistent default export), and the render options' `plugins` typing is tightened from `any[]` to `SerializerPlugin[]`.
+
+  The module also gains an isomorphic JSON codec for RPC-style transports (e.g. server functions): `serializeJSON(value, { onParse, onDone, onError, ... })` streams a value as `SerovalNode` chunks (async values continue streaming as they resolve), and `createJSONDeserializer(options)` returns its decoding counterpart with cross-chunk reference state. Both share the web plugin resolution, and default to a transport-hardened policy (RegExp disabled, parse depth capped at 64) that can be overridden per peer. Wire framing of chunks is intentionally left to the transport. This is groundwork for sharing one serialization configuration between SSR hydration and server function transports.
+
+- e717d06: Fix streamed fragment swaps leaving fallback content behind when the fallback contains unrelated comment markers.
+- 2c4ab6b: Raise the seroval / seroval-plugins peer dependency floor from `~1.5.0` to `~1.5.4`: seroval 1.5.3 and earlier are affected by a security issue fixed in 1.5.4.
+
+## 0.50.0-next.20
+
+### Patch Changes
+
+- 9d5a90b: Queue streamed fragment activations whose `pl-*` marker is not yet in the live DOM instead of silently dropping them.
+
+  A fragment's marker can sit inside a flushed-but-unactivated ancestor `<template>` (a slot held by a reveal group). Template content is inert, so `document.getElementById` cannot see the marker and `$df`/`$dfl` previously returned `0` and lost the swap permanently — the fallback stayed stuck even though the content template had streamed. Today this window is masked because the server enrolls nested boundaries into the ancestor reveal group, but fixing that enrollment (solidjs/solid#2871, solidjs/solid#2872) makes nested boundaries activate independently, exposing the drop.
+
+  `$df` and `$dfl` now queue marker misses (`_$HY.dq` / `_$HY.dlq`) and a new `$dfd` drains both queues after every successful swap or fallback materialization — the only events that can bring queued markers into the live document. Content swaps drain before fallbacks so a settled fragment wins over its own pending fallback, and drains cascade through arbitrarily nested held levels. An activation whose content template is already consumed remains a plain no-op and is never queued.
+
 ## 0.50.0-next.19
 
 ### Patch Changes

package/package.json

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

package/src/serializer.d.ts

@@ -1,3 +1,97 @@
-import { Serializer } from "seroval";
+import { Plugin, Serializer, SerovalNode } from "seroval";
 
-export default function createSerializer(onData: (value: string) => void): Serializer;
+export type { SerovalNode };
+
+/** A Seroval plugin usable with the web serializers. */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
+ * and feature policy — only the wiring options (callbacks, scope, extra
+ * plugins) are configurable.
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/** Returns the cross-reference bootstrap script for a render scope. */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse`.
+ * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;

package/src/serializer.js

@@ -1,4 +1,10 @@
-import { Feature, Serializer, getCrossReferenceHeader } from "seroval";
+import {
+  Feature,
+  Serializer,
+  fromCrossJSON,
+  getCrossReferenceHeader,
+  toCrossJSONStream
+} from "seroval";
 import {
   AbortSignalPlugin,
   CustomEventPlugin,
@@ -13,36 +19,69 @@ import {
   URLSearchParamsPlugin
 } from "seroval-plugins/web";
 
-const ES2017FLAG =
-  Feature.AggregateError | // ES2021
-  Feature.BigIntTypedArray; // ES2020;
-
-const GLOBAL_IDENTIFIER = "_$HY.r"; // TODO this is a pending name
-
-export function createSerializer({ onData, onDone, scopeId, onError, plugins: customPlugins }) {
-  const defaultPlugins = [
-    AbortSignalPlugin,
-    // BlobPlugin,
-    CustomEventPlugin,
-    DOMExceptionPlugin,
-    EventPlugin,
-    // FilePlugin,
-    FormDataPlugin,
-    HeadersPlugin,
-    ReadableStreamPlugin,
-    RequestPlugin,
-    ResponsePlugin,
-    URLSearchParamsPlugin,
-    URLPlugin
-  ];
-
-  const allPlugins = customPlugins ? [...customPlugins, ...defaultPlugins] : defaultPlugins;
+// Features excluded from emitted scripts so output stays runnable on ~ES2017
+// targets (AggregateError is ES2021, BigInt typed arrays are ES2020).
+const DEFAULT_DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;
+
+// Part of the hydration wire protocol since the streaming serializer landed
+// (#275): the bootstrap from `generateHydrationScript` creates it and the
+// client runtime reads resolved values out of it. Terse on purpose — it ships
+// in every SSR payload.
+const HYDRATION_GLOBAL = "_$HY.r";
+
+/**
+ * Baseline plugin set for serializing web-platform values. Shared by the
+ * hydration serializer and any consumer building its own serializer (e.g.
+ * server function transports).
+ */
+export const DEFAULT_WEB_PLUGINS = Object.freeze([
+  AbortSignalPlugin,
+  // BlobPlugin,
+  CustomEventPlugin,
+  DOMExceptionPlugin,
+  EventPlugin,
+  // FilePlugin,
+  FormDataPlugin,
+  HeadersPlugin,
+  ReadableStreamPlugin,
+  RequestPlugin,
+  ResponsePlugin,
+  URLSearchParamsPlugin,
+  URLPlugin
+]);
+
+/**
+ * Composes user plugins with the default web set. Custom plugins come first
+ * so they can shadow a default for values both would match.
+ */
+export function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
 
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy. `globalIdentifier` is required and
+ * names the object the emitted scripts write resolved values into.
+ */
+export function createSerializer(options) {
   return new Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures:
+      options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures
+  });
+}
+
+/**
+ * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
+ * and feature policy — only the wiring options (callbacks, scope, extra
+ * plugins) are configurable.
+ */
+export function createHydrationSerializer({ onData, onDone, scopeId, onError, plugins }) {
+  return createSerializer({
     scopeId,
-    plugins: allPlugins,
-    globalIdentifier: GLOBAL_IDENTIFIER,
-    disabledFeatures: ES2017FLAG,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
     onData,
     onDone,
     onError
@@ -52,3 +91,58 @@ export function createSerializer({ onData, onDone, scopeId, onError, plugins: cu
 export function getLocalHeaderScript(id) {
   return getCrossReferenceHeader(id) + ";";
 }
+
+// ---- JSON codec (server function transports) ----
+//
+// Unlike hydration output (executable JS targeting a global), the JSON codec
+// streams SerovalNode values that a peer decodes without eval. Framing the
+// nodes on the wire (chunk delimiting, HTTP plumbing) is the transport's
+// concern; this layer only guarantees both sides agree on plugins and
+// feature policy.
+
+// Codec payloads may come from an untrusted peer, so the defaults protect
+// the decoding side: RegExp is disabled (ReDoS via deserialized patterns)
+// and parse depth is capped well below Seroval's own limit.
+const JSON_CODEC_DISABLED_FEATURES = Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+
+// Single source of truth for codec defaults — encode and decode must agree
+// on plugins and feature policy or payloads won't roundtrip.
+function resolveCodecOptions({ plugins, disabledFeatures, depthLimit } = {}) {
+  return {
+    plugins: resolveSerializerPlugins(plugins),
+    disabledFeatures:
+      disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
+    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
+  };
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through
+ * `onParse(node, initial)`. Async values (promises, streams) produce
+ * additional chunks as they resolve; `onDone` fires when everything has
+ * settled. Returns a cancel function that aborts any pending async
+ * serialization.
+ */
+export function serializeJSON(value, { onParse, onDone, onError, ...codecOptions }) {
+  return toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. The returned function
+ * deserializes one SerovalNode chunk at a time; cross-references between
+ * chunks resolve through a map shared across calls, so all chunks from one
+ * stream must go through the same deserializer instance.
+ */
+export function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return fromCrossJSON(node, { refs, ...resolved });
+  };
+}

package/src/server.d.ts

@@ -1,4 +1,5 @@
 import { JSX } from "./jsx.js";
+import { SerializerPlugin } from "./serializer.js";
 export const DOMWithState: Record<string, Record<string, 1 | 2>>;
 export const ChildProperties: Set<string>;
 export const DelegatedEvents: Set<string>;
@@ -62,7 +63,7 @@ export function renderToString<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
+    plugins?: SerializerPlugin[];
     manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
@@ -75,7 +76,7 @@ export function renderToStringAsync<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
+    plugins?: SerializerPlugin[];
     manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
@@ -86,7 +87,7 @@ export function renderToStream<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
+    plugins?: SerializerPlugin[];
     manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onCompleteShell?: (info: { write: (v: string) => void }) => void;
     onCompleteAll?: (info: { write: (v: string) => void }) => void;

package/src/server.js

@@ -1,6 +1,6 @@
 import { ChildProperties } from "./constants";
 import { sharedConfig, root, ssrHandleError, getOwner, runWithOwner } from "rxcore";
-import { createSerializer, getLocalHeaderScript } from "./serializer";
+import { createHydrationSerializer, getLocalHeaderScript } from "./serializer";
 
 // `mergeProps` comes from the framework like the client/universal entries —
 // prop-merge semantics (function sources, precedence) belong to the reactive
@@ -178,19 +178,29 @@ function applyAssetTracking(context, tracking, manifest) {
 const VOID_ELEMENTS =
   /^(?:area|base|br|col|embed|hr|img|input|keygen|link|menuitem|meta|param|source|track|wbr)$/i;
 // Fragment replacement helpers emitted into stream task scripts:
-// - $df(id): swap template payload into the `pl-*` marker range.
+// - $df(id): swap template payload into the `pl-*` marker range. A marker that
+//   isn't in the live DOM yet (it sits inside a flushed-but-unactivated ancestor
+//   template held by a reveal group) queues the id in `_$HY.dq` for retry instead
+//   of dropping the swap. A missing content template means the swap already ran —
+//   that stays a plain no-op and is never queued.
 // - $dfl(id): materialize fallback from `pl-*` template content without resolving.
+//   Marker misses queue in `_$HY.dlq`, same reasoning as $df.
 // - $dflj(ids): materialize fallback content for every id in the list.
+// - $dfd(): drain both retry queues. Runs after every successful swap or fallback
+//   materialization — the only events that can bring queued markers into the live
+//   document. Content swaps ($df) drain before fallbacks ($dfl) so a settled
+//   fragment wins over its own pending fallback. Each pass snapshots the queue,
+//   so still-inert entries simply re-queue and wait for the next swap.
 // - $dfs(id, count, defer): register pending stylesheet count for fragment `id`.
 // - $dfc(id): style completion callback; reveals when the fragment/group is unblocked.
 // - $dfg(id): group-style gate check; reveals a waiting group once all style counts hit zero.
 // - $dfj(ids): reveal a group in registration order, waiting if any member still has pending styles.
-const REPLACE_SCRIPT = `function $df(e,n,o,t){if(!(n=document.getElementById(e))||!(o=document.getElementById("pl-"+e)))return 0;for(;o&&8!==o.nodeType&&o.nodeValue!=="pl-"+e;)t=o.nextSibling,o.remove(),o=t;_$HY.done?o.remove():o.replaceWith(n.content),n.remove(),_$HY.fe(e);return 1}function $dfl(e,o,n){if(!(o=document.getElementById("pl-"+e)))return 0;if(o._$fl)return 1;for(n=o.nextSibling;n;){if(8===n.nodeType&&n.nodeValue==="pl-"+e){o.parentNode&&o.parentNode.insertBefore(o.content.cloneNode(!0),n),o._$fl=1;return 1}n=n.nextSibling}return 0}function $dflj(e,i){for(i=0;i<e.length;i++)$dfl(e[i])}function $dfs(e,c,d){(_$HY.sc=_$HY.sc||{})[e]=c,d&&((_$HY.sd=_$HY.sd||{})[e]=1)}function $dfg(e,g,i,k){if(!(g=_$HY.sg&&_$HY.sg[e]))return;for(i=0;i<g.length;i++)if(_$HY.sc&&_$HY.sc[g[i]]>0)return;for(i=0;i<g.length;i++)k=g[i],delete _$HY.sg[k],$df(k)}function $dfc(e){if(--_$HY.sc[e]<=0){delete _$HY.sc[e],_$HY.sg&&_$HY.sg[e]?$dfg(e):!(_$HY.sd&&_$HY.sd[e])&&$df(e);_$HY.sd&&delete _$HY.sd[e]}}function $dfj(e,i,n){for(i=0;i<e.length;i++)if(_$HY.sc&&_$HY.sc[e[i]]>0){for(n=0;n<e.length;n++)(_$HY.sg=_$HY.sg||{})[e[n]]=e;return}for(i=0;i<e.length;i++)$df(e[i])}`;
+const REPLACE_SCRIPT = `function $df(e,n,o,t){if(!(n=document.getElementById(e)))return 0;if(!(o=document.getElementById("pl-"+e)))return(_$HY.dq=_$HY.dq||{})[e]=1,0;for(;o&&(8!==o.nodeType||o.nodeValue!=="pl-"+e);)t=o.nextSibling,o.remove(),o=t;_$HY.done?o.remove():o.replaceWith(n.content),n.remove(),_$HY.fe(e),$dfd();return 1}function $dfl(e,o,n){if(!(o=document.getElementById("pl-"+e)))return(_$HY.dlq=_$HY.dlq||{})[e]=1,0;if(o._$fl)return 1;for(n=o.nextSibling;n;){if(8===n.nodeType&&n.nodeValue==="pl-"+e){o.parentNode&&o.parentNode.insertBefore(o.content.cloneNode(!0),n),o._$fl=1,$dfd();return 1}n=n.nextSibling}return 0}function $dflj(e,i){for(i=0;i<e.length;i++)$dfl(e[i])}function $dfd(e,i){if(e=_$HY.dq){_$HY.dq=0;for(i in e)$df(i)}if(e=_$HY.dlq){_$HY.dlq=0;for(i in e)$dfl(i)}}function $dfs(e,c,d){(_$HY.sc=_$HY.sc||{})[e]=c,d&&((_$HY.sd=_$HY.sd||{})[e]=1)}function $dfg(e,g,i,k){if(!(g=_$HY.sg&&_$HY.sg[e]))return;for(i=0;i<g.length;i++)if(_$HY.sc&&_$HY.sc[g[i]]>0)return;for(i=0;i<g.length;i++)k=g[i],delete _$HY.sg[k],$df(k)}function $dfc(e){if(--_$HY.sc[e]<=0){delete _$HY.sc[e],_$HY.sg&&_$HY.sg[e]?$dfg(e):!(_$HY.sd&&_$HY.sd[e])&&$df(e);_$HY.sd&&delete _$HY.sd[e]}}function $dfj(e,i,n){for(i=0;i<e.length;i++)if(_$HY.sc&&_$HY.sc[e[i]]>0){for(n=0;n<e.length;n++)(_$HY.sg=_$HY.sg||{})[e[n]]=e;return}for(i=0;i<e.length;i++)$df(e[i])}`;
 
 export function renderToString(code, options = {}) {
   const { renderId = "", nonce, noScripts, manifest } = options;
   let scripts = "";
-  const serializer = createSerializer({
+  const serializer = createHydrationSerializer({
     scopeId: renderId,
     plugins: options.plugins,
     onData(script) {
@@ -289,7 +299,7 @@ export function renderToStream(code, options = {}) {
     completed = true;
     if (firstFlushed) dispose();
   };
-  const serializer = createSerializer({
+  const serializer = createHydrationSerializer({
     scopeId: options.renderId,
     plugins: options.plugins,
     onData: pushTask,