@solidjs/web 2.0.0-beta.28 → 2.0.0-beta.29

package/types-cjs/frames/frame-transport.d.cts

@@ -1,4 +1,11 @@
 import { FrameChunk, FrameHost } from "./frame-client.cjs";
+import { JSONCodecOptions } from "./serializer.cjs";
+
+// 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
@@ -23,9 +30,24 @@ export interface ApplyFrameResponseOptions {
    * 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.
+   * 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);
+  /**
+   * Remap any frame id other than the response's own root onto a local one
+   * — how a consumer resolves the addresses a single-flight response uses
+   * for the regions it refreshed.
    */
-  version?: number;
+  route?(id: string): string;
+  /**
+   * 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;
 }
 
 /**
@@ -48,6 +70,31 @@ export function applyFrameResponse(
   options?: ApplyFrameResponseOptions
 ): Promise<string>;
 
+/** Brands an inline-rendered server component with its function id. */
+export const SERVER_COMPONENT: unique symbol;
+
+/** The unwrapped server component behind an inline-render wrap. */
+export const SERVER_COMPONENT_SOURCE: unique symbol;
+
+/** The call's wire address (`frameAddress`), for regions to be emitted under. */
+export const SERVER_COMPONENT_ADDRESS: unique symbol;
+
+/**
+ * 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.
+ */
+export const ServerComponentPlugin: unknown;
+
+/**
+ * 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.
+ */
+export function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
+
 /** Options for `createServerComponentHandler`. */
 export interface ServerComponentHandlerOptions<C = unknown> {
   host: FrameHost;
@@ -57,12 +104,6 @@ export interface ServerComponentHandlerOptions<C = unknown> {
    * own frame instance under the boundary id (multi-mount fans out).
    */
   component(frameId: string): C;
-  /**
-   * Runs synchronously at each server-function call site (before any
-   * await); its return is the call's ambient identity — e.g. Solid's
-   * `getOwner`. Calls sharing a captured context share one boundary.
-   */
-  capture?(info: { id: string; meta: unknown }): unknown;
   /**
    * A new response is about to stream into a boundary: rotate
    * response-scoped state (codec data tables) here. `version` is the
@@ -83,6 +124,18 @@ export interface ServerComponentHandlerOptions<C = unknown> {
    * 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;
 }
 
 /**
@@ -92,15 +145,26 @@ export interface ServerComponentHandlerOptions<C = unknown> {
  * (Solid's `dynamic`) never remounts across refetches — the response streams
  * into the boundary underneath as the only observable effect.
  *
- * Boundary identity is derived, never declared: contexts captured per call
- * key a WeakMap of boundaries (dying with their call sites); ownerless calls
- * fall back to one boundary per function id.
+ * Boundary identity is derived, never declared: every call keys by its
+ * intrinsic (function, arguments) address — the query cache's per-args rule,
+ * so cached components and boundaries stay one-to-one. Same-args calls
+ * resolve the identical component and morph in place; an args switch swaps
+ * boundaries, re-materialized from the host's retained state.
  */
 export function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
-  capture?(info: { id: string; meta: unknown }): unknown;
   intercept?(info: { id: string; meta: unknown; args: unknown[] }): C | undefined;
   handle(
     response: Response,
     ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
   ): C | undefined;
+  /**
+   * 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 —
+   * they are how a post-load call for the same (function, arguments) finds
+   * its way back to the adopted boundary. `component` must be the exact
+   * reference the integration's cache holds for the call (the per-function
+   * placeholder), or readers' equals-gates fail into remounts.
+   */
+  showing(address: string, functionId: string, component: C): void;
 };

package/types-cjs/frames/server.d.cts

@@ -26,5 +26,5 @@ import type { Element as SolidElement } from "solid-js";
 export type Slot<P = {}> = (props: P & {
     $key?: string | number;
 }) => SolidElement;
-export { renderToFrameStream, renderServerComponent, serverComponentResponse, frameTransformResult, createFrameSink, frameTransformDirectResult, ServerComponentPlugin, SERVER_COMPONENT_BOOTSTRAP } from "./frame-sink.cjs";
+export { renderToFrameStream, renderServerComponent, serverComponentResponse, frameTransformResult, frameTransformFlightResult, createFrameSink, frameTransformDirectResult, ServerComponentPlugin, SERVER_COMPONENT_BOOTSTRAP } from "./frame-sink.cjs";
 export { FRAME_STREAM_HEADER, isFrameStreamResponse } from "./frame-transport.cjs";

package/types-cjs/index.d.cts

@@ -176,3 +176,77 @@ export declare function dynamic<T extends ValidComponent>(source: () => T | Prom
  * @description https://docs.solidjs.com/reference/components/dynamic
  */
 export declare function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;
+/**
+ * Wraps a dynamically imported component so it renders only in the browser.
+ * The server renders `props.fallback` (and nothing else); the client shows
+ * the fallback until the import resolves and the tree has mounted, then
+ * swaps the real component in.
+ *
+ * Unlike `lazy()`, this avoids Suspense entirely and never server-renders
+ * the wrapped component — only the fallback — so the component participates
+ * in no hydration asset manifest and its code is guaranteed to never run on
+ * the server (safe for browser-only libraries touching `window`, DOM
+ * measurement, etc.). The mount gate keeps hydration safe: during hydration
+ * the fallback is rendered exactly as the server did, and the swap happens
+ * only after settle, so there is no mismatch.
+ *
+ * By default the import starts as soon as `clientOnly` is called (module
+ * load); pass `{ lazy: true }` to defer the import to the component's first
+ * render.
+ *
+ * @example
+ * ```tsx
+ * const Chart = clientOnly(() => import("./Chart.jsx"));
+ * // <Chart fallback={<div>Loading chart…</div>} data={data()} />
+ * ```
+ */
+export declare function clientOnly<T extends Component<any>>(fn: () => Promise<{
+    default: T;
+}>, options?: {
+    lazy?: boolean;
+}): Component<ComponentProps<T> & {
+    fallback?: JSX.Element;
+}>;
+/**
+ * Declares the HTTP response status (and optional status text) for the
+ * lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body where the status is decided (a 404
+ * route, an error fallback). Client build: a no-op — the response head was
+ * sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this status." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the write snapshots the previous
+ * `event.response` status at write time and restores it when the owning
+ * scope is disposed — so a boundary that errored, declared a status, and
+ * then recovered retracts its write instead of stomping a status a
+ * surviving part of the tree legitimately set. Once the integration marks
+ * the response head `committed` (head derived/sent), writes and
+ * retractions are no-ops.
+ */
+export declare function httpStatus(_code: number, _text?: string): void;
+/**
+ * Declares an HTTP response header (or with `append`, appends to one) for
+ * the lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body. Client build: a no-op — the response
+ * head was sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this header." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the header's prior value is snapshotted at
+ * write time and restored when the owning scope is disposed (deleted if
+ * there was none) — a boundary that errors or recovers retracts its writes.
+ * Once the integration marks the response head `committed` (head
+ * derived/sent), writes and retractions are no-ops.
+ */
+export declare function httpHeader(_name: string, _value: string, _options?: {
+    append?: boolean;
+}): void;

package/types-cjs/server-functions/client.d.cts

@@ -2,22 +2,29 @@ import { JSONCodecOptions } from "../serializer.cjs";
 import { ServerFunction, ServerFunctionMetadata } from "./shared.cjs";
 
 export {
+  ChunkReader,
   ERROR_HEADER,
   FLASH_COOKIE,
   FUNCTION_HEADER,
   INSTANCE_HEADER,
   SINGLE_FLIGHT_HEADER,
   clearFlashCookie,
+  createChunk,
   decodeErrorHeaderValue,
   decodeResponse,
   decodeResponsePayload,
+  deserializeStream,
   encodeErrorHeaderValue,
+  frameAddress,
+  getFlightDataConsumer,
   getServerFunctionMetadata,
+  getServerFunctionsCodec,
   hasFlashCookie,
   isServerFunction,
   subscribeFlightData,
   withMeta
 } from "./shared.cjs";
+export { REVALIDATE_HEADER } from "../response.cjs";
 export type {
   FlightDataConsumer,
   FlightDataContext,
@@ -174,3 +181,20 @@ export function createServerReference(id: string, name?: string, base?: string):
  * @internal
  */
 export function registerServerReference(): never;
+
+/**
+ * Identity of the currently executing server function call — see the
+ * server entry. Named here so isomorphic code can import the type from
+ * either entry.
+ */
+export interface ServerFunctionInvocation {
+  id: string;
+}
+
+/**
+ * Client no-op mirror of the server entry's accessor: there is never a
+ * server function call in flight on the client, so this always returns
+ * undefined. Present so `"use server"` modules that import it stay
+ * import-stable in client builds before dead-code elimination.
+ */
+export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;

package/types-cjs/server-functions/server.d.cts

@@ -32,8 +32,9 @@ import { ServerFunction } from "./shared.cjs";
 
 /**
  * The request event a server function call runs under: the base
- * `RequestEvent` (request + locals) plus `serverOnly`, set when the call is
- * an in-process SSR invocation whose result never serializes to a client.
+ * `RequestEvent` (request + locals) with `serverOnly` added, set when the
+ * call is an in-process SSR invocation whose result never serializes to a
+ * client.
  */
 export interface ServerFunctionEvent extends RequestEvent {
   serverOnly?: boolean;
@@ -196,13 +197,36 @@ export interface ServerFunctionsServerConfig {
   transformResult?(
     event: ServerFunctionEvent,
     result: unknown,
-    context: { instance: string | null; request: Request; thrown?: boolean }
+    context: {
+      id: string;
+      args: unknown[];
+      instance: string | null;
+      request: Request;
+      thrown?: boolean;
+    }
   ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
+  /**
+   * `transformResult`'s counterpart for the single-flight fold: when a
+   * call's flight payload needs a body only a policy knows how to build
+   * (frames' `frameTransformFlightResult` — an invalidated entry is
+   * markup), this gets first refusal on the `{ value, data }` outcome.
+   * Return a `Response` to carry the outcome (call headers and cookies are
+   * copied onto it), or `undefined` to decline and keep the plain
+   * serialized envelope. A per-request option overrides it.
+   */
+  transformFlightResult?(
+    event: ServerFunctionEvent,
+    outcome: { value: unknown; data: unknown },
+    context: { id: string; args: unknown[]; instance: string | null; request: Request }
+  ): Response | undefined | Promise<Response | undefined>;
   /**
    * The in-process mirror of `transformResult` for direct (same-server)
    * calls during document SSR — e.g. frames' `frameTransformDirectResult`.
    */
-  transformDirectResult?(value: unknown, options: { id: string }): unknown;
+  transformDirectResult?(
+    value: unknown,
+    options: { id: string; args: unknown[]; event: ServerFunctionEvent }
+  ): unknown;
   /**
    * Server-wide response builder for calls made without the client runtime
    * (see `handleNoJS` in `HandleServerFunctionRequestOptions`); a
@@ -333,17 +357,33 @@ export function GET<A extends readonly any[], R>(
   fn: (...args: A) => R
 ): ServerFunction<A, Awaited<R>>;
 
-/** Identity of the currently executing server function. */
-export interface ServerFunctionMeta {
+/** Identity of the currently executing server function call. */
+export interface ServerFunctionInvocation {
   id: string;
 }
 
 /**
- * Reads the calling server function's meta (its id) off the current request
- * event — usable inside a server function body, e.g. to key caches or logs
- * by function. Returns undefined outside a server function call.
+ * Reads the in-flight server function invocation (its id) for the current
+ * request event — usable inside a server function body, e.g. to key caches
+ * or logs by function. Returns undefined outside a server function call.
+ * The state lives in a module-private WeakMap keyed by the per-call request
+ * event (never in `event.locals`, which derived events share with their
+ * outer event). Distinct from `getServerFunctionMetadata(fn)`, which reads
+ * a reference's static declaration metadata; this describes the call
+ * currently executing.
+ */
+export function getServerFunctionInvocation(): ServerFunctionInvocation | undefined;
+
+/**
+ * The event-keyed half of `getServerFunctionInvocation`, for callers handed
+ * an event outside its provideEvent scope (the handler's result transforms
+ * run after the scope has exited). Integration plumbing — application code
+ * reads the ambient accessor instead.
+ * @internal
  */
-export function getServerFunctionMeta(): ServerFunctionMeta | undefined;
+export function getEventServerFunctionInvocation(
+  event: RequestEvent | undefined
+): ServerFunctionInvocation | undefined;
 
 /**
  * Hooks layering framework policy onto `handleServerFunctionRequest`.
@@ -367,16 +407,26 @@ export interface HandleServerFunctionOptions {
    * extension point for response metadata policies (headers, statuses,
    * substituted results). Runs for returned and thrown results alike
    * (`context.thrown` distinguishes); `context.instance` is null for no-JS
-   * calls. Return the result unchanged to pass through, or a
-   * `ResponseEnvelope` (exposed through the core entry) to send HTTP
-   * metadata plus a structured payload. Runs before `collectFlightData`,
-   * so the flight hook sees the transformed outcome — use
-   * `collectFlightData`, not this, to fold data into the response.
+   * calls. The context carries the call's identity — the function `id` and
+   * the parsed `args` the implementation was invoked with — matching the
+   * direct-call mirror (`transformDirectResult`), so a policy keying state
+   * by the call works over either dispatch path. Return the result
+   * unchanged to pass through, or a `ResponseEnvelope` (exposed through
+   * the core entry) to send HTTP metadata plus a structured payload. Runs
+   * before `collectFlightData`, so the flight hook sees the transformed
+   * outcome — use `collectFlightData`, not this, to fold data into the
+   * response.
    */
   transformResult?(
     event: ServerFunctionEvent,
     result: unknown,
-    context: { instance: string | null; request: Request; thrown?: boolean }
+    context: {
+      id: string;
+      args: unknown[];
+      instance: string | null;
+      request: Request;
+      thrown?: boolean;
+    }
   ): unknown | ResponseEnvelope | Promise<unknown | ResponseEnvelope>;
   /**
    * Overrides the configured single-flight hook for this handler — same
@@ -384,6 +434,15 @@ export interface HandleServerFunctionOptions {
    * `CollectFlightDataHook`).
    */
   collectFlightData?: CollectFlightDataHook;
+  /**
+   * Overrides the configured single-flight fold policy for this handler —
+   * same contract as the `transformFlightResult` config option.
+   */
+  transformFlightResult?(
+    event: ServerFunctionEvent,
+    outcome: { value: unknown; data: unknown },
+    context: { id: string; args: unknown[]; instance: string | null; request: Request }
+  ): Response | undefined | Promise<Response | undefined>;
   /**
    * Builds the response for calls made without the client runtime (no
    * instance header — no-JS form posts, direct HTTP). Receives the

package/types-cjs/server-functions/shared.d.cts

@@ -434,3 +434,12 @@ export class ChunkReader {
   constructor(stream: ReadableStream<Uint8Array>);
   next(): Promise<{ done: boolean; value: string | undefined }>;
 }
+
+/**
+ * The intrinsic wire address of a server-component call: the function id,
+ * suffixed with a realm-stable hash of the arguments when there are any.
+ * Both peers derive it independently — the server names flight regions with
+ * it, the client routes them by it — so it must stay deterministic across
+ * realms and releases.
+ */
+export function frameAddress(id: string, args?: readonly unknown[]): string;

package/types-cjs/server-mock.d.cts

@@ -63,7 +63,10 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  * boundaries settle. Good for time-to-first-byte sensitive pages.
  *
  * Returns an object with `pipe`/`pipeTo` for piping to a Node `Writable` or
- * a Web `WritableStream`, plus a `then` for awaiting full completion.
+ * a Web `WritableStream`, a lazy `readable` byte-stream view for
+ * `new Response(stream.readable)`, plus a `then` for awaiting full
+ * completion. `pipe`, `pipeTo`, and `readable` each consume the render —
+ * use exactly one of the three.
  *
  * @example
  * ```tsx
@@ -73,7 +76,7 @@ export declare function renderToStringAsync<T>(fn: () => T, options?: {
  * renderToStream(() => <App />).pipe(res);
  *
  * // Web (Workers / Deno):
- * await renderToStream(() => <App />).pipeTo(stream.writable);
+ * return new Response(renderToStream(() => <App />).readable);
  * ```
  */
 export declare function renderToStream<T>(fn: () => T, options?: {
@@ -102,6 +105,7 @@ export declare function renderToStream<T>(fn: () => T, options?: {
         end: () => void;
     }) => void;
     pipeTo: (writable: WritableStream) => Promise<void>;
+    readonly readable: ReadableStream<Uint8Array>;
 };
 /**
  * Compiler primitive — emitted by JSX-DOM-Expressions for tagged-template

package/types-cjs/server.d.cts

@@ -97,6 +97,17 @@ export function renderToStream<T>(
   then: (fn: (html: string) => void) => void;
   pipe: (writable: { write: (v: string) => void; end: () => void }) => void;
   pipeTo: (writable: WritableStream) => Promise<void>;
+  /**
+   * Lazy `ReadableStream<Uint8Array>` view of the render — hand it straight
+   * to `new Response(stream.readable)`. First access starts the render
+   * piping through an internal `TransformStream` (chunks are UTF-8 encoded
+   * bytes, the same as `pipeTo` writes) and the stream is cached, so
+   * repeated access returns the same instance. Like `pipe`/`pipeTo`, this
+   * consumes the render: use exactly one of the three — mixing distinct
+   * consumers (`readable` after `pipe`/`pipeTo`, or vice versa) throws an
+   * error naming the conflict.
+   */
+  readonly readable: ReadableStream<Uint8Array>;
 };
 
 export function HydrationScript(props: { nonce?: string; eventNames?: string[] }): JSX.Element;
@@ -140,10 +151,37 @@ export function generateHydrationScript(options?: {
  * @internal
  */
 export declare const RequestContext: unique symbol;
+/**
+ * The mutable response head an integration's handler exposes on the request
+ * event as `event.response`: status/statusText/headers it will apply when
+ * sending the response. A scaffold, not a `Response` — application code
+ * (e.g. JSX response components) writes to it during render, and the
+ * handler reads it when the head goes out. Core does not declare the
+ * `response` property on `RequestEvent` itself: integrations that provide
+ * one declare it through module augmentation (as `@solidjs/router` does),
+ * and this type names the shape they agree on. Core's server-function
+ * handler reads its `Set-Cookie` headers when folding single-flight
+ * cookies but never requires it.
+ */
+export interface ResponseStub {
+  status?: number;
+  statusText?: string;
+  headers: Headers;
+  /**
+   * Set by the integration once the response head has been derived/sent
+   * from this stub — status and headers can no longer change. Consumers
+   * that write response metadata during render (e.g. JSX response
+   * components) must treat later status/header writes and cleanup-time
+   * retractions as no-ops.
+   */
+  committed?: boolean;
+}
+
 /**
  * The per-request context available on the server: the incoming `Request`
  * and a `locals` bag integrations and middleware can hang state on.
- * Frameworks typically extend this shape with richer fields.
+ * Frameworks typically extend this shape with richer fields (e.g. a
+ * `response` head — see `ResponseStub`).
  */
 export interface RequestEvent {
   request: Request;