@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.3

package/types/frames/frame-transport.d.ts

@@ -1,222 +1,189 @@
-// EXPERIMENTAL — the frames/server-components surface ships as an
-// experimental preview, excluded from the 2.0 stability guarantee: API
-// shapes and the wire format may change between prereleases (RFC 11).
-// Every export in this module is @experimental.
-import { FrameChunk, FrameHost } from "./frame-client.js";
+import { FrameHost } from "./frame-client.js";
 import { JSONCodecOptions } from "./serializer-decode.js";
-
-// Structural mirror of server-functions/shared.js's FlightDataConsumer:
-// this file may only reference siblings that ship with it when integrations
-// copy the frames declaration set (solid-web's types build), and the
-// server-functions declarations are copied to a different root.
-type FlightConsumer = (data: unknown, context: { response: Response }) => void | Promise<void>;
-
-/**
- * Header tagging a Response as a frame stream; its value is the producing
- * frame's id. Frame-owned wire contract — deliberately not a server-function
- * `BodyFormat` entry, since the body is frame chunks, not a serialized value.
- * @experimental
- */
-export const FRAME_STREAM_HEADER: "X-Frame-Stream";
-
-/**
- * Whether a fetch Response carries a frame stream.
- * @experimental
- */
-export function isFrameStreamResponse(response: Response): boolean;
-
+type FlightConsumer = (data: unknown, context: {
+    response: Response;
+}) => void | Promise<void>;
 /**
  * Options for `applyFrameResponse`.
  * @experimental
  */
 export interface ApplyFrameResponseOptions {
-  /**
-   * Remap the producer's root frame id onto a local one — the id your
-   * insertable/frame registered under — so navigations to the same boundary
-   * reuse the same frame regardless of what the server called it. Boundary
-   * identity belongs to the client.
-   */
-  as?: string;
-  /**
-   * Restamp every chunk of the response with this version (one response IS
-   * one version). Versions belong to the client too: the producer cannot
-   * know how many streams a boundary has consumed, so pass the Nth-response
-   * counter to make policy A's stale-guard real across navigations. A
-   * single-flight response addresses several boundaries, each with its own
-   * history — pass a function and it is called once per frame in the
-   * response.
-   */
-  version?: number | ((frameId: string) => number);
-  /**
-   * Receives the payload text of each `outcome` chunk — the response-scoped
-   * single-flight envelope, the caller's result rather than anything the
-   * host renders.
-   */
-  onOutcome?(payload: string): void;
+    /**
+     * Remap the producer's root frame id onto a local one — the id your
+     * insertable/frame registered under — so navigations to the same boundary
+     * reuse the same frame regardless of what the server called it. Boundary
+     * identity belongs to the client.
+     */
+    as?: string;
+    /**
+     * Restamp every chunk of the response with this version (one response IS
+     * one version). Versions belong to the client too: the producer cannot
+     * know how many streams a boundary has consumed, so pass the Nth-response
+     * counter to make policy A's stale-guard real across navigations. A
+     * single-flight response addresses several boundaries, each with its own
+     * history — pass a function and it is called once per frame in the
+     * response.
+     */
+    version?: number | ((frameId: string) => number);
+    /**
+     * Receives the payload text of each `outcome` chunk — the response-scoped
+     * single-flight envelope, the caller's result rather than anything the
+     * host renders.
+     */
+    onOutcome?(payload: string): void;
 }
-
 /**
- * Reads a frame-stream Response to completion, applying every chunk to
- * `host`. Chunks are length-prefixed JSON over the server-function wire
- * framing. Resolves with the id the chunks were applied under once the
- * stream ends; rejects on a malformed or errored stream.
- *
- * @example
- * ```ts
- * const response = await getStory(id); // frame-tagged server function result
- * if (isFrameStreamResponse(response)) {
- *   await applyFrameResponse(response, host, { as: "story-pane" });
- * }
- * ```
+ * The value under `COMPONENT_BINDING` on a transport-resolved binding.
  * @experimental
  */
-export function applyFrameResponse(
-  response: Response,
-  host: FrameHost,
-  options?: ApplyFrameResponseOptions
-): Promise<string>;
-
+export interface ComponentBinding<C = unknown> {
+    /** The per-function mount component (the equals-gate identity). */
+    component: C;
+    /** The call's intrinsic (function, arguments) address — its store's key. */
+    address: string;
+}
 /**
- * Brands an inline-rendered server component with its function id.
+ * Options for `createServerComponentHandler`.
  * @experimental
  */
