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

package/types/frames/frame-container-plugin.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The container tier at the slot border: reactive containers (projections)
+ * cross serialization boundaries as TRACES — an async iterable whose first
+ * yield is a full state snapshot and whose later yields are patch batches —
+ * and materialize back into live local containers. Renderer-agnostic glue;
+ * the reactive core injects both halves. See frame-container-plugin.js.
+ * @experimental
+ */
+/** A container's border serialization: one subscribe() per consumer. */
+export interface ContainerTrace {
+    subscribe(): AsyncIterable<any>;
+    /** Whether the container's root is an array — the consumer's seed shape. */
+    array: boolean;
+}
+/** The eval-face wire literal a trace decodes to before materialization. */
+export interface ContainerTraceMarker {
+    $tr: AsyncIterable<any>;
+    $ta?: number;
+}
+export declare function setContainerTraceResolver(fn: (value: unknown) => ContainerTrace | undefined): void;
+export declare function setContainerTraceMaterializer(fn: (marker: ContainerTraceMarker) => unknown): void;
+/**
+ * Serializer half: install the async-iterable → raw-seroval-stream mint
+ * (serializer-decode.js, which already carries seroval — this module must
+ * stay seroval-free because it also rides the EAGER frames-client graph,
+ * and seroval ships without `sideEffects: false`).
+ *
+ * Why a raw stream and not the iterable itself: seroval decodes an async
+ * iterable as a generator WRAPPER over its internal stream, so every
+ * buffered value is microtasks away — but hydration's claim walk is
+ * SYNCHRONOUS. A trace whose snapshot the document already delivered must
+ * read as ready DURING the walk (every other async source has a sync
+ * hydration answer: promise stamps, serialized records), or the consuming
+ * boundary renders a phantom fallback over settled markup (the chat
+ * welcome/status meter miss). A raw stream decodes as the stream object
+ * itself, whose `.on()` replays the buffer synchronously at subscribe.
+ */
+export declare function setContainerTraceStreamMint(fn: any): void; /** Whether a value is a traced container (server side; WeakMap probe, trap-safe). */
+export declare function isContainerTraced(value: unknown): boolean;
+export declare function envelopeContainerTraces(value: unknown): unknown;
+export declare function isMaterializedContainer(value: unknown): boolean;
+export declare function isContainerTraceMarker(value: unknown): value is ContainerTraceMarker;
+export declare function reviveContainerTraces(value: unknown): unknown;
+declare function parseTrace(value: any, ctx: any): {
+    a: number;
+    i: any;
+};
+/**
+ * Seroval plugin carrying reactive containers across the slot border as
+ * traces. Part of the codec's DEFAULT plugin set (serializer-decode.js), so
+ * every face — the hydration serializer, the frames codec, flight
+ * payloads, the client data tables — carries it with nothing to wire, and
+ * its weight lives in the (lazy) codec graph, never the eager client.
+ *
+ * @type {import("seroval").Plugin<object, { a: number, i: any }>}
+ */
+export declare const ContainerTracePlugin: {
+    tag: string;
+    test(value: any): boolean;
+    parse: {
+        sync(): never;
+        async(value: any, ctx: any): Promise<{
+            a: number;
+            i: any;
+        }>;
+        stream: typeof parseTrace;
+    };
+    serialize(node: any, ctx: any): string;
+    deserialize(node: any, ctx: any): any;
+};
+export {};

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

@@ -1,132 +1,56 @@
-// 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 } from "./frame-client.js";
-
 /**
  * Addresses a frame stream: the boundary id and this response's version.
  * @experimental
  */
 export interface FrameAddress {
-  id: string;
-  version: number;
+    id: string;
+    version: number;
 }
-
-/**
- * The emission surface `renderToStream` routes through when producing a
- * frame stream instead of a document (see the `sink` render option). Each
- * method emits transport-agnostic chunks; `emit` is the envelope boundary.
- * @internal Compiler/renderer wiring — use `renderToFrameStream` or
- * `renderServerComponent` instead.
- * @experimental
- */
-export function createFrameSink(
-  emit: (chunk: FrameChunk) => void,
-  frame: FrameAddress
-): Record<string, (...args: any[]) => void>;
-
 /**
  * Options shared by the frame producers.
  * @experimental
  */
 export interface FrameStreamOptions {
-  /** Boundary address; defaults to `{ id: "", version: 1 }`. */
-  frame?: { id?: string; version?: number };
-  /** Remaining `renderToStream` options (plugins, onError, manifest, ...). */
-  [key: string]: unknown;
+    /** Boundary address; defaults to `{ id: "", version: 1 }`. */
+    frame?: {
+        id?: string;
+        version?: number;
+    };
+    /** Remaining `renderToStream` options (plugins, onError, manifest, ...). */
+    [key: string]: unknown;
 }
