octane 0.2.11 → 0.2.13

package/dist/runtime.server.d.ts

@@ -1,30 +1,19 @@
-/**
- * octane server runtime (SSR).
- *
- * The `octane/compiler` compiler, in `mode: 'server'`, emits component bodies
- * that build an HTML STRING (instead of cloning a DOM template) by calling the
- * `ssr*` helpers here, and that call these server hook implementations. The
- * server analogues of `createRoot().render()` are `renderToString` /
- * `renderToStaticMarkup` (`octane/server`) and `prerender` (`octane/static`),
- * each returning `{ html, css }` (hoisted head folded into `html`).
- *
- * Scope: static markup, dynamic text holes, attributes (incl. class / style /
- * spread), control flow (@if/@for/@switch/@try), nested components, scoped CSS
- * collection, Suspense, and the leaf hooks (state renders its initial value —
- * re-invoking the body for render-phase dispatches until it settles, as React's
- * server renderer does — effects no-op, memo runs once, ids are deterministic).
- * Every dynamic site is
- * wrapped in the hydration markers (`constants.ts`) the client `hydrateRoot`
- * cursor adopts. Events and refs are dropped (no DOM on the server); Fragment
- * refs retain their range markers only when producing hydratable output.
- */
+export { trustHTML, type TrustedHTML } from './trusted-html.js';
+export { readNativeDomStyle, readNativeDomProps } from './signals/read-protocol.js';
 import { EXTERNAL_HYDRATION_PROMISE, HYDRATION_RANGE_BOUNDARY } from './constants.js';
+import { type IndependentHydrateBuildRecord } from './independent-hydration-protocol.js';
 import { normalizeClass } from './css.js';
 import { validateNativeReadWitness, type NativeReadWitness } from './signals/native-read-collector.js';
 import { type NativeSignalManifest } from './signals/native-read-seeds.js';
+import { type ServerSignalQueryAttempt, type ServerSignalQueryAttemptObservations } from './signals/query-attempt-observer.js';
+import { type SignalOwner, type SignalRendererOwnerIdentity } from './signals/types.js';
 export { EXTERNAL_HYDRATION_PROMISE, HYDRATION_RANGE_BOUNDARY, normalizeClass };
 export { validateNativeReadWitness };
 export type { NativeSignalManifest };