-export const SERVER_COMPONENT: unique symbol;
-
+export interface ServerComponentHandlerOptions<C = unknown> {
+    host: FrameHost;
+    /**
+     * Builds the framework's mount component for a server FUNCTION. Invoked
+     * once per function and cached — this is the equals-gate identity every
+     * call of the function resolves through. The component is CALLED (by the
+     * binding wrapper or a gated reader), receiving its current address as a
+     * second argument (`() => string`); it should (re-)bind its frame's pull
+     * to that address's store. Multi-mount fans out per site.
+     */
+    component(fnId: string): C;
+    /**
+     * A new response is about to stream into an address: rotate
+     * response-scoped state (codec data tables) here. `version` is the
+     * client-owned stream counter the chunks will be stamped with.
+     */
+    onStream?(address: string, version: number, response: Response): void;
+    /**
+     * Answer a call SYNCHRONOUSLY before any request is made (t = 0 local
+     * answers — e.g. a boundary the document already carries). Returning a
+     * non-undefined value resolves the call with it; a hydrating consumer
+     * never observes a pending beat.
+     */
+    intercept?(info: {
+        id: string;
+        meta: unknown;
+        args: unknown[];
+    }): C | undefined;
+    /**
+     * Reads the registered single-flight consumer at delivery time. The
+     * consumer is module state in the server-function client's SHARED
+     * instance; pass a getter reading that instance when your bundling gives
+     * this module a private copy. Defaults to the local copy's reader.
+     */
+    consumer?(): FlightConsumer | undefined;
+    /**
+     * Reads the configured codec options at decode time — same instance-
+     * identity contract as `consumer`. Defaults to the local copy's reader.
+     */
+    codec?(): JSONCodecOptions | undefined;
+}
 /**
- * The unwrapped server component behind an inline-render wrap.
- * @experimental
+ * Header tagging a Response as a frame stream; its value is the producing
+ * frame's id. Frame-owned contract (hence the namespace) — deliberately not
+ * a `BodyFormat` entry, since the body is frame chunks, not a serialized
+ * value.
  */
-export const SERVER_COMPONENT_SOURCE: unique symbol;
-
-/**
- * The call's wire address (`frameAddress`), for regions to be emitted under.
+export declare const FRAME_STREAM_HEADER = "X-Frame-Stream"; /**
+ * Whether a fetch Response carries a frame stream.
  * @experimental
  */
-export const SERVER_COMPONENT_ADDRESS: unique symbol;
-
+export declare function isFrameStreamResponse(response: Response): boolean;
+export declare function applyFrameResponse(response: Response, host: FrameHost, options?: ApplyFrameResponseOptions): Promise<string>;
+/** Brands an inline-rendered server component with its function id. */
+export declare const SERVER_COMPONENT: unique symbol;
+/** The unwrapped server component behind an inline-render wrap. */
+export declare const SERVER_COMPONENT_SOURCE: unique symbol;
+/** The call's wire address (`frameAddress`), for regions to be emitted under. */
+export declare const SERVER_COMPONENT_ADDRESS: unique symbol;
 /**
  * The binding brand on values the transport resolves: `{ component, address }`
- * — the identity split (DR-1). `component` is the mount identity, one per
- * server function; `address` names the call's content store. An equals-gated
- * reader compares `component` across resolutions: same function means "same
- * instance, new binding" — keep the mounted instance and deliver the new
- * address into it; a different function swaps normally. `Symbol.for`, so
- * frameworks can honor it without importing this module.
- * @experimental
- */
-export const COMPONENT_BINDING: unique symbol;
-
-/**
- * The value under `COMPONENT_BINDING` on a transport-resolved binding.
- * @experimental
+ * (see `createServerComponentHandler`). The identity split (DR-1,
+ * docs/server-components-principles.md): `component` is the MOUNT identity —
+ * one per server function, stable across every call — while `address` names
+ * the call's content store. An equals-gated reader (a framework's `dynamic`)
+ * compares `component` across resolutions: same function means "same
+ * instance, new binding" — it keeps its mounted instance and delivers the
+ * new address into it (the instance's frame re-binds its pull to that
+ * address's resident store) — and a different function swaps normally.
+ * `Symbol.for`, so consumers honor it without importing this module.
  */
