@solidjs/web 2.0.0-beta.16 → 2.0.0-beta.18

package/dist/web.js

@@ -1,4 +1,4 @@
-import { createRenderEffect, createMemo, sharedConfig, untrack, runWithOwner, flatten, createRoot, merge, createComponent, omit, getOwner, createEffect, enableHydration, flush } from 'solid-js';
+import { createRenderEffect, createMemo, sharedConfig, untrack, runWithOwner, flatten, createRoot, merge, createComponent, omit, createOwner, enableHydration, flush, getOwner, createEffect } from 'solid-js';
 export { Errored, For, Hydration, Loading, Match, NoHydration, Repeat, Reveal, Show, Switch, createComponent, getOwner, untrack } from 'solid-js';
 
 const DOMWithState = {
@@ -503,22 +503,117 @@ function assign(node, props, skipChildren, prevProps = {}, skipRef = false) {
     prevProps[prop] = assignProp(node, prop, props[prop], prevProps[prop], skipRef, nodeName);
   }
 }
+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;
+}
+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;
+}
+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);
+  };
+}
 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(entryUrl).then(mod => {
-        hy.modules[moduleUrl] = mod;
+  for (const key in mapping) {
+    if (hy.modules[key]) continue;
+    const entryUrl = mapping[key];
+    if (!hy.loading[key]) {
+      hy.loading[key] = import(entryUrl).then(mod => {
+        hy.modules[key] = mod;
       }, err => {
-        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;
 }
@@ -805,7 +900,12 @@ function insertExpression(parent, value, current, marker) {
     const tc = typeof current;
     if (tc === "string" || tc === "number") {
       parent.firstChild.data = value;
-    } else parent.textContent = value;
+    } else {
+      if (ownsAllChildren(parent, current)) parent.textContent = value;else {
+        removeOwnedChildren(parent, current);
+        parent.insertBefore(document.createTextNode(value), parent.firstChild);
+      }
+    }
   } else if (value === undefined) {
     cleanChildren(parent, current, marker);
   } else if (value.nodeType) {
@@ -828,7 +928,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 ;
@@ -868,8 +968,34 @@ function appendNodes(parent, array, marker = null) {
     if (marker) n[$$SLOT] = marker;
   }
 }
+function ownsAllChildren(parent, current) {
+  if (current == null) return true;
+  if (Array.isArray(current)) {
+    return current.length ? parent.firstChild === current[0] && parent.lastChild === current[current.length - 1] : parent.firstChild === null;
+  }
+  if (current === "") return parent.firstChild === null;
+  if (current.nodeType) return parent.firstChild === current && parent.lastChild === current;
+  const first = parent.firstChild;
+  return first !== null && first.nodeType === 3 && parent.lastChild === first;
+}
+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 {
+    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) {
+    if (ownsAllChildren(parent, current)) return parent.textContent = "";
+    return removeOwnedChildren(parent, current);
+  }
   if (current.length) {
     let inserted = false;
     for (let i = current.length - 1; i >= 0; i--) {
@@ -940,11 +1066,16 @@ const hydrate = (...args) => {
   return hydrate$1(...args);
 };
 function Portal(props) {
+  return runWithOwner(createOwner(), () => portalImpl(props));
+}
+function portalImpl(props) {
   const treeMarker = document.createTextNode(""),
     startMarker = document.createTextNode(""),
     endMarker = document.createTextNode(""),
     mount = () => props.mount || document.body,
-    content = createMemo(() => [startMarker, props.children]);
+    content = createMemo(() => [startMarker, props.children], {
+      ssrSource: "client"
+    });
   createRenderEffect(
   () => [mount(), content(), getOwner()], ([, c, owner]) => {
     const m = untrack(mount);
@@ -965,8 +1096,10 @@ function Portal(props) {
         c = n;
       }
     };
-  }, {
-    schedule: true
+  },
+  {
+    schedule: true,
+    ssrSource: "client"
   });
   createEffect(mount, () => {
     const m = untrack(mount);
@@ -974,6 +1107,11 @@ function Portal(props) {
     if (!ownerRoot || ownerRoot.contains(m)) return;
     registerDelegatedContainer(m, ownerRoot);
     return () => unregisterDelegatedContainer(m, ownerRoot);
+  }, {
+    ssrSource: "client"
+  });
+  if (sharedConfig.hydrating) return createMemo(() => treeMarker, {
+    ssrSource: "client"
   });
   return treeMarker;
 }
@@ -1005,4 +1143,4 @@ function createElement(tagName, is = undefined) {
   });
 }
 
-export { voidFn as Assets, ChildProperties, DOMElements, DOMWithState, DelegatedEvents, Dynamic, voidFn as HydrationScript, MathMLElements, Namespaces, Portal, RawTextElements, RequestContext, SVGElements, VoidElements, addEvent, applyRef, assign, className, delegateEvents, dynamic, dynamicProperty, effect, escape, voidFn as generateHydrationScript, voidFn as getAssets, getDelegatedRoot, getFirstChild, getHydrationKey, getNextElement, getNextMarker, getNextMatch, getNextSibling, voidFn as getRequestEvent, hydrate, insert, isDev, isServer, memo, mergeProps, ref, registerDelegatedContainer, registerDelegatedRoot, render, renderToStream, renderToString, renderToStringAsync, resolveSSRNode, runHydrationEvents, scope, setAttribute, setAttributeNS, setProperty, setStyleProperty, spread, ssr, ssrAttribute, ssrClassList, ssrElement, ssrHydrationKey, ssrStyle, style, template, unregisterDelegatedContainer, unregisterDelegatedRoot, voidFn as useAssets };
+export { voidFn as Assets, ChildProperties, DOMElements, DOMWithState, DelegatedEvents, Dynamic, voidFn as HydrationScript, MathMLElements, Namespaces, Portal, RawTextElements, RequestContext, SVGElements, VoidElements, acquireAsset, addEvent, applyRef, assign, className, delegateEvents, dynamic, dynamicProperty, effect, escape, voidFn as generateHydrationScript, voidFn as getAssets, getDelegatedRoot, getFirstChild, getHydrationKey, getNextElement, getNextMarker, getNextMatch, getNextSibling, voidFn as getRequestEvent, hydrate, insert, isDev, isServer, memo, mergeProps, ref, registerDelegatedContainer, registerDelegatedRoot, render, renderToStream, renderToString, renderToStringAsync, resolveSSRNode, runHydrationEvents, scope, setAttribute, setAttributeNS, setProperty, setStyleProperty, spread, ssr, ssrAttribute, ssrClassList, ssrElement, ssrHydrationKey, ssrStyle, style, template, unregisterDelegatedContainer, unregisterDelegatedRoot, voidFn as useAssets };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/web",
   "description": "Solid's web runtime: client rendering, hydration, SSR, and DOM-specific control flow (Portal, Dynamic).",
-  "version": "2.0.0-beta.16",
+  "version": "2.0.0-beta.18",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
@@ -27,7 +27,11 @@
     "storage/dist",
     "storage/types",
     "storage/types-cjs",
-    "storage/package.json"
+    "storage/package.json",
+    "serialization/dist",
+    "serialization/types",
+    "serialization/types-cjs",
+    "serialization/package.json"
   ],
   "exports": {
     ".": {
@@ -130,30 +134,41 @@
         "default": "./storage/dist/storage.cjs"
       }
     },
+    "./serialization": {
+      "import": {
+        "types": "./serialization/types/index.d.ts",
+        "default": "./serialization/dist/serialization.js"
+      },
+      "require": {
+        "types": "./serialization/types-cjs/index.d.cts",
+        "default": "./serialization/dist/serialization.cjs"
+      }
+    },
     "./types/*": "./types/*"
   },
   "dependencies": {
-    "seroval": "^1.1.0",
-    "seroval-plugins": "^1.1.0"
+    "seroval": "~1.5.4",
+    "seroval-plugins": "~1.5.4"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0-beta.16"
+    "solid-js": "^2.0.0-beta.18"
   },
   "devDependencies": {
-    "solid-js": "2.0.0-beta.16"
+    "solid-js": "2.0.0-beta.18"
   },
   "scripts": {
     "build": "npm-run-all -nl build:clean types:copy-jsx build:js",
     "build:clean": "rimraf dist/",
     "build:js": "rollup -c",
     "link": "symlink-dir . node_modules/@solidjs/web",
-    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:cjs",
-    "types:clean": "rimraf types/ types-cjs/ storage/types-cjs/",
+    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:copy-serialization types:cjs",
+    "types:clean": "rimraf types/ types-cjs/ storage/types/ storage/types-cjs/ serialization/types/ serialization/types-cjs/",
     "types:copy-jsx": "ncp ../../node_modules/@dom-expressions/runtime/src/jsx.d.ts ./src/jsx.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/jsx-properties.d.ts ./src/jsx-properties.d.ts && dom-expressions-jsx-types --input ./src/jsx.d.ts --element \"SolidElement | Node | ArrayElement\" --import 'import type { Element as SolidElement } from \"solid-js\";'",
     "types:web": "tsc --project ./tsconfig.build.json",
-    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
+    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/serializer.d.ts ./types/serializer.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
     "types:web-storage": "tsc --project ./storage/tsconfig.build.json",
-    "types:cjs": "node ../../scripts/sync-dual-types.mjs ./types ./types-cjs ./storage/types ./storage/types-cjs",
+    "types:copy-serialization": "node -e \"fs.mkdirSync('./serialization/types', { recursive: true }); fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/serializer.d.ts', './serialization/types/index.d.ts');\"",
+    "types:cjs": "node ../../scripts/sync-dual-types.mjs ./types ./types-cjs ./storage/types ./storage/types-cjs ./serialization/types ./serialization/types-cjs",
     "test": "vitest run && vitest run --config vite.config.server.mjs && vitest run --config vite.config.hydrate.mjs",
     "test:server": "vitest run --config vite.config.server.mjs",
     "coverage": "vitest run --coverage",

package/serialization/dist/serialization.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var seroval = require('seroval');
+var web = require('seroval-plugins/web');
+
+const DEFAULT_DISABLED_FEATURES = seroval.Feature.AggregateError | seroval.Feature.BigIntTypedArray;
+const HYDRATION_GLOBAL = "_$HY.r";
+const DEFAULT_WEB_PLUGINS = Object.freeze([web.AbortSignalPlugin,
+web.CustomEventPlugin, web.DOMExceptionPlugin, web.EventPlugin,
+web.FormDataPlugin, web.HeadersPlugin, web.ReadableStreamPlugin, web.RequestPlugin, web.ResponsePlugin, web.URLSearchParamsPlugin, web.URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+function createSerializer(options) {
+  return new seroval.Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures: options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures
+  });
+}
+function createHydrationSerializer({
+  onData,
+  onDone,
+  scopeId,
+  onError,
+  plugins
+}) {
+  return createSerializer({
+    scopeId,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
+    onData,
+    onDone,
+    onError
+  });
+}
+function getLocalHeaderScript(id) {
+  return seroval.getCrossReferenceHeader(id) + ";";
+}
+const JSON_CODEC_DISABLED_FEATURES = seroval.Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+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
+  };
+}
+function serializeJSON(value, {
+  onParse,
+  onDone,
+  onError,
+  ...codecOptions
+}) {
+  return seroval.toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return seroval.fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+
+exports.DEFAULT_WEB_PLUGINS = DEFAULT_WEB_PLUGINS;
+exports.createHydrationSerializer = createHydrationSerializer;
+exports.createJSONDeserializer = createJSONDeserializer;
+exports.createSerializer = createSerializer;
+exports.getLocalHeaderScript = getLocalHeaderScript;
+exports.resolveSerializerPlugins = resolveSerializerPlugins;
+exports.serializeJSON = serializeJSON;

package/serialization/dist/serialization.js

@@ -0,0 +1,75 @@
+import { Feature, Serializer, getCrossReferenceHeader, toCrossJSONStream, fromCrossJSON } from 'seroval';
+import { AbortSignalPlugin, CustomEventPlugin, DOMExceptionPlugin, EventPlugin, FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin } from 'seroval-plugins/web';
+
+const DEFAULT_DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;
+const HYDRATION_GLOBAL = "_$HY.r";
+const DEFAULT_WEB_PLUGINS = Object.freeze([AbortSignalPlugin,
+CustomEventPlugin, DOMExceptionPlugin, EventPlugin,
+FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+function createSerializer(options) {
+  return new Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures: options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures
+  });
+}
+function createHydrationSerializer({
+  onData,
+  onDone,
+  scopeId,
+  onError,
+  plugins
+}) {
+  return createSerializer({
+    scopeId,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
+    onData,
+    onDone,
+    onError
+  });
+}
+function getLocalHeaderScript(id) {
+  return getCrossReferenceHeader(id) + ";";
+}
+const JSON_CODEC_DISABLED_FEATURES = Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+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
+  };
+}
+function serializeJSON(value, {
+  onParse,
+  onDone,
+  onError,
+  ...codecOptions
+}) {
+  return toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+
+export { DEFAULT_WEB_PLUGINS, createHydrationSerializer, createJSONDeserializer, createSerializer, getLocalHeaderScript, resolveSerializerPlugins, serializeJSON };

package/serialization/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@solidjs/web/serialization",
+  "main": "./dist/serialization.cjs",
+  "module": "./dist/serialization.js",
+  "types": "./types/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/serialization.js"
+      },
+      "require": {
+        "types": "./types-cjs/index.d.cts",
+        "default": "./dist/serialization.cjs"
+      }
+    }
+  }
+}

package/serialization/types/index.d.ts

@@ -0,0 +1,97 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+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/serialization/types-cjs/index.d.cts

@@ -0,0 +1,97 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+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;