+/** @internal Compiler target for strict server reads of a direct signal binding. */
+export declare function ssrSignalValue(value: unknown): unknown;
+/** @internal Preserve a writable control's identity until the final JSX winner is known. */
+export declare function ssrSignalControlValue(value: unknown, site: string): unknown;
 /** Server twin of the compiler's guarded native-array map ABI. */
 export declare function mapSlot(receiver: any, method: any, callback?: (...args: any[]) => any): any;
 interface SSRScope {
@@ -56,6 +45,7 @@ export declare function beginNativeReadWitness(detached?: boolean): number;
 export declare function finishNativeReadWitness(token: number, completed: boolean): NativeReadWitness | null;
 /** @internal Shared automatic-cache witness ABI. */
 export declare function replayNativeReadWitness(witness: NativeReadWitness | null | undefined): void;
+type ServerSignalInstanceKey = string | Frame;
 interface InjectedStyle {
     css: string;
     nonce?: string;
@@ -71,6 +61,11 @@ interface Frame {
     asyncScope: string;
     /** Parser context supplied by, or inherited through, the component call site. */
     namespace: 'html' | 'svg' | 'mathml' | undefined;
+    signalParentKey?: ServerSignalInstanceKey;
+    signalInvocationSite?: string;
+    signalListKeys?: readonly string[];
+    signalKey?: string;
+    signalInstanceKey?: string;
 }
 type ScopedCounts = (string | number)[] | Map<string, number>;
 /** Compiler ABI: validate and scope one native element during a DEV SSR render. */
@@ -102,16 +97,22 @@ interface ElementDescriptor {
     key: any;
     ref: any;
     children: any;
+    /** @internal Compiler-stable component invocation identity. */
+    __octaneInvocationSite?: string;
 }
 /** Server twin of the compiler-only complete JSX-record deferral helper. */
 export declare function createScopedValue(readElement: () => ElementDescriptor): ElementDescriptor;
 /** @internal Native complete-record deferral with request-local evidence. */
 export declare function nativeCreateScopedValue(readElement: () => ElementDescriptor): ElementDescriptor;
 /** Server twin of the compiler-only scope-preserving JSX descriptor factory. */
-export declare function createScopedElement(type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props: any, readChildren: () => unknown): ElementDescriptor;
+export declare function createScopedElement(type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props: any, readChildren: () => unknown, invocationSite?: string): ElementDescriptor;
 /** @internal Native child deferral with evidence on every resolving scope. */
-export declare function nativeCreateScopedElement(type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props: any, readChildren: () => unknown): ElementDescriptor;
+export declare function nativeCreateScopedElement(type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props: any, readChildren: () => unknown, invocationSite?: string): ElementDescriptor;
 export declare function createElement(type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props?: any, ...children: any[]): ElementDescriptor;
+/** @internal Compiler-authored element descriptor with stable invocation identity. */
+export declare function createElementAt(invocationSite: string, type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props?: any, ...children: any[]): ElementDescriptor;
+/** @internal Compiler-owned positional children; omitted children allocate no rest array. */
+export declare function createElementFromConfig(invocationSite: string | undefined, type: ServerEntryComponent | string | typeof Fragment | typeof Activity, props: any, children?: any[]): ElementDescriptor;
 export declare function positionalChildren(children: unknown[]): unknown[];
 /** True if `v` is an element descriptor from `createElement` / JSX-at-value. */
 export declare function isValidElement(v: unknown): v is ElementDescriptor;
@@ -134,6 +135,10 @@ export declare const Children: {
 export declare function createPortal(body: unknown, target: unknown, props?: any): unknown;
 /** @internal Brand the final serialized output of a compiled server body. */
 export declare function ssrHtml(html: string): string;
+/** @internal Preserve the existing component range while identifying an authored binding view. */
+export declare function ssrBindingHtml(html: string, id: string): string;
+/** @internal Match the client definition-site boundary capability. */
+export declare function bindPresentationView<T extends Function>(view: T, _id: string): T;
 export declare function escapeHtml(v: unknown): string;
 export declare function escapeAttr(v: unknown): string;
 /** A dynamic text hole. null/false/undefined render as empty (React parity). */
@@ -154,6 +159,8 @@ export declare function ssrTextPre(v: unknown): string;
  * `{x as string}` / literals / `+`-concats to `ssrText`, everything else here.
  */
 export declare function ssrChild(v: unknown, scope: SSRScope): string;
+/** @internal Give an authored child slot an identity without adding a second hydration range. */
+export declare function ssrBindingChild(value: unknown, scope: SSRScope, marker: string): string;
 export declare function ssrChildText(v: unknown, scope: SSRScope): string;
 /** @internal First-child renderable hole in a newline-eating HTML element. */
 export declare function ssrChildTextPre(v: unknown, scope: SSRScope): string;
@@ -166,6 +173,12 @@ export declare function ssrChildPre(v: unknown, scope: SSRScope): string;
  * protocol (shared constants in ./constants).
  */
 export declare function ssrBlock(content: string): string;
+/** @internal Opt-in identity payload on an otherwise ordinary hydration range. */
+export declare function ssrBindingBlock(content: string, marker: string): string;
+/** @internal Authenticate keyed item identity before emitting any item HTML. */
+export declare function ssrBindingKey(key: unknown, seen: Set<string>): string;
+/** @internal One evaluation supplies both presentation classes and their adoption receipt. */
+export declare function ssrBindingClass(receipt: string, values: [unknown, unknown[]]): string;
 /**
  * Preserve a Fragment ref's authored evaluation order without attaching its
  * value. Hydratable output needs the exact comments its client template adopts;
@@ -200,7 +213,7 @@ export declare function ssrControl<T>(siteKey: string, fn: () => T): T;
 /** Compiler-emitted identity membrane for one arm/item inside ssrControl. */
 export declare function ssrArm<T>(armKey: unknown, fn: () => T): T;
 /** Invoke a compiled list body without allocating a callback per item. */
-export declare function ssrForItem(armKey: unknown, fn: (...args: any[]) => string, item: unknown, index: number | undefined, scope: SSRScope, block: boolean): string;
+export declare function ssrForItem(armKey: unknown, fn: (...args: any[]) => string, item: unknown, index: number | undefined, scope: SSRScope, block: boolean, mapped?: boolean): string;
 /**
  * A portal's site marker. The portal body renders into a foreign target at the
  * client, so server-side it leaves a single anchor comment placeholder.
@@ -235,7 +248,7 @@ type SsrAttributeSource = readonly [
  * class identity after that last-writer fold, matching the client so a spread
  * `class` is not replaced by the hash alone.
  */
-export declare function ssrAttrs(sources: readonly SsrAttributeSource[], tag?: string, namespace?: AttributeNamespace, skipFormControls?: boolean): string;
+export declare function ssrAttrs(sources: readonly SsrAttributeSource[], tag?: string, namespace?: AttributeNamespace, skipFormControls?: boolean, readStyle?: (value: unknown) => unknown): string;
 /**
  * Resolve direct and spread class writers to one native `class` attribute.
  * `sources` are `[isSpread, value]` pairs in authoring order. A spread only
@@ -248,7 +261,7 @@ export declare function ssrClass(sources: Array<[boolean, unknown]>): string;
  * string keys participate, and getters run once at the spread's authored
  * evaluation position before later direct prop expressions.
  */
-export declare function ssrSnapshotSpread(obj: unknown): Record<string, unknown> | null;
+export declare function ssrSnapshotSpread(obj: unknown, controlSite?: string, deferStyle?: boolean): Record<string, unknown> | null;
 /** A spread `{...obj}`: serialize attr-like keys; drop events/refs/key/children. */
 export declare function ssrSpread(obj: unknown, tag?: string, skipClass?: boolean, namespace?: AttributeNamespace, skipFormControls?: boolean): string;
 export declare function ssrInnerHtml(sources: readonly (readonly [boolean, unknown])[], renderChildren?: () => string, definitelyHasChildren?: boolean, childrenSources?: readonly (readonly [boolean, unknown])[]): string | undefined;
@@ -293,6 +306,8 @@ export declare function ssrCheckedAttr(v: unknown): string;
  */
 export declare function ssrInputAttrs(sources: Array<readonly [isSpread: boolean, sourceOrName: unknown, value?: unknown]>): string;
 type SsrFormControlSource = readonly [isSpread: boolean, sourceOrName: unknown, value?: unknown];
+/** @internal Join the final writable control winners to the baked control-site key. */
+export declare function ssrSignalControlAttrs(sources: readonly SsrFormControlSource[]): string;
 /**
  * Controlled `<textarea>` content: escaped text + the leading-newline guard
  * (the parser eats a '\n' right after the opening tag — see ssrTextPre).
@@ -340,9 +355,9 @@ export declare function nativeLocalHook<T>(name: string, initialize: () => T, di
  * parent's own range bounds it; the client borrows that range). Applies to
  * both the component branch (frame wrap) and the string-tag branch (ssrBlock).
  */
-export declare function ssrComponent(parent: SSRScope, comp: ServerComponent | string | typeof Activity, props: any, inherit?: boolean, key?: unknown, identityScoped?: boolean): string;
+export declare function ssrComponent(parent: SSRScope, comp: ServerComponent | string | typeof Activity, props: any, inherit?: boolean, key?: unknown, identityScoped?: boolean, invocationSite?: string, bindingMarker?: string): string;
 /** Compiler ABI for a component call whose output is parsed in foreign content. */
-export declare function ssrComponentNS(parent: SSRScope, comp: ServerComponent | string | typeof Activity, props: any, namespace: 'html' | 'svg' | 'mathml', inherit?: boolean, key?: unknown): string;
+export declare function ssrComponentNS(parent: SSRScope, comp: ServerComponent | string | typeof Activity, props: any, namespace: 'html' | 'svg' | 'mathml', inherit?: boolean, key?: unknown, invocationSite?: string, bindingMarker?: string): string;
 /** Run a renderable hole under a lexically proven parser namespace. */
 export declare function ssrInNamespace(namespace: 'html' | 'svg' | 'mathml', render: () => string): string;
 export declare const Hydrate: ServerComponent;
@@ -364,11 +379,16 @@ export declare const Suspense: (props: {
 type VtSsrClassValue = string | Record<string, string>;
 interface VtSsrProps {
     name?: string;
+    scope?: 'element';
     enter?: VtSsrClassValue;
     exit?: VtSsrClassValue;
     update?: VtSsrClassValue;
     share?: VtSsrClassValue;
     default?: VtSsrClassValue;
+    parentEnter?: VtSsrClassValue;
+    parentExit?: VtSsrClassValue;
+    onParentEnter?: unknown;
+    onParentExit?: unknown;
     children?: unknown;
 }
 /**
@@ -643,6 +663,24 @@ export interface RenderResult {
 }
 /** Options accepted by the buffered render entry points (React-shaped subset). */
 export interface RenderOptions {
+    /** The host already emitted earlySignalBootstrapScript before interactive HTML. */
+    earlySignalBootstrap?: 'external';
+    /** Shared request/account data owner borrowed across sibling SSR regions. */
+    signalOwner?: SignalOwner;
+    /** Automatically publish query attempts into the pre-module streamed receiver. */
+    streamedSignals?: {
+        readonly buildId: string;
+        readonly documentId: string;
+        readonly selectionGeneration?: number;
+        readonly maxFrameBytes?: number;
+        readonly maxTotalBytes?: number;
+        readonly timeoutMs?: number;
+    };
+    /** Compiler/bundler records for strict independently activated Hydrate boundaries. */
+    independentHydration?: {
+        readonly buildId: string;
+        readonly resolve: (templateBoundaryId: string) => IndependentHydrateBuildRecord | undefined;
+    };
     /** Caller-controlled namespace for `useId`; use distinct prefixes for sibling roots. */
     identifierPrefix?: string;
     /** Called with any error thrown during the render (before it propagates). */
@@ -693,6 +731,8 @@ type SuspenseOutcome = SuspenseResult & {
     thenable: PromiseLike<unknown>;
 };
 type ResolvedMap = Map<string, SuspenseOutcome> & {
+    /** Pending streaming subscriptions shared across this request's settle waves. */
+    streamSettlements?: StreamSettlements;
     /** Recoverable buffered-boundary errors are reported once across async retries. */
     bufferedErrors?: Map<string, {
         error: unknown;
@@ -702,6 +742,11 @@ type ResolvedMap = Map<string, SuspenseOutcome> & {
     resourceOptions?: RenderOptions | null;
     /** Optional renderer resources; allocated only by a participating adapter. */
     resources?: ServerRenderResources;
+    /** One request/account owner shared by every pass and streamed region. */
+    signalOwner?: SignalOwner;
+    ownedSignalOwner?: boolean;
+    signalInstances?: Map<string, SignalRendererOwnerIdentity>;
+    hasSignalControls?: boolean;
     /** Render-local stable ids for non-primitive and long string control/list keys. */
     asyncIdentities: Map<unknown, number>;
     /** Cross-pass fallback ids for transient object keys at one lexical position. */
@@ -732,6 +777,8 @@ type ResolvedMap = Map<string, SuspenseOutcome> & {
         touched?: Set<PromiseLike<unknown>>;
     };
 };
+/** @internal Compiler/runtime server signal capability version 1. */
+export declare function enableServerSignalBindings(abi?: number, potentialOnly?: boolean): void;
 /** @internal Request lifetime for an optional renderer's asynchronous server work. */
 export interface ServerRenderResourceContext {
     readonly signal: AbortSignal | undefined;
@@ -750,6 +797,20 @@ interface ServerRenderResources extends ServerRenderResourceContext {
  * or cancellation; return null so its adapter can reject before starting work.
  */
 export declare function getServerRenderResourceContext(): ServerRenderResourceContext | null;
+interface StreamSettlementRecorder {
+    promise: PromiseLike<unknown>;
+    key: string;
+    /** Batch registrations get a fresh synthetic key on every pass. */
+    keys: Set<string> | null;
+    batch: boolean;
+    wave: number;
+}
+interface StreamSettlements {
+    resolved: ResolvedMap | null;
+    pending: Map<PromiseLike<unknown>, StreamSettlementRecorder>;
+    wave: number;
+    wake: (() => void) | null;
+}
 /**
  * React `react-dom/static` `prerender` — await ALL data (Suspense boundaries
  * resolve to their success arm), then return the complete `{ html, css }`. Use
@@ -852,11 +913,27 @@ export declare function ssrTry(scope: SSRScope, siteKey: string, tryFn: (arg: un
  * construction.
  */
 export interface StreamInjectionSource {
+    /** @internal Pending query authority must precede shell-time module execution. */
+    takeInitialSelections?(): string;
+    /** This source emits validated renderer frames and needs the pre-module mailbox. */
+    readonly streamedRenderer?: true;
+    /** @internal Automatic query-attempt sink installed by streamedSignals. */
+    readonly observeSignalAttempt?: (attempt: ServerSignalQueryAttempt, run: <T>(callback: () => T) => T) => void;
+    /** @internal Server-only mirrors paired with the automatic attempt sink. */
+    readonly createSignalAttemptObservations?: () => ServerSignalQueryAttemptObservations;
     /**
      * Pull all queued HTML (concatenated, verbatim). Called at emission
      * boundaries and after `subscribe` notifications; return '' when empty.
      */
     take(): string;
+    /**
+     * Optional transport acknowledgement for demand-driven producers. Called
+     * after the string returned by take() has been accepted by the renderer's
+     * sink. A producer may defer its next iterator pull until this callback.
+     */
+    accepted?(): void;
+    /** Release this response's producer when rendering fails or its request is canceled. */
+    cancel?(reason: unknown): void;
     /**
      * The source notifies when new HTML is queued; the renderer then drains
      * promptly — even while the render itself is idle awaiting `done`.
@@ -881,6 +958,12 @@ export interface StreamInjectionSource {
 }
 export interface StreamOptions extends RenderOptions {
     onShellReady?: () => void;
+    /**
+     * The initial shell uses signals requiring activation before document EOF.
+     * Called before shell publication, after its query authority is serialized.
+     * Feature-free renders do not call this hook.
+     */
+    onEarlyHydrationReady?: () => void;
     onShellError?: (err: unknown) => void;
     onAllReady?: () => void;
     /**