-export interface ComponentBinding<C = unknown> {
-  /** The per-function mount component (the equals-gate identity). */
-  component: C;
-  /** The call's intrinsic (function, arguments) address — its store's key. */
-  address: string;
-}
-
+export declare const COMPONENT_BINDING: unique symbol;
+export declare function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
 /**
- * Seroval plugin for a server component crossing a serialization boundary:
- * a branded component serializes as a REFERENCE — a per-function document
- * placeholder in the hydration serializer, a live-registry lookup by call
- * address in the JSON codec (single-flight envelopes) — its markup never
- * rides as data.
- * @experimental
- */
-export const ServerComponentPlugin: unknown;
-
-/**
- * Installs the hydration-serializer registry prefix: given the emitted
- * script's serializer context, returns the expression the next serialized
- * reference reads the `_$SC` registry through (the self-bootstrapping form
- * on a script's first reference, a bare read after). Loaded document-SSR
- * modules install this (see frame-sink); client bundles never carry the
- * bootstrap text.
- * @experimental
+ * Seroval plugin for a server component crossing a serialization boundary.
+ * A branded component (see `frameTransformDirectResult`) serializes as a
+ * REFERENCE — its markup never rides as data.
+ *
+ * Two distinct consumers share the one tag:
+ *
+ * - `serialize` (eval-style, the document hydration serializer): emits
+ *   `self._$SC.r("<function id>")`. The document shell's inline bootstrap
+ *   memoizes a stable placeholder per FUNCTION — a delegating shell whose
+ *   every mount binds to its own SSR'd element during adoption — so the
+ *   address adds nothing at t=0 and the reference stays id-keyed.
+ * - `deserialize` (the JSON codec): the codec only ever carries a component
+ *   inside a single-flight envelope, so this is a FLIGHT reference. It must
+ *   resolve to the exact object the reading call site already holds — an
+ *   integration seeding its cache with anything else fails the consumer's
+ *   equals-gate and remounts the boundary — so it resolves through the live
+ *   transport registry by the call's address.
  */
-export function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
-
-/**
+declare function parseServerComponent(value: any, ctx: any): {
+    id: any;
+    address: any;
+};
+/** @type {import("seroval").Plugin<Function, { id: any, address: any }>} */
+export declare const ServerComponentPlugin: {
+    tag: string;
+    test(value: any): boolean;
+    parse: {
+        sync: typeof parseServerComponent;
+        async(value: any, ctx: any): Promise<{
+            id: any;
+            address: any;
+        }>;
+        stream: typeof parseServerComponent;
+    };
+    serialize(node: any, ctx: any): string;
+    deserialize(node: any, ctx: any): any;
+}; /**
  * The codec options for a single-flight envelope: `codec` plus
  * `ServerComponentPlugin` (deduped by tag). Injected by the protocol on both
  * legs; exported for integrations composing their own flight carriers.
  * @experimental
  */
