@fluojs/react 0.1.0

package/dist/render-stream.js

@@ -0,0 +1,135 @@
+import { RequestAbortedError } from '@fluojs/http';
+
+/** Minimal request abort surface used while React Web Streams are read. */
+
+function createAbortWait(signal) {
+  if (!signal) {
+    return undefined;
+  }
+  if (signal.aborted) {
+    return {
+      cleanup: () => undefined,
+      promise: Promise.resolve('aborted')
+    };
+  }
+  let listener;
+  const promise = new Promise(resolve => {
+    listener = () => resolve('aborted');
+    signal.addEventListener('abort', listener, {
+      once: true
+    });
+  });
+  return {
+    cleanup: () => {
+      if (listener) {
+        signal.removeEventListener('abort', listener);
+      }
+    },
+    promise
+  };
+}
+function isReactRequestAborted(source) {
+  return source.isAborted?.() === true || source.signal?.aborted === true;
+}
+
+/**
+ * Throws when a request has been aborted through either supported HTTP abort surface.
+ *
+ * @param source Request abort source exposed by the active fluo request.
+ */
+export function throwIfReactRequestAborted(source) {
+  if (isReactRequestAborted(source)) {
+    throw new RequestAbortedError();
+  }
+}
+async function readNextChunk(reader, abortSource) {
+  if (isReactRequestAborted(abortSource)) {
+    return 'aborted';
+  }
+  const abort = createAbortWait(abortSource.signal);
+  if (!abort) {
+    const next = await reader.read();
+    return isReactRequestAborted(abortSource) ? 'aborted' : next;
+  }
+  try {
+    const next = await Promise.race([reader.read(), abort.promise]);
+    return next === 'aborted' || isReactRequestAborted(abortSource) ? 'aborted' : next;
+  } finally {
+    abort.cleanup();
+  }
+}
+
+/**
+ * Collects a React HTML stream for buffered hosts without committing partial bodies after abort.
+ *
+ * @param stream React Web Stream to collect.
+ * @param abortSource Request abort source checked before buffered response metadata is applied.
+ * @returns Fully collected HTML bytes.
+ */
+export async function collectReadableStream(stream, abortSource) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let byteLength = 0;
+  try {
+    while (!isReactRequestAborted(abortSource)) {
+      const next = await readNextChunk(reader, abortSource);
+      if (next === 'aborted') {
+        await reader.cancel();
+        throw new RequestAbortedError();
+      }
+      if (next.done) {
+        break;
+      }
+      chunks.push(next.value);
+      byteLength += next.value.byteLength;
+    }
+    if (isReactRequestAborted(abortSource)) {
+      await reader.cancel();
+      throw new RequestAbortedError();
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+
+/**
+ * Pipes a React HTML stream into an already committed streaming response until close or abort.
+ *
+ * @param stream React Web Stream to pipe.
+ * @param target Response stream that receives HTML chunks.
+ * @param abortSource Request abort source checked between chunks.
+ * @returns A promise that resolves when piping stops and the target is closed.
+ */
+export async function pipeReadableStream(stream, target, abortSource) {
+  const reader = stream.getReader();
+  try {
+    while (!isReactRequestAborted(abortSource) && !target.closed) {
+      const next = await readNextChunk(reader, abortSource);
+      if (next === 'aborted') {
+        break;
+      }
+      if (next.done) {
+        break;
+      }
+      const accepted = target.write(next.value);
+      if (!accepted) {
+        await target.waitForDrain?.();
+      }
+    }
+    if (isReactRequestAborted(abortSource)) {
+      await reader.cancel();
+    }
+  } finally {
+    reader.releaseLock();
+    if (!target.closed) {
+      target.close();
+    }
+  }
+}

package/dist/render.d.ts

@@ -0,0 +1,50 @@
+import type { RequestContext } from '@fluojs/http';
+import type { ReactNode } from 'react';
+import type { ReactAssetMap, ReactBootstrapAsset, ReactServerEntry } from './server-entry.js';
+/** Readable stream returned by React's Web Streams SSR renderer. */
+export type ReactReadableStream = ReadableStream<Uint8Array> & {
+    /** Promise exposed by React for callers that intentionally wait for all Suspense boundaries. */
+    readonly allReady?: Promise<void>;
+};
+/** React Web Streams render options used by `renderReactResponse(...)`. */
+export type ReactReadableStreamRenderOptions = {
+    /** Trusted build-produced asset map shared with custom server renderers and client hydration code. */
+    readonly assetMap?: ReactAssetMap;
+    /** Module script URLs or descriptors forwarded to React DOM `bootstrapModules`. */
+    readonly bootstrapModules?: readonly ReactBootstrapAsset[];
+    /** Trusted inline bootstrap script content forwarded to React DOM without serialization. */
+    readonly bootstrapScriptContent?: string;
+    /** Classic script URLs or descriptors forwarded to React DOM `bootstrapScripts`. */
+    readonly bootstrapScripts?: readonly ReactBootstrapAsset[];
+    /** Stable React `useId()` prefix shared with client hydration. */
+    readonly identifierPrefix?: string;
+    /** CSP nonce applied by React DOM to emitted bootstrap scripts. */
+    readonly nonce?: string;
+    /** Reports render errors observed by React during shell or Suspense streaming. */
+    readonly onError?: (error: unknown, errorInfo?: unknown) => void;
+    /** Abort signal propagated from the active fluo request when the adapter provides one. */
+    readonly signal?: AbortSignal;
+};
+/** Function compatible with `react-dom/server` `renderToReadableStream`. */
+export type ReactReadableStreamRenderer = (node: ReactNode, options: ReactReadableStreamRenderOptions) => Promise<ReactReadableStream>;
+/** Options for rendering a React entry into one fluo response. */
+export type RenderReactResponseOptions = {
+    /** Applies dispatcher-owned success metadata after shell creation and before response commit. */
+    readonly applySuccessResponseMetadata?: () => void;
+    /** Test or custom renderer override. Defaults to lazy `react-dom/server` Web Streams rendering. */
+    readonly renderToReadableStream?: ReactReadableStreamRenderer;
+};
+/** Minimal fluo request context needed to render one React HTML response. */
+export type ReactRenderContext = Pick<RequestContext, 'request' | 'requestId' | 'response'>;
+/**
+ * Renders a React server entry to one fluo HTML response using Web Streams SSR.
+ *
+ * @param entry React server entry created by `createReactServerEntry(...)`.
+ * @param requestContext Active fluo request context whose response receives the HTML stream.
+ * @param options Optional custom renderer, primarily for tests and custom React DOM integration.
+ * @returns A promise that resolves when the shell stream has been fully piped or a committed streaming response observes request abort.
+ * @throws Shell render errors before any response bytes are committed.
+ * @throws RequestAbortedError before buffered responses commit when the request aborts.
+ */
+export declare function renderReactResponse(entry: ReactServerEntry, requestContext: ReactRenderContext, options?: RenderReactResponseOptions): Promise<void>;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EAGnB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAK3B,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG;IAC7D,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,gCAAgC,GAAG;IAC7C,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC3D,4FAA4F;IAC5F,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC3D,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjE,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,CAAC;AAoBF,4EAA4E;AAC5E,MAAM,MAAM,2BAA2B,GAAG,CACxC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,gCAAgC,KACtC,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,kEAAkE;AAClE,MAAM,MAAM,0BAA0B,GAAG;IACvC,iGAAiG;IACjG,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,IAAI,CAAC;IACnD,mGAAmG;IACnG,QAAQ,CAAC,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;CAC/D,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC,CAAC;AAyJ5F;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,kBAAkB,EAClC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/render.js

@@ -0,0 +1,201 @@
+import { collectReadableStream, pipeReadableStream, throwIfReactRequestAborted } from './render-stream.js';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+
+/** Readable stream returned by React's Web Streams SSR renderer. */
+
+/** React Web Streams render options used by `renderReactResponse(...)`. */
+
+/** Function compatible with `react-dom/server` `renderToReadableStream`. */
+
+/** Options for rendering a React entry into one fluo response. */
+
+/** Minimal fluo request context needed to render one React HTML response. */
+
+function applyEntryHeaders(entry, requestContext) {
+  for (const [name, value] of Object.entries(entry.headers)) {
+    requestContext.response.setHeader(name, typeof value === 'string' ? value : [...value]);
+  }
+  requestContext.response.setHeader('Content-Type', HTML_CONTENT_TYPE);
+}
+function applyEntryStatus(entry, requestContext) {
+  if (entry.status !== undefined) {
+    requestContext.response.setStatus(entry.status);
+    return;
+  }
+  if (requestContext.response.statusSet !== true) {
+    requestContext.response.setStatus(200);
+  }
+}
+function cloneBootstrapDescriptor(asset) {
+  return {
+    ...(asset.crossOrigin !== undefined ? {
+      crossOrigin: asset.crossOrigin
+    } : {}),
+    ...(asset.integrity !== undefined ? {
+      integrity: asset.integrity
+    } : {}),
+    src: asset.src
+  };
+}
+function cloneBootstrapAsset(asset) {
+  return typeof asset === 'string' ? asset : cloneBootstrapDescriptor(asset);
+}
+function cloneBootstrapAssets(assets) {
+  return assets && assets.length > 0 ? assets.map(cloneBootstrapAsset) : undefined;
+}
+function hasAssetMap(assetMap) {
+  return Object.keys(assetMap).length > 0;
+}
+function createReactReadableStreamRenderOptions(entry, requestContext, onError) {
+  return {
+    ...(hasAssetMap(entry.assetMap) ? {
+      assetMap: entry.assetMap
+    } : {}),
+    ...(entry.bootstrapModules.length > 0 ? {
+      bootstrapModules: entry.bootstrapModules
+    } : {}),
+    ...(entry.bootstrapScriptContent !== undefined ? {
+      bootstrapScriptContent: entry.bootstrapScriptContent
+    } : {}),
+    ...(entry.bootstrapScripts.length > 0 ? {
+      bootstrapScripts: entry.bootstrapScripts
+    } : {}),
+    ...(entry.identifierPrefix !== undefined ? {
+      identifierPrefix: entry.identifierPrefix
+    } : {}),
+    ...(entry.nonce !== undefined ? {
+      nonce: entry.nonce
+    } : {}),
+    onError,
+    ...(requestContext.request.signal !== undefined ? {
+      signal: requestContext.request.signal
+    } : {})
+  };
+}
+function createReactDomRenderOptions(options) {
+  return {
+    ...(options.bootstrapModules !== undefined ? {
+      bootstrapModules: cloneBootstrapAssets(options.bootstrapModules)
+    } : {}),
+    ...(options.bootstrapScriptContent !== undefined ? {
+      bootstrapScriptContent: options.bootstrapScriptContent
+    } : {}),
+    ...(options.bootstrapScripts !== undefined ? {
+      bootstrapScripts: cloneBootstrapAssets(options.bootstrapScripts)
+    } : {}),
+    ...(options.identifierPrefix !== undefined ? {
+      identifierPrefix: options.identifierPrefix
+    } : {}),
+    ...(options.nonce !== undefined ? {
+      nonce: options.nonce
+    } : {}),
+    ...(options.onError !== undefined ? {
+      onError: options.onError
+    } : {}),
+    ...(options.signal !== undefined ? {
+      signal: options.signal
+    } : {})
+  };
+}
+function createRecoverableErrorContext(errorInfo, requestContext) {
+  return {
+    ...(errorInfo !== undefined ? {
+      errorInfo
+    } : {}),
+    request: requestContext.request,
+    ...(requestContext.requestId !== undefined ? {
+      requestId: requestContext.requestId
+    } : {})
+  };
+}
+function reportRecoverableError(entry, requestContext, event) {
+  const hook = entry.onRecoverableError;
+  if (!hook) {
+    return;
+  }
+  try {
+    hook(event.error, createRecoverableErrorContext(event.errorInfo, requestContext));
+  } catch (error) {
+    if (error instanceof Error) {
+      return;
+    }
+  }
+}
+function reportRecoverableErrors(entry, requestContext, events) {
+  for (const event of events) {
+    reportRecoverableError(entry, requestContext, event);
+  }
+}
+async function writeReactStream(plan) {
+  const {
+    applySuccessMetadata,
+    entry,
+    pendingRecoverableErrors,
+    requestContext,
+    stream
+  } = plan;
+  const responseStream = requestContext.response.stream;
+  if (!responseStream) {
+    const body = await collectReadableStream(stream, requestContext.request);
+    throwIfReactRequestAborted(requestContext.request);
+    applySuccessMetadata();
+    reportRecoverableErrors(entry, requestContext, pendingRecoverableErrors);
+    await requestContext.response.send(body);
+    return;
+  }
+  applySuccessMetadata();
+  requestContext.response.committed = true;
+  responseStream.flush?.();
+  reportRecoverableErrors(entry, requestContext, pendingRecoverableErrors);
+  await pipeReadableStream(stream, responseStream, requestContext.request);
+}
+async function defaultRenderToReadableStream(node, options) {
+  const {
+    renderToReadableStream
+  } = await import('react-dom/server');
+  return renderToReadableStream(node, createReactDomRenderOptions(options));
+}
+
+/**
+ * Renders a React server entry to one fluo HTML response using Web Streams SSR.
+ *
+ * @param entry React server entry created by `createReactServerEntry(...)`.
+ * @param requestContext Active fluo request context whose response receives the HTML stream.
+ * @param options Optional custom renderer, primarily for tests and custom React DOM integration.
+ * @returns A promise that resolves when the shell stream has been fully piped or a committed streaming response observes request abort.
+ * @throws Shell render errors before any response bytes are committed.
+ * @throws RequestAbortedError before buffered responses commit when the request aborts.
+ */
+export async function renderReactResponse(entry, requestContext, options = {}) {
+  throwIfReactRequestAborted(requestContext.request);
+  const renderToReadableStream = options.renderToReadableStream ?? defaultRenderToReadableStream;
+  const pendingRecoverableErrors = [];
+  let shellReady = false;
+  const stream = await renderToReadableStream(entry.node, createReactReadableStreamRenderOptions(entry, requestContext, (error, errorInfo) => {
+    const event = errorInfo !== undefined ? {
+      error,
+      errorInfo
+    } : {
+      error
+    };
+    if (shellReady) {
+      reportRecoverableError(entry, requestContext, event);
+      return;
+    }
+    pendingRecoverableErrors.push(event);
+  }));
+  shellReady = true;
+  throwIfReactRequestAborted(requestContext.request);
+  const applySuccessMetadata = () => {
+    options.applySuccessResponseMetadata?.();
+    applyEntryStatus(entry, requestContext);
+    applyEntryHeaders(entry, requestContext);
+  };
+  await writeReactStream({
+    applySuccessMetadata,
+    entry,
+    pendingRecoverableErrors,
+    requestContext,
+    stream
+  });
+}

package/dist/server-entry.d.ts

@@ -0,0 +1,87 @@
+import type { FrameworkRequest } from '@fluojs/http';
+import { type ReactNode } from 'react';
+/** Header values applied before a React server entry starts streaming. */
+export type ReactServerEntryHeaders = Readonly<Record<string, string | readonly string[]>>;
+/** Build-produced asset names mapped to public URLs shared by server render and client hydration. */
+export type ReactAssetMap = Readonly<Record<string, string>>;
+/** Descriptor for a bootstrap script or module tag emitted by React DOM server rendering. */
+export type ReactBootstrapScriptDescriptor = {
+    /** Public URL used for the script `src` attribute. */
+    readonly src: string;
+    /** Optional `crossorigin` attribute forwarded to the emitted script tag. */
+    readonly crossOrigin?: string;
+    /** Optional Subresource Integrity value forwarded to the emitted script tag. */
+    readonly integrity?: string;
+};
+/** Bootstrap asset accepted by React DOM server rendering. */
+export type ReactBootstrapAsset = string | ReactBootstrapScriptDescriptor;
+/** Recoverable React render error details reported after the shell can stream. */
+export type ReactRecoverableErrorContext = {
+    /** React-provided error metadata, such as a component stack, when available. */
+    readonly errorInfo?: unknown;
+    /** Framework request being rendered. */
+    readonly request: FrameworkRequest;
+    /** Adapter-provided request id, when available. */
+    readonly requestId?: string;
+};
+/** Hook invoked when React reports a recoverable streaming render error. */
+export type ReactRecoverableErrorHandler = (error: unknown, context: ReactRecoverableErrorContext) => void;
+/** Options used to create a React server entry. */
+export type ReactServerEntryOptions = {
+    /** Trusted build-produced asset map available to server rendering and client hydration code. */
+    readonly assetMap?: ReactAssetMap;
+    /** Module script URLs or descriptors forwarded to React DOM `bootstrapModules`. */
+    readonly bootstrapModules?: readonly ReactBootstrapAsset[];
+    /** Trusted inline bootstrap script content forwarded to React DOM without serialization. */
+    readonly bootstrapScriptContent?: string;
+    /** Classic script URLs or descriptors forwarded to React DOM `bootstrapScripts`. */
+    readonly bootstrapScripts?: readonly ReactBootstrapAsset[];
+    /** Additional response headers to apply before the HTML stream commits. */
+    readonly headers?: ReactServerEntryHeaders;
+    /** Stable React `useId()` prefix shared with client hydration. */
+    readonly identifierPrefix?: string;
+    /** CSP nonce applied by React DOM to emitted bootstrap scripts. */
+    readonly nonce?: string;
+    /** Hook for recoverable errors reported by React after the shell is ready. */
+    readonly onRecoverableError?: ReactRecoverableErrorHandler;
+    /** HTTP status to apply before streaming starts. Defaults to the current response status or `200`. */
+    readonly status?: number;
+};
+/** Runtime-neutral React server entry rendered to streamed HTML by `renderReactResponse(...)`. */
+export type ReactServerEntry = {
+    /** Trusted build-produced asset map available to server rendering and client hydration code. */
+    readonly assetMap: ReactAssetMap;
+    /** Module script URLs or descriptors forwarded to React DOM `bootstrapModules`. */
+    readonly bootstrapModules: readonly ReactBootstrapAsset[];
+    /** Trusted inline bootstrap script content forwarded to React DOM without serialization. */
+    readonly bootstrapScriptContent?: string;
+    /** Classic script URLs or descriptors forwarded to React DOM `bootstrapScripts`. */
+    readonly bootstrapScripts: readonly ReactBootstrapAsset[];
+    /** Additional response headers to apply before the HTML stream commits. */
+    readonly headers: ReactServerEntryHeaders;
+    /** Stable React `useId()` prefix shared with client hydration. */
+    readonly identifierPrefix?: string;
+    /** React tree rendered with `react-dom/server` Web Streams APIs. */
+    readonly node: ReactNode;
+    /** CSP nonce applied by React DOM to emitted bootstrap scripts. */
+    readonly nonce?: string;
+    /** Hook for recoverable errors reported by React after the shell is ready. */
+    readonly onRecoverableError?: ReactRecoverableErrorHandler;
+    /** HTTP status to apply before streaming starts. Defaults to the current response status or `200`. */
+    readonly status?: number;
+};
+/**
+ * Creates a runtime-neutral React server entry for streamed HTML rendering.
+ *
+ * @remarks
+ * The entry is the stable root SSR handoff for page handlers registered through
+ * `@Router(...)` and `@Path(...)`. It forwards explicit React DOM hydration asset
+ * options only; Vite manifest discovery, client bundle generation, RSC, and Server
+ * Functions remain outside the root `@fluojs/react` contract.
+ *
+ * @param node React node tree returned by a page handler.
+ * @param options Optional status, headers, and recoverable error hook for the render.
+ * @returns A defensive React server entry snapshot suitable for `renderReactResponse(...)`.
+ */
+export declare function createReactServerEntry(node: ReactNode, options?: ReactServerEntryOptions): ReactServerEntry;
+//# sourceMappingURL=server-entry.d.ts.map

package/dist/server-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-entry.d.ts","sourceRoot":"","sources":["../src/server-entry.ts"],"names":[],"mappings":"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"}

package/dist/server-entry.js

@@ -0,0 +1,126 @@
+import { cloneElement, isValidElement } from 'react';
+const responseWriterKey = Symbol.for('fluo.http.responseWriter');
+
+/** Header values applied before a React server entry starts streaming. */
+
+/** Build-produced asset names mapped to public URLs shared by server render and client hydration. */
+
+/** Descriptor for a bootstrap script or module tag emitted by React DOM server rendering. */
+
+/** Bootstrap asset accepted by React DOM server rendering. */
+
+/** Recoverable React render error details reported after the shell can stream. */
+
+/** Hook invoked when React reports a recoverable streaming render error. */
+
+/** Options used to create a React server entry. */
+
+/** Runtime-neutral React server entry rendered to streamed HTML by `renderReactResponse(...)`. */
+
+function cloneAssetMap(assetMap) {
+  const cloned = {};
+  Object.setPrototypeOf(cloned, null);
+  for (const [name, url] of Object.entries(assetMap ?? {})) {
+    cloned[name] = url;
+  }
+  return cloned;
+}
+function cloneBootstrapAsset(asset) {
+  if (typeof asset === 'string') {
+    return asset;
+  }
+  return {
+    ...(asset.crossOrigin !== undefined ? {
+      crossOrigin: asset.crossOrigin
+    } : {}),
+    ...(asset.integrity !== undefined ? {
+      integrity: asset.integrity
+    } : {}),
+    src: asset.src
+  };
+}
+function getBootstrapAssetSource(asset) {
+  return typeof asset === 'string' ? asset : asset.src;
+}
+function cloneUniqueBootstrapAssets(assets) {
+  const cloned = [];
+  const seenSources = new Set();
+  for (const asset of assets ?? []) {
+    const source = getBootstrapAssetSource(asset);
+    if (seenSources.has(source)) {
+      continue;
+    }
+    seenSources.add(source);
+    cloned.push(cloneBootstrapAsset(asset));
+  }
+  return cloned;
+}
+function cloneHeaders(headers) {
+  const cloned = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    cloned[name] = typeof value === 'string' ? value : [...value];
+  }
+  return cloned;
+}
+function cloneNodeAssetMapProp(node, originalAssetMap, assetMapSnapshot) {
+  if (originalAssetMap === undefined || !isValidElement(node)) {
+    return node;
+  }
+  if (node.props.assetMap !== originalAssetMap) {
+    return node;
+  }
+  return cloneElement(node, {
+    assetMap: assetMapSnapshot
+  });
+}
+
+/**
+ * Creates a runtime-neutral React server entry for streamed HTML rendering.
+ *
+ * @remarks
+ * The entry is the stable root SSR handoff for page handlers registered through
+ * `@Router(...)` and `@Path(...)`. It forwards explicit React DOM hydration asset
+ * options only; Vite manifest discovery, client bundle generation, RSC, and Server
+ * Functions remain outside the root `@fluojs/react` contract.
+ *
+ * @param node React node tree returned by a page handler.
+ * @param options Optional status, headers, and recoverable error hook for the render.
+ * @returns A defensive React server entry snapshot suitable for `renderReactResponse(...)`.
+ */
+export function createReactServerEntry(node, options = {}) {
+  const assetMap = cloneAssetMap(options.assetMap);
+  const entry = {
+    assetMap,
+    bootstrapModules: cloneUniqueBootstrapAssets(options.bootstrapModules),
+    ...(options.bootstrapScriptContent !== undefined ? {
+      bootstrapScriptContent: options.bootstrapScriptContent
+    } : {}),
+    bootstrapScripts: cloneUniqueBootstrapAssets(options.bootstrapScripts),
+    headers: cloneHeaders(options.headers),
+    ...(options.identifierPrefix !== undefined ? {
+      identifierPrefix: options.identifierPrefix
+    } : {}),
+    node: cloneNodeAssetMapProp(node, options.assetMap, assetMap),
+    ...(options.nonce !== undefined ? {
+      nonce: options.nonce
+    } : {}),
+    ...(options.onRecoverableError !== undefined ? {
+      onRecoverableError: options.onRecoverableError
+    } : {}),
+    ...(options.status !== undefined ? {
+      status: options.status
+    } : {})
+  };
+  Object.defineProperty(entry, responseWriterKey, {
+    enumerable: false,
+    value: async context => {
+      const {
+        renderReactResponse
+      } = await import('./render.js');
+      await renderReactResponse(entry, context.requestContext, {
+        applySuccessResponseMetadata: context.applySuccessResponseMetadata
+      });
+    }
+  });
+  return entry;
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Planning marker for the first public `@fluojs/react` package surface.
+ *
+ * @remarks
+ * The package manifest starts at `0.0.0` so the committed Changesets minor release intent
+ * can produce the planned `0.1.0` initial public version through the canonical release flow.
+ * This marker describes the stable root SSR MVP; Vite assets, client navigation, and
+ * RSC/server functions belong to future subpaths rather than the root package.
+ */
+export type ReactScaffoldPhase = '0.1.0-scaffold';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};