-
 /**
  * A produced frame stream: pipe chunks, or await the collected array.
  * @experimental
  */
 export interface FrameStream extends PromiseLike<FrameChunk[]> {
-  pipe(writable: { write(chunk: FrameChunk): void; end?(): void }): void;
+    pipe(writable: {
+        write(chunk: FrameChunk): void;
+        end?(): void;
+    }): void;
 }
-
-/**
- * Render to a FrameChunk stream: the same render core as `renderToStream`
- * with emission swapped to the frame sink and the document writable replaced
- * by a chunk envelope (`start` up front, `complete` at stream end). Data
- * records default to the keyed JSON codec (decode with
- * `createJSONDataTable`).
- * @experimental
- */
-export function renderToFrameStream(code: () => unknown, options?: FrameStreamOptions): FrameStream;
-
+export { SERVER_COMPONENT, SERVER_COMPONENT_SOURCE, SERVER_COMPONENT_ADDRESS, ServerComponentPlugin } from "./frame-transport.js";
 /**
- * Render a **server component** — a `props => JSX` function, typically
- * returned from a server function — to a FrameChunk stream. `props` is a
- * slot-props proxy, not data:
- *
- * - reading a prop as a child emits a marker range the client fills;
- * - calling a prop as a render function emits a `slot` chunk for a fresh
- *   occurrence (a primitive `$key` arg names it, so client state follows the
- *   entity across responses — the slot-level analogue of For's `keyed`
- *   function; positional otherwise, which is the right default for most
- *   flows);
- * - primitive args ride the chunk; server JSX args stream as nested regions
- *   (`{$frame}` — html once, never data); other values serialize as `{$ref}`
- *   data records with referential dedupe.
- *
- * The props a *client* passes never reach the server — server inputs are the
- * function's arguments.
- * @experimental
+ * Statement form of the registry bootstrap, for a document shell that wants
+ * to install `_$SC` ahead of every data script (e.g. a plugin injecting it
+ * into `<head>`). No longer required — serialized references self-bootstrap
+ * — but kept for integrations still emitting it; the idempotent form makes
+ * the double-definition harmless. Never splice it before the authored
+ * `<head>` elements: a head-open script claims as the first walked child at
+ * hydration and drifts every positional claim after it.
  */
-export function renderServerComponent(
-  component: (props: Record<string, any>) => unknown,
-  options?: FrameStreamOptions
-): FrameStream;
-
-/**
- * The slot props proxy used by `renderServerComponent`. Every key
- * virtually exists (`in` is always true — a prop is a position the client
- * may fill), enumeration is empty by design, and serialization goes through
- * the live render context, so it must only be used during the frame's
- * render.
- * @internal Exposed for framework bindings composing their own producers.
- * @experimental
- */
-export function createSlotProps(
-  sink: ReturnType<typeof createFrameSink>,
-  frame: FrameAddress
-): Record<string, any>;
-
-/**
- * A server component as an HTTP Response: the chunk stream framed with the
- * server-function wire convention, tagged `X-Frame-Stream: <frame id>` for
- * the client and `X-Content-Raw` so the server-function handler forwards it
- * untouched. `init` (headers/status, e.g. from a `respond()` envelope)
- * merges in; the frame tags win on conflict.
- * @experimental
- */
-export function serverComponentResponse(
-  component: (props: Record<string, any>) => unknown,
-  options?: FrameStreamOptions,
-  init?: { headers?: HeadersInit; status?: number }
-): Response;
-
-/**
- * The server-component convention as a `transformResult` policy for
- * `handleServerFunctionRequest`: a function result — or a `respond()`
- * envelope whose value is a function — becomes a frame-stream Response,
- * with the frame id defaulting to the server function's id so repeat calls
- * target the same client boundary. Everything else passes through.
- *
- * @example
- * ```ts
- * handleServerFunctionRequest(request, {
- *   transformResult: frameTransformResult,
- *   provideEvent
- * });
- * ```
+export declare const SERVER_COMPONENT_BOOTSTRAP: string; /**
+ * The emission surface `renderToStream` routes through when producing a
+ * frame stream instead of a document (see the `sink` render option). Each
+ * method emits transport-agnostic chunks; `emit` is the envelope boundary.
+ * @internal Compiler/renderer wiring — use `renderToFrameStream` or
+ * `renderServerComponent` instead.
  * @experimental
  */
