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

package/types/client.d.ts

@@ -1,12 +1,24 @@
 import { JSX } from "./jsx.js";
+import type { RequestEventLocals } from "./server.js";
+// Element/property classification tables consumed by the JSX compiler and
+// custom renderers. Compiler/tooling surface; not for hand-written code.
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const DOMWithState: Record<string, Record<string, 1 | 2>>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const ChildProperties: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const DelegatedEvents: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const DOMElements: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const SVGElements: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const MathMLElements: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const VoidElements: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const RawTextElements: Set<string>;
+/** Compiler/tooling table; not for hand-written code. @internal */
 export const Namespaces: Record<string, string>;
 
 type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
@@ -17,16 +29,30 @@ export function render(
   options?: { owner?: unknown }
 ): () => void;
 /**
+ * Compiler-emitted primitive; not for hand-written code.
  * @param flag
  * - `undefined` — clone the template as-is (uses `cloneNode`).
  * - `1` — use `document.importNode` instead of `cloneNode`.
  * - `2` — the template html is wrapped; the outer tag is stripped at clone time.
+ * @internal
  */
 export function template(html: string, flag?: 1 | 2): () => Element;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function scope<T extends () => any>(fn: T): T;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function effect<T>(fn: (prev?: T) => T, effect: (value: T, prev?: T) => void): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function memo<T>(fn: () => T, equal: boolean): () => T;
+/**
+ * Compiler-emitted primitive; not for hand-written code — import `untrack`
+ * from `solid-js` instead.
+ * @internal
+ */
 export function untrack<T>(fn: () => T): T;
+/**
+ * Compiler-emitted primitive; not for hand-written code.
+ * @internal
+ */
 export function insert<T>(
   parent: MountableElement,
   accessor: (() => T) | T,
@@ -43,20 +69,29 @@ export function insert<T>(
     schedule?: boolean;
   }
 ): JSX.Element;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function createComponent<T>(Comp: (props: T) => JSX.Element, props: T): JSX.Element;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function delegateEvents(eventNames: string[]): void;
+/** Event-delegation plumbing (Portal/custom-root wiring). Integration plumbing. @internal */
 export function registerDelegatedRoot(root: MountableElement): void;
+/** Event-delegation plumbing (Portal/custom-root wiring). Integration plumbing. @internal */
 export function unregisterDelegatedRoot(root: MountableElement): void;
+/** Event-delegation plumbing (Portal/custom-root wiring). Integration plumbing. @internal */
 export function registerDelegatedContainer(
   container: MountableElement,
   owner?: MountableElement
 ): void;
+/** Event-delegation plumbing (Portal/custom-root wiring). Integration plumbing. @internal */
 export function unregisterDelegatedContainer(
   container: MountableElement,
   owner?: MountableElement
 ): void;
