@reckona/mreact-server 0.0.160 → 0.0.162

package/src/buffer-sink.ts

@@ -30,6 +30,7 @@ interface BufferConstructor {
 
 declare const Buffer: BufferConstructor;
 
+/** Accumulates server-rendered chunks into a Node Buffer. */
 export interface BufferSink {
   append(chunk: string | NodeBuffer): void;
   toBuffer(): NodeBuffer;
@@ -37,6 +38,7 @@ export interface BufferSink {
   size(): number;
 }
 
+/** Options controlling allocation and growth for a Node buffer sink. */
 export interface BufferSinkOptions {
   /**
    * Initial backing buffer size (UTF-8 bytes). The buffer grows
@@ -50,15 +52,6 @@ export interface BufferSinkOptions {
   growthFactor?: number;
 }
 
-/**
- * Creates a Node-only buffer sink with a single pre-allocated growing
- * backing `Buffer`. UTF-8 encoding happens in-place at the current write
- * offset, avoiding per-chunk Buffer allocation and a final concat.
- *
- * Compared to `Buffer.concat`-style implementations, this trades a small
- * amount of headroom memory for ~5-10x throughput on small chunks
- * (see docs/benchmarks/2026-05-12-server-sink-strategy.md).
- */
 /**
  * A streaming-flavored buffer sink used by
  * `renderToReadableStream`. Coalesces successive `append(chunk)` calls
@@ -87,6 +80,7 @@ export interface StreamingBufferSink {
   size(): number;
 }
 
+/** Options controlling automatic flush behavior for a streaming buffer sink. */
 export interface StreamingBufferSinkOptions {
   /** UTF-8 byte threshold that triggers an automatic flush from inside
    *  `append`. Default 8 KiB (one common TCP segment payload). */
@@ -98,6 +92,7 @@ export interface StreamingBufferSinkOptions {
   onFlush(buffer: Uint8Array): void;
 }
 
+/** Creates a streaming sink that coalesces appended text into byte buffers. */
 export function createStreamingBufferSink(
   options: StreamingBufferSinkOptions,
 ): StreamingBufferSink {
@@ -186,6 +181,10 @@ function hasNodeBuffer(): boolean {
   return typeof Buffer !== "undefined" && typeof Buffer.allocUnsafe === "function";
 }
 
+/**
+ * Creates a Node-only buffer sink with a single pre-allocated growing
+ * backing `Buffer`.
+ */
 export function createBufferSink(options: BufferSinkOptions = {}): BufferSink {
   const initialSize = options.initialSize ?? 8192;
   const growthFactor = options.growthFactor ?? 2;

package/src/flight.ts

@@ -1,12 +1,15 @@
 import { getNativeFlight } from "./native-flight.js";
 
+/** Symbol tag used to identify client references in serialized Flight values. */
 export const CLIENT_REFERENCE_TYPE = Symbol.for("modular.react.client_reference");
+/** Symbol tag used to identify server references in serialized Flight values. */
 export const SERVER_REFERENCE_TYPE = Symbol.for("modular.react.server_reference");
 const CACHE_SCOPE_SYMBOL = Symbol.for("modular.react.cache_scope");
 
 const REACT_COMPAT_ELEMENT_TYPE = Symbol.for("react.transitional.element");
 const REACT_COMPAT_FRAGMENT_TYPE = Symbol.for("react.fragment");
 
+/** Registered client reference included in a Flight response. */
 export interface FlightClientReference {
   id: number;
   moduleId: string;
@@ -14,37 +17,46 @@ export interface FlightClientReference {
   chunks?: string[];
 }
 
+/** Input used to register a client reference before assigning a Flight id. */
 export interface FlightClientReferenceInput {
   name: string;
   moduleId: string;
   exportName: string;
 }
 
+/** Client manifest entry with resolved module chunks. */
 export interface FlightClientManifestEntry extends FlightClientReferenceInput {
   chunks: string[];
 }
 
+/** Function that can be invoked through a server action request. */
 export type ServerAction = (...args: unknown[]) => unknown | Promise<unknown>;
 
+/** Validation result returned by server action guards. */
 export type ServerActionValidationResult = boolean | string;
 
+/** Server action entry with optional argument validation. */
 export interface ServerActionDescriptor {
   action: ServerAction;
   validateArgs?: (args: unknown[]) => ServerActionValidationResult;
 }
 
+/** Registry mapping server action keys to handlers. */
 export type ServerActionRegistry = Record<string, ServerAction | ServerActionDescriptor>;
 
+/** Store used to reject replayed server action nonces. */
 export interface ServerActionReplayStore {
   has(value: string): boolean;
   add(value: string): void;
 }
 
+/** Module export reference requested by a server action request. */
 export interface ServerActionRequestReference {
   moduleId: string;
   exportName: string;
 }
 
+/** Security and validation options for createServerActionHandler. */
 export interface ServerActionHandlerOptions {
   // Issue 076: secure defaults. When undefined, the handler enforces the
   // same-origin policy by comparing `Origin` to the request URL. Pass an
@@ -77,11 +89,13 @@ export interface ServerActionHandlerOptions {
 
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
+/** Options for embedding a serialized Flight response in a script tag. */
 export interface FlightScriptOptions {
   id?: string;
   nonce?: string;
 }
 
+/** Registered server reference included in a Flight response. */
 export interface FlightServerReference {
   id: number;
   moduleId: string;
@@ -89,6 +103,7 @@ export interface FlightServerReference {
   bound?: FlightModel[];
 }
 
+/** Runtime marker object representing a client module export. */
 export interface ClientReference {
   $$typeof: typeof CLIENT_REFERENCE_TYPE;
   moduleId: string;
@@ -96,6 +111,7 @@ export interface ClientReference {
   chunks?: string[];
 }
 
+/** Runtime marker object representing a server module export. */
 export interface ServerReference {
   $$typeof: typeof SERVER_REFERENCE_TYPE;
   moduleId: string;
@@ -103,6 +119,7 @@ export interface ServerReference {
   bound?: unknown[];
 }
 
+/** Serializable Flight payload with root model and module references. */
 export interface FlightResponse {
   version: 1;
   root: FlightModel;
@@ -110,6 +127,7 @@ export interface FlightResponse {
   serverReferences: FlightServerReference[];
 }
 
+/** Recursive value model supported by the mreact Flight serializer. */
 export type FlightModel =
   | null
   | string
@@ -135,11 +153,13 @@ export type FlightModel =
   | FlightDataViewModel
   | { kind: "undefined" };
 
+/** Plain object shape inside a Flight model. */
 export interface FlightObjectModel {
   kind?: never;
   [key: string]: FlightModel | undefined;
 }
 
+/** Serialized React-compatible element inside a Flight model. */
 export interface FlightElementModel {
   kind: "element";
   type: string | FlightClientReferenceModel | { kind: "fragment" };
@@ -147,56 +167,67 @@ export interface FlightElementModel {
   props: Record<string, FlightModel>;
 }
 
+/** Reference to a client module export inside a Flight model. */
 export interface FlightClientReferenceModel {
   kind: "client-reference";
   id: number;
 }
 
+/** Reference to a server module export inside a Flight model. */
 export interface FlightServerReferenceModel {
   kind: "server-reference";
   id: number;
 }
 
+/** Serialized Date value inside a Flight model. */
 export interface FlightDateModel {
   kind: "date";
   value: string;
 }
 
+/** Serialized bigint value inside a Flight model. */
 export interface FlightBigIntModel {
   kind: "bigint";
   value: string;
 }
 
+/** Serialized non-finite or negative-zero number inside a Flight model. */
 export interface FlightNumberModel {
   kind: "number";
   value: "Infinity" | "-Infinity" | "NaN" | "-0";
 }
 
+/** Serialized global symbol reference inside a Flight model. */
 export interface FlightSymbolModel {
   kind: "symbol";
   name: string;
 }
 
+/** Serialized Map value inside a Flight model. */
 export interface FlightMapModel {
   kind: "map";
   entries: [FlightModel, FlightModel][];
 }
 
+/** Serialized Set value inside a Flight model. */
 export interface FlightSetModel {
   kind: "set";
   values: FlightModel[];
 }
 
+/** Serialized FormData value inside a Flight model. */
 export interface FlightFormDataModel {
   kind: "form-data";
   entries: [string, FlightModel][];
 }
 
+/** Serialized iterable value inside a Flight model. */
 export interface FlightIterableModel {
   kind: "iterable";
   values: FlightModel[];
 }
 
+/** Serialized Error value inside a Flight model. */
 export interface FlightErrorModel {
   kind: "error";
   name: string;
@@ -204,27 +235,32 @@ export interface FlightErrorModel {
   digest?: string;
 }
 
+/** Reference to an outlined promise chunk inside a Flight model. */
 export interface FlightPromiseModel {
   kind: "promise";
   id: number;
 }
 
+/** Serialized ArrayBuffer value inside a Flight model. */
 export interface FlightArrayBufferModel {
   kind: "array-buffer";
   bytes: number[];
 }
 
+/** Serialized typed array value inside a Flight model. */
 export interface FlightTypedArrayModel {
   kind: "typed-array";
   arrayType: FlightTypedArrayName;
   bytes: number[];
 }
 
+/** Serialized DataView value inside a Flight model. */
 export interface FlightDataViewModel {
   kind: "data-view";
   bytes: number[];
 }
 
+/** Typed array constructor names supported by the Flight serializer. */
 export type FlightTypedArrayName =
   | "Int8Array"
   | "Uint8Array"
@@ -262,12 +298,14 @@ const reactFlightModelTokens = [
   "$undefined",
 ] as const;
 
+/** Lists the React Flight row tags and model tokens covered by the serializer. */
 export interface ReactFlightProtocolCoverage {
   binaryRowTags: string[];
   modelTokens: string[];
   rowTags: string[];
 }
 
+/** Returns the React Flight protocol tags and tokens supported by this package. */
 export function getReactFlightProtocolCoverage(): ReactFlightProtocolCoverage {
   return {
     binaryRowTags: [...reactFlightBinaryRowTags],
@@ -296,6 +334,7 @@ interface ServerCacheScope {
   ownerStack: string[];
 }
 
+/** Creates a runtime client reference marker for a module export. */
 export function createClientReference(
   moduleId: string,
   exportName = "default",
@@ -309,6 +348,7 @@ export function createClientReference(
   };
 }
 
+/** Creates a runtime server reference marker for a module export. */
 export function createServerReference(
   moduleId: string,
   exportName = "default",
@@ -322,6 +362,7 @@ export function createServerReference(
   };
 }
 
+/** Returns true when a value is a runtime client reference marker. */
 export function isClientReference(value: unknown): value is ClientReference {
   return (
     typeof value === "object" &&
@@ -330,6 +371,7 @@ export function isClientReference(value: unknown): value is ClientReference {
   );
 }
 
+/** Returns true when a value is a runtime server reference marker. */
 export function isServerReference(value: unknown): value is ServerReference {
   return (
     typeof value === "object" &&
@@ -338,6 +380,7 @@ export function isServerReference(value: unknown): value is ServerReference {
   );
 }
 
+/** Serializes a renderable value into a structured Flight response. */
 export async function renderToFlightResponse<P extends Record<string, unknown>>(
   renderable: ((props: P) => unknown) | unknown,
   props = {} as P,
@@ -363,10 +406,12 @@ export async function renderToFlightResponse<P extends Record<string, unknown>>(
   });
 }
 
+/** Serializes a Flight response to JSON text. */
 export function stringifyFlightResponse(response: FlightResponse): string {
   return JSON.stringify(response);
 }
 
+/** Renders a Flight response as an HTML script tag. */
 export function renderFlightResponseScript(
   response: FlightResponse,
   options: FlightScriptOptions = {},
@@ -378,6 +423,7 @@ export function renderFlightResponseScript(
   return `<script type="application/json" data-mreact-flight${idAttribute}${nonceAttribute}>${serializeJsonForHtml(response)}</script>`;
 }
 
+/** Creates a request handler that validates and invokes registered server actions. */
 export function createServerActionHandler(
   actions: ServerActionRegistry,
   options: ServerActionHandlerOptions = {},
@@ -498,6 +544,7 @@ export function createServerActionHandler(
   };
 }
 
+/** Encodes a structured Flight response into React Flight row text. */
 export function toReactFlightRows(response: FlightResponse): string {
   // Issue 081 note: a native encoder exists in
   // `packages/router-native/src/flight.rs::encode_flight_response`
@@ -555,6 +602,7 @@ export function toReactFlightRows(response: FlightResponse): string {
   return rows.join("\n");
 }
 
+/** Decodes React Flight row text into a structured Flight response. */
 export function fromReactFlightRows(rows: string): FlightResponse {
   // Issue 081 note: a native decoder exists in
   // `packages/router-native/src/flight.rs::decode_flight_rows`
@@ -644,6 +692,7 @@ export function fromReactFlightRows(rows: string): FlightResponse {
   };
 }
 
+/** Merges additional React Flight row text into an existing Flight response. */
 export function mergeReactFlightRows(
   response: FlightResponse,
   rows: string,
@@ -700,6 +749,7 @@ export function mergeReactFlightRows(
   };
 }
 
+/** Builds a Flight client manifest from client references and chunk resolution. */
 export function createFlightClientManifest(
   references: readonly FlightClientReferenceInput[],
   resolveChunks: (reference: FlightClientReferenceInput) => string[],
@@ -710,6 +760,7 @@ export function createFlightClientManifest(
   }));
 }
 
+/** Renders modulepreload links for client chunks referenced by a Flight response. */
 export function renderFlightPreloadLinks(
   response: FlightResponse,
   options: { nonce?: string } = {},

package/src/html-helpers.ts

@@ -28,6 +28,7 @@ import {
 import { createStringSink, hasDeferredTasks, type StreamRender } from "./sink.js";
 import { renderToReadableStream } from "./stream.js";
 
+/** External script asset attributes emitted by renderScriptAsset. */
 export interface ScriptAssetOptions {
   src: string;
   nonce?: string;
@@ -35,27 +36,32 @@ export interface ScriptAssetOptions {
   crossOrigin?: "anonymous" | "use-credentials";
 }
 
+/** Event handler entry used by the hydration manifest. */
 export interface EventHydrationEntry {
   id: string;
   event: string;
   handler: string;
 }
 
+/** Manifest of event handlers that can be hydrated on the client. */
 export interface EventHydrationManifest {
   version: 1;
   events: EventHydrationEntry[];
 }
 
+/** Response options used when wrapping rendered HTML in a Response. */
 export interface HtmlResponseOptions {
   headers?: HeadersInit;
   status?: number;
   statusText?: string;
 }
 
+/** Serializes state for safe embedding in an HTML script tag. */
 export function serializeSsrState(value: unknown): string {
   return serializeScriptJson(value);
 }
 
+/** Appends serialized SSR state as a JSON script tag. */
 export function renderSsrState(
   sink: HtmlSink,
   value: unknown,
@@ -66,6 +72,7 @@ export function renderSsrState(
   );
 }
 
+/** Creates a defensive copy of an event hydration manifest. */
 export function createEventHydrationManifest(
   events: readonly EventHydrationEntry[],
 ): EventHydrationManifest {
@@ -75,6 +82,7 @@ export function createEventHydrationManifest(
   };
 }
 
+/** Appends an event hydration manifest as a JSON script tag. */
 export function renderEventHydrationManifest(
   sink: HtmlSink,
   manifest: EventHydrationManifest,
@@ -85,6 +93,7 @@ export function renderEventHydrationManifest(
   );
 }
 
+/** Appends an external script tag with optional nonce and integrity attributes. */
 export function renderScriptAsset(sink: HtmlSink, options: ScriptAssetOptions): void {
   const integrityAttribute =
     options.integrity === undefined ? "" : ` integrity="${escapeAttribute(options.integrity)}"`;
@@ -98,6 +107,7 @@ export function renderScriptAsset(sink: HtmlSink, options: ScriptAssetOptions):
   );
 }
 
+/** Creates an HTML Response from a React-compatible node. */
 export function html(node: unknown, options: HtmlResponseOptions = {}): Response {
   const headers = new Headers(options.headers);
   const responseOptions: ResponseInit = { headers };
@@ -123,6 +133,7 @@ export function html(node: unknown, options: HtmlResponseOptions = {}): Response
   );
 }
 
+/** Renders sink output to a string after awaiting deferred work. */
 export async function renderToString(render: StreamRender): Promise<string> {
   const sink = createStringSink();
 
@@ -132,6 +143,7 @@ export async function renderToString(render: StreamRender): Promise<string> {
   return sink.toString();
 }
 
+/** Renders a React-compatible node to an HTML string. */
 export async function renderReactNodeToString(node: unknown): Promise<string> {
   const sink = createStringSink();
   const state: HtmlRenderState = { suspenseId: 0 };

package/src/index.ts

@@ -4,8 +4,11 @@ import {
   type ReactCompatNode,
 } from "@reckona/mreact-compat";
 
+/** Fragment marker used to group children without emitting an extra element. */
 export { Fragment } from "@reckona/mreact-compat";
+/** Any value accepted by the React-compatible renderer. */
 export type { ReactCompatNode } from "@reckona/mreact-compat";
+/** Receives HTML chunks and deferred work while server rendering. */
 export type { HtmlSink } from "@reckona/mreact-shared/compiler-contract";
 
 export {
@@ -109,11 +112,13 @@ export type {
   ScriptAssetOptions,
 } from "./html-helpers.js";
 
+/** Props accepted by the server Suspense compatibility component. */
 export interface SuspenseProps extends Record<string, unknown> {
   fallback?: unknown;
   children?: unknown;
 }
 
+/** Creates a React-compatible Suspense boundary for server rendering. */
 export function Suspense(props: SuspenseProps): never {
   const config: SuspenseProps = {};
 

package/src/reorder.ts

@@ -1,3 +1,4 @@
+/** Moves out-of-order fragments into their matching placeholders within a DOM root. */
 export function applyOutOfOrderFragments(root: ParentNode = document): void {
   const fragments = Array.from(
     root.querySelectorAll<HTMLTemplateElement>(

package/src/sink.ts

@@ -1,22 +1,27 @@
 import type { HtmlSink } from "@reckona/mreact-shared/compiler-contract";
 
+/** HTML sink that buffers output as a string and can await deferred tasks. */
 export interface StringHtmlSink extends HtmlSink {
   bufferStrategy(): StringSinkBufferStrategy;
   drain(): Promise<void>;
   toString(): string;
 }
 
+/** String buffering strategy used by createStringSink. */
 export type StringSinkBufferStrategy = "concat" | "array-join";
 
+/** Options controlling how a string sink buffers appended chunks. */
 export interface StringSinkOptions {
   strategy?: StringSinkBufferStrategy | "auto";
   arrayJoinThreshold?: number;
 }
 
+/** Callback that writes server-rendered HTML into a sink. */
 export type StreamRender = (sink: HtmlSink) => void | PromiseLike<void>;
 
 const stringSinkDeferredTasks = new WeakMap<HtmlSink, PromiseLike<void>[]>();
 
+/** Creates an HTML sink that stores appended chunks in memory as a string. */
 export function createStringSink(options: StringSinkOptions = {}): StringHtmlSink {
   // Default to "concat" - V8 rope flattening yields 2-6x throughput over
   // `Array#join("")` across all measured fixture sizes (see
@@ -81,6 +86,7 @@ export function createStringSink(options: StringSinkOptions = {}): StringHtmlSin
   return sink;
 }
 
+/** Returns true when a sink created by createStringSink has deferred tasks. */
 export function hasDeferredTasks(sink: HtmlSink): boolean {
   return (stringSinkDeferredTasks.get(sink)?.length ?? 0) > 0;
 }

package/src/stream.ts

@@ -1,12 +1,14 @@
 import { createStreamingBufferSink } from "./buffer-sink.js";
 import type { StreamRender } from "./sink.js";
 
+/** Options controlling server render stream error logging behavior. */
 export interface RenderToReadableStreamOptions {
   logAbortedDeferredErrors?: boolean;
 }
 
 const streamQueuedChunkSoftLimitBytes = 1024 * 1024;
 
+/** Renders HTML sink output to a WHATWG readable byte stream. */
 export function renderToReadableStream(
   render: StreamRender,
   options: RenderToReadableStreamOptions = {},