-export function frameTransformResult(event: unknown, result: unknown): unknown;
-
-// === Document SSR (t = 0) ===
-
+export declare function createFrameSink(emit: (chunk: FrameChunk) => void, frame: FrameAddress): Record<string, (...args: any[]) => void>;
+export declare function renderToFrameStream(code: () => unknown, options?: FrameStreamOptions): FrameStream;
+export declare function renderServerComponent(component: (props: Record<string, any>) => unknown, options?: FrameStreamOptions): FrameStream;
 /**
  * Document-mode slot props — the t = 0 counterpart of
  * `createSlotProps`: the server component renders INLINE in the
@@ -136,59 +60,33 @@ export function frameTransformResult(event: unknown, result: unknown): unknown;
  * regions onto the server-rendered ranges.
  * @experimental
  */
-export function createDocumentSlotProps(
-  clientProps: Record<string, unknown>,
-  frameId: string
-): Record<string, unknown>;
-
+export declare function createDocumentSlotProps(clientProps: Record<string, unknown>, frameId: string): Record<string, unknown>;
+export declare function frameTransformDirectResult<T>(value: T, options: {
+    id: string;
+    args?: unknown[];
+}): T;
+export declare function createSlotProps(sink: ReturnType<typeof createFrameSink>, frame: FrameAddress): Record<string, any>;
+export declare function serverComponentResponse(component: (props: Record<string, any>) => unknown, options?: FrameStreamOptions, init?: {
+    headers?: HeadersInit;
+    status?: number;
+}): Response;
+export declare function frameTransformResult(event: unknown, result: unknown): unknown;
+export declare function frameTransformFlightResult(event: unknown, outcome: {
+    value: unknown;
+    data: unknown;
+}, context?: unknown): Promise<Response | undefined>;
 /**
- * The in-process mirror of `frameTransformResult` for DOCUMENT SSR: install
- * as `configureServerFunctionsServer({ transformDirectResult })` and a
- * direct (same-process) server-function result that is a function comes back
- * as an inline-renderable server component (frame markers + document
- * slot props), branded with its function id and the call's wire address.
- * Non-function results pass through.
- * @experimental
- */
-export function frameTransformDirectResult<T>(
-  value: T,
-  options: { id: string; args?: unknown[] }
-): T;
-
-/**
- * The frame half of single-flight, as a `transformFlightResult` policy for
- * `handleServerFunctionRequest`: when part of what a mutation invalidated is
- * markup (a component-valued flight-data entry), the frame stream carries
- * the whole payload — each component's content as a region addressed by its
- * call, the `{ value, data }` envelope as `outcome` chunks with the
- * component entries serialized as flight references. Returns `undefined`
- * when nothing invalidated is markup (the response stays the plain
- * single-flight envelope).
- * @experimental
- */
-export function frameTransformFlightResult(
-  event: unknown,
-  outcome: { value: unknown; data: unknown },
-  context?: unknown
-): Promise<Response | undefined>;
-
-// The brands and the codec plugin live with the transport (client bundles
-// resolve flight references against the live registry); re-exported here for
-// server integrations importing the document-SSR surface.
-export {
-  SERVER_COMPONENT,
-  SERVER_COMPONENT_ADDRESS,
-  SERVER_COMPONENT_SOURCE,
-  ServerComponentPlugin
-} from "./frame-transport.js";
-
-/**
- * Statement form of the `self._$SC` placeholder-registry bootstrap
- * (idempotent — first definition wins). No longer required in the document
- * shell: each hydration script's first serialized server-component reference
- * self-bootstraps the registry. Kept for integrations still installing it
- * document-wide; the client upgrades the registry via
- * `installServerComponents()`.
- * @experimental
+ * A framed response carrying several frames and a single-flight outcome:
+ * each frame's chunks in order (the host routes and buffers by id), then the
+ * `{ value, data }` envelope as `outcome` chunks.
+ *
+ * Those chunks carry the codec's own nodes, one per chunk, so async values
+ * inside flight data settle progressively exactly as they do in a plain
+ * single-flight body — the consumer replays them into the same decoder.
  */
-export const SERVER_COMPONENT_BOOTSTRAP: string;
+export declare function frameFlightResponse({ primary, regions, outcome, codec }: {
+    primary: any;
+    regions?: any[];
+    outcome: any;
+    codec: any;
+}, init?: {}): Response;