+/** Event-delegation plumbing (Portal/custom-root wiring). Integration plumbing. @internal */
 export function getDelegatedRoot(node: MountableElement): MountableElement | undefined;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function spread<T>(node: Element, accessor: T, skipChildren?: Boolean): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function assign(
   node: Element,
   props: any,
@@ -64,7 +99,9 @@ export function assign(
   prevProps?: any,
   skipRef?: Boolean
 ): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function setAttribute(node: Element, name: string, value: string): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
 /**
  * Register a consumer for compiler-emitted element claims. Compiled DOM
@@ -77,11 +114,16 @@ export function setAttributeNS(node: Element, namespace: string, name: string, v
  * cleanup through your own reactive system. Dormant until registered —
  * without a handler the emitted claims are null checks. Returns an
  * unregister function.
+ *
+ * Integration plumbing (routers register the consumer); not meant for
+ * application code.
+ * @internal
  */
 export function registerElementClaim(handler: (element: Element) => void): () => void;
 /**
  * Claim `node` for registered consumers (see `registerElementClaim`).
  * Emitted by the compiler at element creation; idempotent by contract.
+ * @internal
  */
 export function claimElement<T extends Element>(node: T): T;
 /**
@@ -90,29 +132,50 @@ export function claimElement<T extends Element>(node: T): T;
  * compiled output emits, for content that becomes live DOM without compiled
  * creation code (frame streams, adopted SSR ranges). Dormant without a
  * registered consumer.
+ *
+ * Integration plumbing; not meant for application code.
+ * @internal
  */
 export function claimElementTree<T extends Node>(root: T): T;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function setProperty(node: Element, name: string, value: any): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function setStyleProperty(node: Element, name: string, value: any): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function addEvent(
   node: Element,
   name: string,
   handler: EventListener | EventListenerObject | (EventListenerObject & AddEventListenerOptions),
   delegate: boolean
 ): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function style(
   node: Element,
   value: { [k: string]: string },
   prev?: { [k: string]: string }
 ): void;
+/**
+ * Compiler-emitted primitive; not for hand-written code — import `getOwner`
+ * from `solid-js` instead.
+ * @internal
+ */
 export function getOwner(): unknown;
+/**
+ * Compiler-emitted prop-spread helper; not for hand-written code — import
+ * `merge` from `solid-js` instead.
+ * @internal
+ */
 export function mergeProps(...sources: unknown[]): unknown;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function dynamicProperty(props: unknown, key: string): unknown;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function applyRef<T extends Element = Element>(
   r: ((element: NoInfer<T>) => void) | ((element: NoInfer<T>) => void)[],
   element: T
 ): void;
+/** Compiler-emitted primitive; not for hand-written code. @internal */
 export function ref(
   fn: () => ((element: Element) => void) | ((element: Element) => void)[],
   element: Element
@@ -123,18 +186,25 @@ export function hydrate(
   node: MountableElement,
   options?: { renderId?: string; owner?: unknown }
 ): () => void;
+/** Hydration-walk primitive; not for hand-written code. @internal */
 export function getHydrationKey(): string | undefined;
+/** Hydration-walk primitive; not for hand-written code. @internal */
 export function getNextElement(template?: () => Element): Element;
+/** Hydration-walk primitive; not for hand-written code. @internal */
 export function getNextMatch(start: Node, elementName: string): Element;
+/** Hydration-walk primitive; not for hand-written code. @internal */
 export function getNextMarker(start: Node): [Node, Array<Node>];
-/** @deprecated Use `useHead` — removed before `0.50.0` stable. */
-export function useAssets(fn: () => JSX.Element): void;
-/** @deprecated Use `useHead` — removed before `0.50.0` stable. */
-export function getAssets(): string;
 /**
  * A head tag descriptor. Props values may be getters (reactive on the
  * client); `children` is the text body. `key` overrides the built-in dedupe
  * identity (`title` is a hard singleton that `key` cannot fork).
+ *
+ * Getters must be plain reads: they evaluate inside registry-owned
+ * computations here and at flush time on the server, so a getter that
+ * allocates a reactive owner (`createMemo`, a `children()` helper) consumes
+ * a hydration id slot on one side only and desyncs every id allocated after
+ * the `useHead` call. Create such helpers eagerly at component position and
+ * read them from the getter. See docs/head-management-rfc.md.
  */
 export type HeadTag = {
   tag: "title" | "meta" | "link" | "style" | "script" | "base";
@@ -163,13 +233,41 @@ export interface ExclusiveAssetDescriptor<T> {
   get(): T;
   set(value: T): void;
 }
+/**
+ * @internal Ref-counted client asset ownership: acquire adopts or mounts the
+ * asset, the returned release follows the owner (with a grace period for
+ * back-and-forth navigation). Internal machinery, not a public CSS-lifecycle
+ * API — per the head-management RFC (docs/head-management-rfc.md), ambient
+ * bundler-injected CSS is never lifecycle-managed, and the head registry
+ * owns the lifecycle of directly-mounted stylesheets outright. This keeps
+ * its non-head roles (exclusive slots, owner-following DOM ownership).
+ */
 export function acquireAsset(descriptor: AssetDescriptor): () => void;
+/**
+ * Registry entry returned by `warmAsset`. Stylesheet entries carry load
+ * tracking for the client reveal gate (docs/client-css-reveal-gating.md):
+ * `loadPromise` resolves on load OR error (never rejects) — an errored
+ * sheet releases the gate, parity with the server gate.
+ */
+export interface AssetEntry {
+  loadState?: "pending" | "loaded" | "errored";
+  loadPromise?: Promise<void>;
+}
+/**
+ * @internal Warm half of `acquireAsset`: idempotent and refcount-free,
+ * callable from a compute phase so the fetch starts at discovery and
+ * overlaps a transition's data wait. Stylesheets warm as
+ * `rel="preload" as="style"` and are flipped live by `acquireAsset` at
+ * commit — a branch superseded before it commits leaks only an inert
+ * preload, never an applied sheet. Only link-backed descriptors warm;
+ * inline styles and exclusive slots return `undefined`.
+ */
+export function warmAsset(descriptor: AssetDescriptor): AssetEntry | undefined;
 export function HydrationScript(props?: { nonce?: string; eventNames?: string[] }): JSX.Element;
 export function generateHydrationScript(options?: {
   nonce?: string;
   eventNames?: string[];
 }): string;
-export function Assets(props: { children?: JSX.Element }): JSX.Element;
 /**
  * See the server entry's `ResponseStub` — the shape of the mutable response
  * head integrations expose as `event.response` via module augmentation.
@@ -185,10 +283,33 @@ export interface ResponseStub {
    */
   committed?: boolean;
 }
+/**
+ * See the server entry's `RequestEventLocals` — the augmentable type of
+ * `RequestEvent.locals`. Re-exported (not re-declared) so both entries
+ * share ONE interface identity and a single augmentation reaches every
+ * `locals`, whichever entry typed the event.
+ */
+export type { RequestEventLocals } from "./server.js";
 export interface RequestEvent {
   request: Request;
-  locals: Record<string | number | symbol, any>;
+  locals: RequestEventLocals;
 }
+/**
+ * Registered symbol (`Symbol.for("solid.RequestContext")`) naming the global
+ * slot where `provideRequestEvent` parks the AsyncLocalStorage scoping
+ * request events. Integration plumbing — read the event through
+ * `getRequestEvent()` instead.
+ * @internal
+ */
 export declare const RequestContext: unique symbol;
 export function getRequestEvent(): RequestEvent | undefined;
+/**
+ * The cookie codec (the platform-gap primitives — see cookies.d.ts for the
+ * blessed patterns): the real implementation on both entries, never a
+ * stub — a pure value transformer has legitimate browser uses
+ * (`document.cookie`). Tree-shakes away when unused.
+ */
+export { parseCookieHeader, serializeCookie } from "./cookies.js";
+export type { CookieOptions } from "./cookies.js";
+/** Hydration-walk primitive; not for hand-written code. @internal */
 export function runHydrationEvents(): void;

package/types/core.d.ts

@@ -1,4 +1,6 @@
 export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope, NoHydration, Hydration, runInServerComponentScope } from "solid-js";
-export declare const effect: (fn: any, effectFn: any, options: any) => void;
+export declare const effect: (fn: any, effectFn: any, options?: any) => void;
 export declare const memo: (fn: any) => import("solid-js").SourceAccessor<any>;
 export declare const runWithHydrationScope: (id: any, fn: any) => unknown;
+export declare const ssrAsyncValue: (value: any) => import("solid-js").SourceAccessor<any>;
+export declare const waitAsset: (promise: any) => void;

package/types/frames/client.d.ts

@@ -1,7 +1,20 @@
 export { createFrame, createFrameHost, createFrameElement, FRAME_APPLIED_EVENT } from "./frame-client.js";
 export { FRAME_STREAM_HEADER, applyFrameResponse, isFrameStreamResponse, createServerComponentHandler } from "./frame-transport.js";
-export { createJSONDataTable } from "./serializer.js";
 export type { Slot } from "./server.js";
+/**
+ * Client-condition twin of the server face's `asyncArg` (DR-2 value tier):
+ * the identity that types an async value crossing the slot border as its
+ * settled value. Server component modules are authored in universal code and
+ * may resolve under the browser condition at typecheck/bundle time — the
+ * call never runs here (the `"use server"` body executes server-side), but
+ * the symbol must exist.
+ */
+export declare function asyncArg<T>(value: PromiseLike<T> | AsyncIterable<T>): T;
+/**
+ * The app-wide shared frame host (created lazily): one chunk router with
+ * per-response codec data tables.
+ * @experimental
+ */
 export declare function getFrameHost(): any;
 /**
  * Installs the server-component transport policy on the server-function
@@ -18,5 +31,6 @@ export declare function getFrameHost(): any;
  * Call once in the client entry (an explicit call — the package is
  * `sideEffects: false`, so a bare import would be tree-shaken away);
  * call again to rebind to a custom host.
+ * @experimental
  */
 export declare function installServerComponents(host?: any): void;

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

@@ -6,9 +6,17 @@
  * inside the boundary are preserved across server updates — the
  * version is a stale-guard only ("policy A"): newer content morphs in
  * place, and teardown is `dispose()`, never a version bump.
+ *
+ * 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`.
  */
 
-/** One transport chunk of a frame stream, addressed by frame `id`. */
+/**
+ * One transport chunk of a frame stream, addressed by frame `id`.
+ * @experimental
+ */
 export type FrameChunk =
   | { type: "start"; id: string; version: number }
   | { type: "html"; id: string; version: number; html: string }
@@ -48,6 +56,7 @@ export type FrameChunk =
  * Maps a wire chunk onto resident-store record writes. `data` chunks map to
  * no records — they are response-scoped and the host applies them through
  * its data hook.
+ * @experimental
  */
 export function chunkToRecords(chunk: FrameChunk): Record<string, unknown>;
 
@@ -55,13 +64,17 @@ export function chunkToRecords(chunk: FrameChunk): Record<string, unknown>;
  * One store write applied to a frame: `r` maps record keys to values
  * (`chunkToRecords` produces these from wire chunks) and `version` is the
  * stream stamp — an older version than the frame's current one is ignored.
+ * @experimental
  */
 export interface FrameWrite {
   version: number;
   r: Record<string, unknown>;
 }
 
-/** Context passed to a slot callback. */
+/**
+ * Context passed to a slot callback.
+ * @experimental
+ */
 export interface SlotContext {
   /**
    * True only for the hydration-attach invocation of an adopted
@@ -117,9 +130,11 @@ export interface SlotContext {
  * resolved args (primitives literal, `{$ref}` data resolved through the
  * host, `{$frame}` regions as marker-range fragments). Return nodes to fill
  * the range, or `undefined` to claim `ctx.existing` untouched.
+ * @experimental
  */
 export type Slot = (props: Record<string, unknown>, ctx: SlotContext) => Node | Node[] | undefined;
 
+/** @experimental */
 export interface Frame {
   /** Merge a write into the store and flush (morph/reveal/slot sync). */
   apply(write: FrameWrite): void;
@@ -159,6 +174,7 @@ export interface Frame {
  * An id may have several frames (the same server component mounted more
  * than once): chunks fan out to all of them, and a frame registering after
  * delivery is seeded from a sibling's store.
+ * @experimental
  */
 export interface FrameHost {
   register(id: string, frame: Frame): void;
@@ -180,10 +196,14 @@ export interface FrameHost {
  * boundary (nested region frames dispatch too); use it to re-apply
  * client-owned decorations on server-owned markup (router affordance
  * reflection, e.g. `aria-current`) without a MutationObserver.
+ * @experimental
  */
 export const FRAME_APPLIED_EVENT: "frame:applied";
 
-/** Options for `createFrameHost`. */
+/**
+ * Options for `createFrameHost`.
+ * @experimental
+ */
 export interface FrameHostOptions {
   /**
    * Backs `{$ref}` slot args (typically a codec data table's `resolve`).
@@ -201,9 +221,13 @@ export interface FrameHostOptions {
   applyData?(chunk: Extract<FrameChunk, { type: "data" }>): void;
 }
 
+/** @experimental */
 export function createFrameHost(options?: FrameHostOptions): FrameHost;
 
-/** Options for `createFrame` / `createFrameElement`. */
+/**
+ * Options for `createFrame` / `createFrameElement`.
+ * @experimental
+ */
 export interface FrameOptions {
   /** Register with this host under `id`, receiving routed/buffered chunks. */
   host?: FrameHost;
@@ -217,7 +241,7 @@ export interface FrameOptions {
    */
   adopt?: boolean;
   /** Called after each apply flush (tests/telemetry). */
-  onApply?(info: { version: number; reason: "materialize" | "morph" | "reveal" }): void;
+  onApply?(info: { version: number; reason: "materialize" | "morph" | "reveal" | "error" }): void;
   /**
    * Wraps element-claim sweeps (`a[href]`/`form[action]` in materialized
    * server content — and only those) so claim consumers register their
@@ -259,12 +283,17 @@ export interface FrameOptions {
  * so the first apply morphs against it and slots sync immediately (hydration
  * attach), claiming their server-rendered DOM — a document boot needs no
  * chunk.
+ * @experimental
  */
 export function createFrame(boundary: Element, options?: FrameOptions): Frame;
 
-/** The default boundary/region element tag and its id attribute — the DOM
- *  contract the producer emits at t=0 and the consumer creates/adopts. */
+/**
+ * The default boundary/region element tag and its id attribute — the DOM
+ * contract the producer emits at t=0 and the consumer creates/adopts.
+ * @experimental
+ */
 export const FRAME_TAG: "dx-frame";
+/** @experimental */
 export const FRAME_ID_ATTR: "data-fid";
 
 /**
@@ -274,6 +303,7 @@ export const FRAME_ID_ATTR: "data-fid";
  * returned `element` in any position — single, array, or fragment — with no
  * special-casing. One frame per element; lifecycle belongs to the creator via
  * `dispose()` (register it with your owner's cleanup).
+ * @experimental
  */
 export function createFrameElement(options: FrameOptions): {
   readonly element: Element;

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

@@ -1,6 +1,13 @@
+// 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. */
+/**
+ * Addresses a frame stream: the boundary id and this response's version.
+ * @experimental
+ */
 export interface FrameAddress {
   id: string;
   version: number;
@@ -12,13 +19,17 @@ export interface FrameAddress {
  * 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. */
+/**
+ * Options shared by the frame producers.
+ * @experimental
+ */
 export interface FrameStreamOptions {
   /** Boundary address; defaults to `{ id: "", version: 1 }`. */
   frame?: { id?: string; version?: number };
@@ -26,7 +37,10 @@ export interface FrameStreamOptions {
   [key: string]: unknown;
 }
 
-/** A produced frame stream: pipe chunks, or await the collected array. */
+/**
+ * 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;
 }
@@ -37,6 +51,7 @@ export interface FrameStream extends PromiseLike<FrameChunk[]> {
  * 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;
 
@@ -57,6 +72,7 @@ export function renderToFrameStream(code: () => unknown, options?: FrameStreamOp
  *
  * The props a *client* passes never reach the server — server inputs are the
  * function's arguments.
+ * @experimental
  */
 export function renderServerComponent(
   component: (props: Record<string, any>) => unknown,
@@ -70,6 +86,7 @@ export function renderServerComponent(
  * 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>,
@@ -82,6 +99,7 @@ export function createSlotProps(
  * 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,
@@ -103,6 +121,7 @@ export function serverComponentResponse(
  *   provideEvent
  * });
  * ```
+ * @experimental
  */
 export function frameTransformResult(event: unknown, result: unknown): unknown;
 
@@ -115,6 +134,7 @@ export function frameTransformResult(event: unknown, result: unknown): unknown;
  * positions (the one hydration-time exception), wrapped in the same marker
  * dialect the chunk producer emits so the adopting client binds slots and
  * regions onto the server-rendered ranges.
+ * @experimental
  */
 export function createDocumentSlotProps(
   clientProps: Record<string, unknown>,
@@ -128,6 +148,7 @@ export function createDocumentSlotProps(
  * 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,
@@ -143,6 +164,7 @@ export function frameTransformDirectResult<T>(
  * 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,
@@ -167,5 +189,6 @@ export {
  * self-bootstraps the registry. Kept for integrations still installing it
  * document-wide; the client upgrades the registry via
  * `installServerComponents()`.
+ * @experimental
  */
 export const SERVER_COMPONENT_BOOTSTRAP: string;

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

@@ -1,3 +1,7 @@
+// 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 { JSONCodecOptions } from "./serializer.js";
 
@@ -11,13 +15,20 @@ type FlightConsumer = (data: unknown, context: { response: Response }) => 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. */
+/**
+ * Whether a fetch Response carries a frame stream.
+ * @experimental
+ */
 export function isFrameStreamResponse(response: Response): boolean;
 
-/** Options for `applyFrameResponse`. */
+/**
+ * Options for `applyFrameResponse`.
+ * @experimental
+ */
 export interface ApplyFrameResponseOptions {
   /**
    * Remap the producer's root frame id onto a local one — the id your
@@ -57,6 +68,7 @@ export interface ApplyFrameResponseOptions {
  *   await applyFrameResponse(response, host, { as: "story-pane" });
  * }
  * ```
+ * @experimental
  */
 export function applyFrameResponse(
   response: Response,
@@ -64,13 +76,22 @@ export function applyFrameResponse(
   options?: ApplyFrameResponseOptions
 ): Promise<string>;
 
-/** Brands an inline-rendered server component with its function id. */
+/**
+ * Brands an inline-rendered server component with its function id.
+ * @experimental
+ */
 export const SERVER_COMPONENT: unique symbol;
 
-/** The unwrapped server component behind an inline-render wrap. */
+/**
+ * The unwrapped server component behind an inline-render wrap.
+ * @experimental
+ */
 export const SERVER_COMPONENT_SOURCE: unique symbol;
 
-/** The call's wire address (`frameAddress`), for regions to be emitted under. */
+/**
+ * The call's wire address (`frameAddress`), for regions to be emitted under.
+ * @experimental
+ */
 export const SERVER_COMPONENT_ADDRESS: unique symbol;
 
 /**
@@ -81,10 +102,14 @@ export const SERVER_COMPONENT_ADDRESS: unique symbol;
  * 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. */
+/**
+ * The value under `COMPONENT_BINDING` on a transport-resolved binding.
+ * @experimental
+ */
 export interface ComponentBinding<C = unknown> {
   /** The per-function mount component (the equals-gate identity). */
   component: C;
@@ -98,6 +123,7 @@ export interface ComponentBinding<C = unknown> {
  * 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;
 
@@ -108,6 +134,7 @@ export const ServerComponentPlugin: unknown;
  * 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
  */
 export function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
 
@@ -115,10 +142,14 @@ export function setServerComponentBootstrap(resolve: (ctx: unknown) => string):
  * 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`. */
+/**
+ * Options for `createServerComponentHandler`.
+ * @experimental
+ */
 export interface ServerComponentHandlerOptions<C = unknown> {
   host: FrameHost;
   /**
@@ -170,6 +201,7 @@ export interface ServerComponentHandlerOptions<C = unknown> {
  * 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;