@solidjs/web 2.0.0-beta.31 → 2.0.0-beta.32

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.31",
+  "version": "2.0.0-beta.32",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
@@ -35,6 +35,7 @@
     "serialization/package.json",
     "server-functions/dist",
     "server-functions/package.json",
+    "server-functions/rich-args/package.json",
     "frames/dist",
     "frames/package.json"
   ],
@@ -151,6 +152,16 @@
     },
     "./server-functions": {
       "worker": {
+        "development": {
+          "import": {
+            "types": "./types/server-functions/server.d.ts",
+            "default": "./server-functions/dist/server.dev.js"
+          },
+          "require": {
+            "types": "./types-cjs/server-functions/server.d.cts",
+            "default": "./server-functions/dist/server.dev.cjs"
+          }
+        },
         "import": {
           "types": "./types/server-functions/server.d.ts",
           "default": "./server-functions/dist/server.js"
@@ -171,6 +182,16 @@
         }
       },
       "deno": {
+        "development": {
+          "import": {
+            "types": "./types/server-functions/server.d.ts",
+            "default": "./server-functions/dist/server.dev.js"
+          },
+          "require": {
+            "types": "./types-cjs/server-functions/server.d.cts",
+            "default": "./server-functions/dist/server.dev.cjs"
+          }
+        },
         "import": {
           "types": "./types/server-functions/server.d.ts",
           "default": "./server-functions/dist/server.js"
@@ -181,6 +202,16 @@
         }
       },
       "node": {
+        "development": {
+          "import": {
+            "types": "./types/server-functions/server.d.ts",
+            "default": "./server-functions/dist/server.dev.js"
+          },
+          "require": {
+            "types": "./types-cjs/server-functions/server.d.cts",
+            "default": "./server-functions/dist/server.dev.cjs"
+          }
+        },
         "import": {
           "types": "./types/server-functions/server.d.ts",
           "default": "./server-functions/dist/server.js"
@@ -200,6 +231,16 @@
       }
     },
     "./server-functions/server": {
+      "development": {
+        "import": {
+          "types": "./types/server-functions/server.d.ts",
+          "default": "./server-functions/dist/server.dev.js"
+        },
+        "require": {
+          "types": "./types-cjs/server-functions/server.d.cts",
+          "default": "./server-functions/dist/server.dev.cjs"
+        }
+      },
       "import": {
         "types": "./types/server-functions/server.d.ts",
         "default": "./server-functions/dist/server.js"
@@ -219,6 +260,16 @@
         "default": "./server-functions/dist/client.cjs"
       }
     },
+    "./server-functions/rich-args": {
+      "import": {
+        "types": "./types/server-functions/rich-args.d.ts",
+        "default": "./server-functions/dist/rich-args.js"
+      },
+      "require": {
+        "types": "./types-cjs/server-functions/rich-args.d.cts",
+        "default": "./server-functions/dist/rich-args.cjs"
+      }
+    },
     "./frames": {
       "worker": {
         "import": {
@@ -316,10 +367,10 @@
     "seroval-plugins": "~1.5.4"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0-beta.31"
+    "solid-js": "^2.0.0-beta.32"
   },
   "devDependencies": {
-    "solid-js": "2.0.0-beta.31"
+    "solid-js": "2.0.0-beta.32"
   },
   "scripts": {
     "build": "npm-run-all -nl build:clean types:copy-jsx build:js",
@@ -334,7 +385,7 @@
     "types:web-storage": "tsc --project ./storage/tsconfig.build.json",
     "types:web-frames": "tsc --project ./frames/tsconfig.build.json",
     "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:copy-server-functions": "node -e \"fs.mkdirSync('./types/server-functions', { recursive: true }); for (const f of ['shared', 'flash', 'client', 'server']) fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/server-functions/' + f + '.d.ts', './types/server-functions/' + f + '.d.ts');\"",
+    "types:copy-server-functions": "node -e \"fs.mkdirSync('./types/server-functions', { recursive: true }); for (const f of ['shared', 'flash', 'client', 'server', 'rich-args']) fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/server-functions/' + f + '.d.ts', './types/server-functions/' + f + '.d.ts');\"",
     "types:copy-frames": "node -e \"fs.mkdirSync('./types/frames', { recursive: true }); for (const f of ['frame-client', 'frame-transport', 'frame-sink', 'serializer']) fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/' + f + '.d.ts', './types/frames/' + f + '.d.ts'); for (const f of ['client', 'server']) fs.writeFileSync('./types/frames/' + f + '.d.ts', fs.readFileSync('./frames/types/' + f + '.d.ts', 'utf8').replaceAll('@dom-expressions/runtime/src/', './'));\"",
     "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",

package/serialization/dist/serialization.cjs

@@ -158,6 +158,14 @@ function createJSONDataTable(options) {
   };
 }
 
+Object.defineProperty(exports, "OpaqueReference", {
+  enumerable: true,
+  get: function () { return seroval.OpaqueReference; }
+});
+Object.defineProperty(exports, "createPlugin", {
+  enumerable: true,
+  get: function () { return seroval.createPlugin; }
+});
 exports.DEFAULT_WEB_PLUGINS = DEFAULT_WEB_PLUGINS;
 exports.createHydrationSerializer = createHydrationSerializer;
 exports.createJSONDataTable = createJSONDataTable;

package/serialization/dist/serialization.js

@@ -1,4 +1,5 @@
 import { Feature, Serializer, getCrossReferenceHeader, toCrossJSONStream, fromCrossJSON } from 'seroval';
+export { OpaqueReference, createPlugin } 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;

package/serialization/types/index.d.ts

@@ -1,23 +1,142 @@
-import { Plugin, Serializer, SerovalNode } from "seroval";
+// Serialization surface (published as `@solidjs/web/serialization`): the
+// runtime's Seroval machinery, exposed for the runtime's own entries and
+// for integrations building transports on the same codec. This is
+// INTEGRATION-FACING plumbing, not application API — it is exempt from the
+// 2.0 stability guarantee and may change between releases. Application and
+// router code should configure `codec` on the server-function entries
+// instead of importing from here.
+import { Serializer, SerovalNode } from "seroval";
 
 /**
  * Seroval's node shape — the intermediate representation `serializeJSON`
  * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export type { SerovalNode };
 
+// ---- Plugin authoring ----
+//
+// Unlike the rest of this entry, plugin authoring is APPLICATION-FACING —
+// it is the supported way to feed the serializers' `plugins` options and
+// the server-function entries' `codec.plugins`. The values re-export
+// seroval's own (`createPlugin`, `OpaqueReference` — see serializer.js);
+// the TYPES are declared here by hand, like everything else in this file,
+// because seroval's published d.ts use extensionless ESM-relative imports
+// that `moduleResolution: "nodenext"` cannot follow — a bare type
+// re-export would silently degrade the whole authoring surface to `any`
+// under skipLibCheck. The declarations mirror seroval ~1.5 exactly; the
+// `~` pin is what makes mirroring safe.
+
+/** Per-plugin bookkeeping seroval hands each plugin callback. */
+export interface PluginData {
+  id: number;
+}
+
+/**
+ * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
+ * by the parse contexts, consumed by `serialize`/`deserialize`.
+ */
+export type PluginInfo = { [key: string]: SerovalNode };
+
+/** Parse context for `parse.sync`: turns child values into nodes. */
+export interface SyncParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+}
+
+/** Parse context for `parse.async`: like sync, but child parses await. */
+export interface AsyncParsePluginContext {
+  parse<T>(current: T): Promise<SerovalNode>;
+}
+
+/**
+ * Parse context for `parse.stream`: sync parsing plus the streaming
+ * lifecycle (pending-state tracking, late node emission, cleanup).
+ */
+export interface StreamParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+  parseWithError<T>(current: T): SerovalNode | undefined;
+  isAlive(): boolean;
+  pushPendingState(): void;
+  popPendingState(): void;
+  onParse(node: SerovalNode): void;
+  onError(error: unknown): void;
+  addCleanup(callback: () => void): void;
+}
+
+/** Serialize context: renders child nodes to JS source. */
+export interface SerializePluginContext {
+  serialize(node: SerovalNode): string;
+}
+
+/** Deserialize context: revives child nodes to runtime values. */
+export interface DeserializePluginContext {
+  deserialize<T>(node: SerovalNode): T;
+}
+
 /**
  * A Seroval plugin usable with the web serializers — teaches the codec how
- * to encode/decode a custom value type. Supply matching plugins on both
- * peers of a transport.
+ * to encode/decode a custom value type (`Value` is the value it matches,
+ * `Info` its parsed payload). Supply matching plugins on both peers of a
+ * transport. Bare `SerializerPlugin` (both parameters defaulted to `any`)
+ * is the list-element type every `plugins` option accepts.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
-export type SerializerPlugin = Plugin<any, any>;
+export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
+  /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
+  tag: string;
+  /** Dependency plugins, resolved ahead of this one. */
+  extends?: SerializerPlugin[];
+  /** Whether `value` is this plugin's to encode. */
+  test(value: unknown): boolean;
+  /** Parsing modes — provide the ones the transports you target use. */
+  parse: {
+    sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
+    async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
+    stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
+  };
+  /** Renders the parsed payload as JS source (script-injection form). */
+  serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
+  /** Revives the parsed payload back into the runtime value. */
+  deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
+}
+
+/**
+ * Builds a `SerializerPlugin` — seroval's `createPlugin`, re-exported so
+ * plugin authors stay on the exact seroval instance/version the runtime
+ * serializes with. Import it from HERE, not from your own `seroval`
+ * dependency: a plugin built against a different copy/version would not
+ * fail the build — it would emit nodes the other peer can't interpret.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export function createPlugin<Value, Info extends PluginInfo>(
+  plugin: SerializerPlugin<Value, Info>
+): SerializerPlugin<Value, Info>;
+
+/**
+ * Seroval's `OpaqueReference`, re-exported from the runtime's own instance
+ * (an `OpaqueReference` from another seroval copy fails the serializer's
+ * instanceof check and serializes as a plain value): wraps a value so it
+ * crosses the wire as its `replacement` (default `undefined`) while
+ * staying readable in-process through `.value`.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export class OpaqueReference<V, R = undefined> {
+  readonly value: V;
+  readonly replacement?: R;
+  constructor(value: V, replacement?: R);
+}
 
 /**
  * Baseline plugin set for serializing web-platform values (AbortSignal,
  * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
  * Applied by every serializer in this module; custom plugins compose ahead
  * of it via `resolveSerializerPlugins`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
 
@@ -26,10 +145,16 @@ export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
  * first so they can shadow a default for values both would match. Returns a
  * fresh array; the defaults are never mutated. Useful when handing a full
  * plugin list to another serialization layer.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
 
-/** Options for `createSerializer`. */
+/**
+ * Options for `createSerializer`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface WebSerializerOptions {
   /** Name of the global object the emitted scripts write resolved values into. */
   globalIdentifier: string;