-export function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
-
-/**
- * Options for `createServerComponentHandler`.
- * @experimental
- */
-export interface ServerComponentHandlerOptions<C = unknown> {
-  host: FrameHost;
-  /**
-   * Builds the framework's mount component for a server FUNCTION. Invoked
-   * once per function and cached — this is the equals-gate identity every
-   * call of the function resolves through. The component is CALLED (by the
-   * binding wrapper or a gated reader), receiving its current address as a
-   * second argument (`() => string`); it should (re-)bind its frame's pull
-   * to that address's store. Multi-mount fans out per site.
-   */
-  component(fnId: string): C;
-  /**
-   * A new response is about to stream into an address: rotate
-   * response-scoped state (codec data tables) here. `version` is the
-   * client-owned stream counter the chunks will be stamped with.
-   */
-  onStream?(address: string, version: number, response: Response): void;
-  /**
-   * Answer a call SYNCHRONOUSLY before any request is made (t = 0 local
-   * answers — e.g. a boundary the document already carries). Returning a
-   * non-undefined value resolves the call with it; a hydrating consumer
-   * never observes a pending beat.
-   */
-  intercept?(info: { id: string; meta: unknown; args: unknown[] }): C | undefined;
-  /**
-   * Reads the registered single-flight consumer at delivery time. The
-   * consumer is module state in the server-function client's SHARED
-   * instance; pass a getter reading that instance when your bundling gives
-   * this module a private copy. Defaults to the local copy's reader.
-   */
-  consumer?(): FlightConsumer | undefined;
-  /**
-   * Reads the configured codec options at decode time — same instance-
-   * identity contract as `consumer`. Defaults to the local copy's reader.
-   */
-  codec?(): JSONCodecOptions | undefined;
-}
-
-/**
- * The client mirror of `frameTransformResult`, shaped for the server-function
- * client's `responseHandler` seam: frame-stream responses resolve the call
- * with a **binding** — a callable wrapper branded `COMPONENT_BINDING` — so
- * an equals-gated consumer (Solid's `dynamic`) never remounts across
- * refetches or argument changes; the response streams into the address's
- * resident store as the only observable effect.
- *
- * The identity split (DR-1): stores are keyed per-ADDRESS — the call's
- * intrinsic (function, arguments) name, one-to-one with a query cache's
- * per-args entries — while mounts are per-SITE, rendering the per-function
- * component and following delivered addresses. An address nothing is bound
- * to warms its store (preload isolation is the default, not a rule).
- * @experimental
- */
-export function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
-  intercept?(info: { id: string; meta: unknown; args: unknown[] }): unknown;
-  handle(
-    response: Response,
-    ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
-  ): unknown;
-  /**
-   * Declares that the document is showing a call: hydration-data references
-   * carry their call's address (`_$SC.r(id, address)`) but never travel
-   * through the transport, so the integration forwards those records here.
-   * Mints the call's binding (a post-load refetch then resolves a value
-   * whose component matches what the document mounted) and brands the
-   * per-function component so cache-seeded readers deliver instead of
-   * remounting when their site later switches calls.
-   */
-  showing(address: string, functionId: string): void;
+export declare function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
+export declare function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
+    intercept?(info: {
+        id: string;
+        meta: unknown;
+        args: unknown[];
+    }): unknown;
+    handle(response: Response, ctx: {
+        id: string;
+        meta: unknown;
+        args: unknown[];
+        context: unknown;
+    }): unknown;
+    /**
+     * Declares that the document is showing a call: hydration-data references
+     * carry their call's address (`_$SC.r(id, address)`) but never travel
+     * through the transport, so the integration forwards those records here.
+     * Mints the call's binding (a post-load refetch then resolves a value
+     * whose component matches what the document mounted) and brands the
+     * per-function component so cache-seeded readers deliver instead of
+     * remounting when their site later switches calls.
+     */
+    showing(address: string, functionId: string): void;
 };
+export {};

package/types/frames/serializer-decode.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ * Declared by hand like the plugin types below (same rationale): the
+ * observable envelope — a numeric type tag, an optional reference id —
+ * with the rest owned by the codec. Real seroval nodes satisfy it; treat
+ * it as an opaque token.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export interface SerovalNode {
+    /** Node type tag (seroval-internal enum). */
+    t: number;
+    /** Reference id, when the node participates in cross-referencing. */
+    i?: number | undefined;
+    [key: string]: unknown;
+}
+/** 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 (`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 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;
+}
+/**
+ * Options shared by both halves of the JSON codec. All of them must match
+ * 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. */
+    plugins?: SerializerPlugin[];
+    /**
+     * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+     * (payloads may come from an untrusted peer). Must match on both peers.
+     * Outside development, the encoding side additionally strips
+     * `Error.prototype.stack` on top of any override — serialized stacks leak
+     * server paths to the client. Decoding stays permissive, so payloads from
+     * a development peer still round-trip.
+     */
+    disabledFeatures?: number;
+    /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+    depthLimit?: number;
+}
+/**
+ * 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;
+    resolve<T = unknown>(ref: {
+        $ref: string;
+    }): T;
+}
+/**
+ * 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). Plugin objects carry both their serialize
+ * and deserialize halves, so the set lives on the decode side and the
+ * encode module composes over it.
+ */
+export declare const DEFAULT_WEB_PLUGINS: any; /**
+ * 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. Useful when handing a full
+ * plugin list to another serialization layer.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit }?: JSONCodecOptions): {
+    plugins: SerializerPlugin<any, any>[];
+    disabledFeatures: any;
+    depthLimit: number;
+}; /**
+ * 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; feeding later chunks
+ * settles the async values referenced inside it.
+ *
+ * Integration-facing; may change (see the entry banner).
+ */
+export declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;