@@ -58,6 +183,8 @@ export interface WebSerializerOptions {
  * evaluated — the script-injection form of serialization renderers build
  * on. For a JSON-based wire codec (no eval on the receiving side), use
  * `serializeJSON` / `createJSONDeserializer` instead.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createSerializer(options: WebSerializerOptions): Serializer;
 
@@ -96,6 +223,8 @@ export function getLocalHeaderScript(id?: string): string;
  * on the serializing and deserializing peer or payloads will not
  * round-trip — for server functions, set them once through the
  * client/server `codec` config option.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export interface JSONCodecOptions {
   /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
@@ -113,7 +242,11 @@ export interface JSONCodecOptions {
   depthLimit?: number;
 }
 
-/** Options for `serializeJSON`. */
+/**
+ * Options for `serializeJSON`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface JSONSerializeOptions extends JSONCodecOptions {
   /**
    * Receives each serialized node; `initial` is true for the first chunk
@@ -132,6 +265,8 @@ export interface JSONSerializeOptions extends JSONCodecOptions {
  * the deserializing peer needs no script evaluation, so CSP-safe). Wire
  * framing of the nodes is the transport's concern. Returns a cancel
  * function that aborts pending async serialization.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
 
@@ -141,14 +276,46 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * from one stream must go through the same deserializer instance. The first
  * chunk's return value is the decoded source value; feeding later chunks
  * settles the async values referenced inside it.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
 
+/** Options for `createJSONSerializer`. */
+export interface JSONSerializerOptions extends JSONCodecOptions {
+  /**
+   * Receives each keyed record — `initial` is true for a key's first node
+   * (the written value itself); async values patch through later records
+   * under the same key. The decoding peer is `createJSONDataTable`.
+   */
+  onData: (record: { key: string; node: SerovalNode; initial: boolean }) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once `flush()` has been called and every pending value settled. */
+  onDone?: () => void;
+}
+
+/**
+ * The keyed, streaming encoder of the eval-free JSON codec — the render
+ * stream's data serializer (frames default to it). Each `write(key, value)`
+ * shares one reference space, so cross-record identity holds; `flush()`
+ * marks the write set complete (writes after it are dropped, mirroring the
+ * hydration serializer); `close()` aborts pending async serialization.
+ */
+export function createJSONSerializer(options: JSONSerializerOptions): {
+  write(key: string, value: unknown): void;
+  flush(): void;
+  close(): void;
+};
+
 /**
  * A resident, response-scoped decode table over the keyed JSON codec: apply
  * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
  * `resolve`. The frames client host wires one per response
  * (`applyData: c => table.apply(c)`).
+ *
+ * Integration-facing; may change (see the entry banner). This serialization
+ * entry is the single home of the data table — the frames client consumes
+ * it internally rather than re-exporting it.
  */
 export interface JSONDataTable {
   apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;

package/serialization/types-cjs/index.d.cts

@@ -1,23 +1,142 @@
-import { Plugin, Serializer, SerovalNode } from "seroval";
+// Serialization surface (published as `@solidjs/web/serialization`): the
+// runtime's Seroval machinery, exposed for the runtime's own entries and
+// for integrations building transports on the same codec. This is
+// INTEGRATION-FACING plumbing, not application API — it is exempt from the
+// 2.0 stability guarantee and may change between releases. Application and
+// router code should configure `codec` on the server-function entries
+// instead of importing from here.
+import { Serializer, SerovalNode } from "seroval";
 
 /**
  * Seroval's node shape — the intermediate representation `serializeJSON`
  * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export type { SerovalNode };
 
+// ---- Plugin authoring ----
+//
+// Unlike the rest of this entry, plugin authoring is APPLICATION-FACING —
+// it is the supported way to feed the serializers' `plugins` options and
+// the server-function entries' `codec.plugins`. The values re-export
+// seroval's own (`createPlugin`, `OpaqueReference` — see serializer.js);
+// the TYPES are declared here by hand, like everything else in this file,
+// because seroval's published d.ts use extensionless ESM-relative imports
+// that `moduleResolution: "nodenext"` cannot follow — a bare type
+// re-export would silently degrade the whole authoring surface to `any`
+// under skipLibCheck. The declarations mirror seroval ~1.5 exactly; the
+// `~` pin is what makes mirroring safe.
+
+/** Per-plugin bookkeeping seroval hands each plugin callback. */
+export interface PluginData {
+  id: number;
+}
+
+/**
+ * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
+ * by the parse contexts, consumed by `serialize`/`deserialize`.
+ */
+export type PluginInfo = { [key: string]: SerovalNode };
+
+/** Parse context for `parse.sync`: turns child values into nodes. */
+export interface SyncParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+}
+
+/** Parse context for `parse.async`: like sync, but child parses await. */
+export interface AsyncParsePluginContext {
+  parse<T>(current: T): Promise<SerovalNode>;
+}
+
+/**
+ * Parse context for `parse.stream`: sync parsing plus the streaming
+ * lifecycle (pending-state tracking, late node emission, cleanup).
+ */
+export interface StreamParsePluginContext {
+  parse<T>(current: T): SerovalNode;
+  parseWithError<T>(current: T): SerovalNode | undefined;
+  isAlive(): boolean;
+  pushPendingState(): void;
+  popPendingState(): void;
+  onParse(node: SerovalNode): void;
+  onError(error: unknown): void;
+  addCleanup(callback: () => void): void;
+}
+
+/** Serialize context: renders child nodes to JS source. */
+export interface SerializePluginContext {
+  serialize(node: SerovalNode): string;
+}
+
+/** Deserialize context: revives child nodes to runtime values. */
+export interface DeserializePluginContext {
+  deserialize<T>(node: SerovalNode): T;
+}
+
 /**
  * A Seroval plugin usable with the web serializers — teaches the codec how
- * to encode/decode a custom value type. Supply matching plugins on both
- * peers of a transport.
+ * to encode/decode a custom value type (`Value` is the value it matches,
+ * `Info` its parsed payload). Supply matching plugins on both peers of a
+ * transport. Bare `SerializerPlugin` (both parameters defaulted to `any`)
+ * is the list-element type every `plugins` option accepts.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
-export type SerializerPlugin = Plugin<any, any>;
+export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
+  /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
+  tag: string;
+  /** Dependency plugins, resolved ahead of this one. */
+  extends?: SerializerPlugin[];
+  /** Whether `value` is this plugin's to encode. */
+  test(value: unknown): boolean;
+  /** Parsing modes — provide the ones the transports you target use. */
+  parse: {
+    sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
+    async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
+    stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
+  };
+  /** Renders the parsed payload as JS source (script-injection form). */
+  serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
+  /** Revives the parsed payload back into the runtime value. */
+  deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
+}
+
+/**
+ * Builds a `SerializerPlugin` — seroval's `createPlugin`, re-exported so
+ * plugin authors stay on the exact seroval instance/version the runtime
+ * serializes with. Import it from HERE, not from your own `seroval`
+ * dependency: a plugin built against a different copy/version would not
+ * fail the build — it would emit nodes the other peer can't interpret.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export function createPlugin<Value, Info extends PluginInfo>(
+  plugin: SerializerPlugin<Value, Info>
+): SerializerPlugin<Value, Info>;
+
+/**
+ * Seroval's `OpaqueReference`, re-exported from the runtime's own instance
+ * (an `OpaqueReference` from another seroval copy fails the serializer's
+ * instanceof check and serializes as a plain value): wraps a value so it
+ * crosses the wire as its `replacement` (default `undefined`) while
+ * staying readable in-process through `.value`.
+ *
+ * Application-facing (see the plugin-authoring banner above).
+ */
+export class OpaqueReference<V, R = undefined> {
+  readonly value: V;
+  readonly replacement?: R;
+  constructor(value: V, replacement?: R);
+}
 
 /**
  * Baseline plugin set for serializing web-platform values (AbortSignal,
  * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
  * Applied by every serializer in this module; custom plugins compose ahead
  * of it via `resolveSerializerPlugins`.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
 
@@ -26,10 +145,16 @@ export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
  * first so they can shadow a default for values both would match. Returns a
  * fresh array; the defaults are never mutated. Useful when handing a full
  * plugin list to another serialization layer.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
 
-/** Options for `createSerializer`. */
+/**
+ * Options for `createSerializer`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface WebSerializerOptions {
   /** Name of the global object the emitted scripts write resolved values into. */
   globalIdentifier: string;
@@ -58,6 +183,8 @@ export interface WebSerializerOptions {
  * evaluated — the script-injection form of serialization renderers build
  * on. For a JSON-based wire codec (no eval on the receiving side), use
  * `serializeJSON` / `createJSONDeserializer` instead.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createSerializer(options: WebSerializerOptions): Serializer;
 
@@ -96,6 +223,8 @@ export function getLocalHeaderScript(id?: string): string;
  * on the serializing and deserializing peer or payloads will not
  * round-trip — for server functions, set them once through the
  * client/server `codec` config option.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export interface JSONCodecOptions {
   /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
@@ -113,7 +242,11 @@ export interface JSONCodecOptions {
   depthLimit?: number;
 }
 
-/** Options for `serializeJSON`. */
+/**
+ * Options for `serializeJSON`.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
 export interface JSONSerializeOptions extends JSONCodecOptions {
   /**
    * Receives each serialized node; `initial` is true for the first chunk
@@ -132,6 +265,8 @@ export interface JSONSerializeOptions extends JSONCodecOptions {
  * the deserializing peer needs no script evaluation, so CSP-safe). Wire
  * framing of the nodes is the transport's concern. Returns a cancel
  * function that aborts pending async serialization.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
 
@@ -141,14 +276,46 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * from one stream must go through the same deserializer instance. The first
  * chunk's return value is the decoded source value; feeding later chunks
  * settles the async values referenced inside it.
+ *
+ * Integration-facing; may change (see the entry banner).
  */
 export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
 
+/** Options for `createJSONSerializer`. */
+export interface JSONSerializerOptions extends JSONCodecOptions {
+  /**
+   * Receives each keyed record — `initial` is true for a key's first node
+   * (the written value itself); async values patch through later records
+   * under the same key. The decoding peer is `createJSONDataTable`.
+   */
+  onData: (record: { key: string; node: SerovalNode; initial: boolean }) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once `flush()` has been called and every pending value settled. */
+  onDone?: () => void;
+}
+
+/**
+ * The keyed, streaming encoder of the eval-free JSON codec — the render
+ * stream's data serializer (frames default to it). Each `write(key, value)`
+ * shares one reference space, so cross-record identity holds; `flush()`
+ * marks the write set complete (writes after it are dropped, mirroring the
+ * hydration serializer); `close()` aborts pending async serialization.
+ */
+export function createJSONSerializer(options: JSONSerializerOptions): {
+  write(key: string, value: unknown): void;
+  flush(): void;
+  close(): void;
+};
+
 /**
  * A resident, response-scoped decode table over the keyed JSON codec: apply
  * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
  * `resolve`. The frames client host wires one per response
  * (`applyData: c => table.apply(c)`).
+ *
+ * Integration-facing; may change (see the entry banner). This serialization
+ * entry is the single home of the data table — the frames client consumes
+ * it internally rather than re-exporting it.
  */
 export interface JSONDataTable {
   apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;