@fluojs/react 0.1.0 → 0.2.0

package/dist/page-catalog.d.ts

@@ -0,0 +1,29 @@
+import type { HandlerDescriptor, HttpMethod } from '@fluojs/http/portable';
+/**
+ * Immutable bootstrap-resolved description of one React page handler.
+ *
+ * @remarks
+ * The catalog is a one-way projection from authoritative compiled HTTP descriptors.
+ * Effective path, method, version, and params come from HTTP compilation rather than
+ * the static values passed to `@Router(...)` and `@Path(...)`. Catalog entries never
+ * participate in route matching, conflict detection, or dispatch.
+ */
+export interface ReactPageCatalogEntry {
+    readonly handler: string;
+    readonly id: string;
+    readonly kind: 'react-page';
+    readonly method: HttpMethod;
+    readonly module?: string;
+    readonly params: readonly string[];
+    readonly path: string;
+    readonly router: string;
+    readonly version?: string;
+}
+/**
+ * Creates an immutable React page catalog from compiled HTTP handler descriptors.
+ *
+ * @param descriptors Authoritative descriptors produced by `createHandlerMapping(...)`.
+ * @returns Frozen React page entries in descriptor registration order; ordinary HTTP handlers are omitted.
+ */
+export declare function createReactPageCatalog(descriptors: readonly HandlerDescriptor[]): readonly ReactPageCatalogEntry[];
+//# sourceMappingURL=page-catalog.d.ts.map

package/dist/page-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-catalog.d.ts","sourceRoot":"","sources":["../src/page-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAK3E;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,SAAS,qBAAqB,EAAE,CA0BlC"}

package/dist/page-catalog.js

@@ -0,0 +1,46 @@
+import { createRuntimeRouteInspection } from '@fluojs/runtime/internal';
+import { getReactPathMetadata, getReactRouterMetadata } from './decorators.js';
+
+/**
+ * Immutable bootstrap-resolved description of one React page handler.
+ *
+ * @remarks
+ * The catalog is a one-way projection from authoritative compiled HTTP descriptors.
+ * Effective path, method, version, and params come from HTTP compilation rather than
+ * the static values passed to `@Router(...)` and `@Path(...)`. Catalog entries never
+ * participate in route matching, conflict detection, or dispatch.
+ */
+
+/**
+ * Creates an immutable React page catalog from compiled HTTP handler descriptors.
+ *
+ * @param descriptors Authoritative descriptors produced by `createHandlerMapping(...)`.
+ * @returns Frozen React page entries in descriptor registration order; ordinary HTTP handlers are omitted.
+ */
+export function createReactPageCatalog(descriptors) {
+  const pages = [];
+  for (const descriptor of descriptors) {
+    const routerMetadata = getReactRouterMetadata(descriptor.controllerToken);
+    const pathMetadata = getReactPathMetadata(descriptor.controllerToken, descriptor.methodName);
+    if (!routerMetadata || !pathMetadata) {
+      continue;
+    }
+    const route = createRuntimeRouteInspection(descriptor);
+    pages.push(Object.freeze({
+      handler: route.handler,
+      id: route.id,
+      kind: 'react-page',
+      method: route.method,
+      ...(route.module ? {
+        module: route.module
+      } : {}),
+      params: route.params,
+      path: route.path,
+      router: route.controller,
+      ...(route.version ? {
+        version: route.version
+      } : {})
+    }));
+  }
+  return Object.freeze(pages);
+}

package/dist/page-metadata.d.ts

@@ -0,0 +1,58 @@
+import { type ReactElement } from 'react';
+import type { ReactRenderContext } from './render.js';
+import type { ReactRenderPolicies } from './render-policy.js';
+import { type ReactRenderPolicyDecorator } from './render-policy-metadata.js';
+/** Request-scoped, response-free context supplied to page metadata factories. */
+export type ReactPageMetadataContext = {
+    readonly container: ReactRenderContext['container'];
+    readonly request: ReactRenderContext['request'];
+    readonly requestId?: ReactRenderContext['requestId'];
+};
+/** One name- or property-addressed React document meta descriptor. */
+export type ReactPageMeta = {
+    readonly content: string;
+    readonly name: string;
+    readonly property?: never;
+} | {
+    readonly content: string;
+    readonly name?: never;
+    readonly property: string;
+};
+/** One bounded React document link descriptor. */
+export type ReactPageLink = {
+    readonly href: string;
+    readonly media?: string;
+    readonly rel: string;
+    readonly type?: string;
+};
+/** Composed document-head metadata for one matched React page request. */
+export type ReactPageMetadata = {
+    readonly links?: readonly ReactPageLink[];
+    readonly meta?: readonly ReactPageMeta[];
+    readonly title?: string;
+};
+/** Synchronous request-aware factory for one React page metadata declaration. */
+export type ReactPageMetadataFactory = (context: ReactPageMetadataContext) => ReactPageMetadata;
+/**
+ * Marks a React router class or `@Path(...)` method with one page metadata factory.
+ *
+ * @param factory Synchronous request-aware factory consumed by the application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export declare function PageMetadata(factory: ReactPageMetadataFactory): ReactRenderPolicyDecorator;
+/**
+ * Resolves ordered page metadata factories for one active request.
+ *
+ * @param policies Matched page policies supplied to the application renderer.
+ * @param context Active request-scoped React render context.
+ * @returns A frozen metadata snapshot with deterministic nearest-title and descriptor replacement semantics.
+ */
+export declare function resolveReactPageMetadata(policies: ReactRenderPolicies, context: ReactRenderContext): ReactPageMetadata;
+/**
+ * Creates escaped ordinary React head elements from resolved page metadata.
+ *
+ * @param metadata Resolved metadata snapshot for one matched page request.
+ * @returns Frozen title, meta, and link elements in deterministic composition order.
+ */
+export declare function createReactPageMetadataElements(metadata: ReactPageMetadata): readonly ReactElement[];
+//# sourceMappingURL=page-metadata.d.ts.map

package/dist/page-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-metadata.d.ts","sourceRoot":"","sources":["../src/page-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,6BAA6B,CAAC;AAErC,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;CACtD,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEN,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,wBAAwB,KAC9B,iBAAiB,CAAC;AAgCvB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,0BAA0B,CAE1F;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CA8BnB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,iBAAiB,GAC1B,SAAS,YAAY,EAAE,CAgCzB"}

package/dist/page-metadata.js

@@ -0,0 +1,139 @@
+import { createElement } from 'react';
+import { createReactRenderPolicyDecorator } from './render-policy-metadata.js';
+
+/** Request-scoped, response-free context supplied to page metadata factories. */
+
+/** One name- or property-addressed React document meta descriptor. */
+
+/** One bounded React document link descriptor. */
+
+/** Composed document-head metadata for one matched React page request. */
+
+/** Synchronous request-aware factory for one React page metadata declaration. */
+
+function replaceEntry(entries, key, value) {
+  entries.delete(key);
+  entries.set(key, value);
+}
+function metaIdentity(meta) {
+  return meta.name !== undefined ? JSON.stringify(['name', meta.name]) : JSON.stringify(['property', meta.property]);
+}
+function linkIdentity(link) {
+  return JSON.stringify([link.rel, link.href]);
+}
+function cloneMeta(meta) {
+  return meta.name !== undefined ? Object.freeze({
+    content: meta.content,
+    name: meta.name
+  }) : Object.freeze({
+    content: meta.content,
+    property: meta.property
+  });
+}
+function cloneLink(link) {
+  return Object.freeze({
+    href: link.href,
+    ...(link.media === undefined ? {} : {
+      media: link.media
+    }),
+    rel: link.rel,
+    ...(link.type === undefined ? {} : {
+      type: link.type
+    })
+  });
+}
+
+/**
+ * Marks a React router class or `@Path(...)` method with one page metadata factory.
+ *
+ * @param factory Synchronous request-aware factory consumed by the application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export function PageMetadata(factory) {
+  return createReactRenderPolicyDecorator('page-metadata', factory);
+}
+
+/**
+ * Resolves ordered page metadata factories for one active request.
+ *
+ * @param policies Matched page policies supplied to the application renderer.
+ * @param context Active request-scoped React render context.
+ * @returns A frozen metadata snapshot with deterministic nearest-title and descriptor replacement semantics.
+ */
+export function resolveReactPageMetadata(policies, context) {
+  const metadataContext = Object.freeze({
+    container: context.container,
+    request: context.request,
+    ...(context.requestId === undefined ? {} : {
+      requestId: context.requestId
+    })
+  });
+  const meta = new Map();
+  const links = new Map();
+  let title;
+  for (const factory of policies.pageMetadata ?? []) {
+    const declaration = factory(metadataContext);
+    if (declaration.title !== undefined) {
+      title = declaration.title;
+    }
+    for (const descriptor of declaration.meta ?? []) {
+      const cloned = cloneMeta(descriptor);
+      replaceEntry(meta, metaIdentity(cloned), cloned);
+    }
+    for (const descriptor of declaration.links ?? []) {
+      const cloned = cloneLink(descriptor);
+      replaceEntry(links, linkIdentity(cloned), cloned);
+    }
+  }
+  return Object.freeze({
+    ...(links.size === 0 ? {} : {
+      links: Object.freeze([...links.values()])
+    }),
+    ...(meta.size === 0 ? {} : {
+      meta: Object.freeze([...meta.values()])
+    }),
+    ...(title === undefined ? {} : {
+      title
+    })
+  });
+}
+
+/**
+ * Creates escaped ordinary React head elements from resolved page metadata.
+ *
+ * @param metadata Resolved metadata snapshot for one matched page request.
+ * @returns Frozen title, meta, and link elements in deterministic composition order.
+ */
+export function createReactPageMetadataElements(metadata) {
+  const elements = [];
+  if (metadata.title !== undefined) {
+    elements.push(createElement('title', {
+      key: 'title'
+    }, metadata.title));
+  }
+  for (const meta of metadata.meta ?? []) {
+    elements.push(meta.name !== undefined ? createElement('meta', {
+      content: meta.content,
+      key: `meta:${metaIdentity(meta)}`,
+      name: meta.name
+    }) : createElement('meta', {
+      content: meta.content,
+      key: `meta:${metaIdentity(meta)}`,
+      property: meta.property
+    }));
+  }
+  for (const link of metadata.links ?? []) {
+    elements.push(createElement('link', {
+      href: link.href,
+      key: `link:${linkIdentity(link)}`,
+      ...(link.media === undefined ? {} : {
+        media: link.media
+      }),
+      rel: link.rel,
+      ...(link.type === undefined ? {} : {
+        type: link.type
+      })
+    }));
+  }
+  return Object.freeze(elements);
+}

package/dist/page-renderer.d.ts

@@ -0,0 +1,24 @@
+import type { Token } from '@fluojs/core';
+import type { ReactElement } from 'react';
+import type { ReactRenderContext } from './render.js';
+import type { ReactRenderPolicies } from './render-policy.js';
+import type { ReactServerEntry } from './server-entry.js';
+/**
+ * Application-owned page composition callback registered through `ReactModule.forRoot(...)`.
+ *
+ * @remarks
+ * The callback can wrap one page element with an application document, shared providers,
+ * request-derived client route state, hydration assets, and recoverable-error policy. It must
+ * return `ReactServerEntry` so the existing HTTP response-writer lifecycle remains authoritative.
+ * Browser and Vite helpers stay application-owned and may be composed without widening the
+ * runtime-neutral root import boundary.
+ *
+ * @param page React page element produced by an application handler.
+ * @param context Active render context containing the matched request URL, params, and response.
+ * @param policies Resolved class and method render policy component references for this page.
+ * @returns An existing React server entry finalized by the fluo HTTP dispatcher.
+ */
+export type ReactPageRenderer = (page: ReactElement, context: ReactRenderContext, policies: ReactRenderPolicies) => ReactServerEntry;
+/** Dependency-injection token for the application `ReactPageRenderer`. */
+export declare const REACT_PAGE_RENDERER: Token<ReactPageRenderer>;
+//# sourceMappingURL=page-renderer.d.ts.map

package/dist/page-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-renderer.d.ts","sourceRoot":"","sources":["../src/page-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,mBAAmB,KAC1B,gBAAgB,CAAC;AAEtB,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAA0C,CAAC"}

package/dist/page-renderer.js

@@ -0,0 +1,18 @@
+/**
+ * Application-owned page composition callback registered through `ReactModule.forRoot(...)`.
+ *
+ * @remarks
+ * The callback can wrap one page element with an application document, shared providers,
+ * request-derived client route state, hydration assets, and recoverable-error policy. It must
+ * return `ReactServerEntry` so the existing HTTP response-writer lifecycle remains authoritative.
+ * Browser and Vite helpers stay application-owned and may be composed without widening the
+ * runtime-neutral root import boundary.
+ *
+ * @param page React page element produced by an application handler.
+ * @param context Active render context containing the matched request URL, params, and response.
+ * @param policies Resolved class and method render policy component references for this page.
+ * @returns An existing React server entry finalized by the fluo HTTP dispatcher.
+ */
+
+/** Dependency-injection token for the application `ReactPageRenderer`. */
+export const REACT_PAGE_RENDERER = Symbol.for('fluo.react.page-renderer');

package/dist/page-result.d.ts

@@ -0,0 +1,16 @@
+import { type Middleware } from '@fluojs/http/portable';
+import { type ReactSsrDiagnosticHandler } from './diagnostics.js';
+import type { ReactPageRenderer } from './page-renderer.js';
+type ReactPageResultRuntime = {
+    readonly onDiagnostic?: ReactSsrDiagnosticHandler;
+    readonly renderPage?: ReactPageRenderer;
+};
+/**
+ * Creates module middleware that finalizes React page values through the HTTP response lifecycle.
+ *
+ * @param runtime Module-level renderer and diagnostic configuration.
+ * @returns Middleware that installs request-local React response state.
+ */
+export declare function createReactPageResultMiddleware(runtime: ReactPageResultRuntime): Middleware;
+export {};
+//# sourceMappingURL=page-result.d.ts.map

package/dist/page-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-result.d.ts","sourceRoot":"","sources":["../src/page-result.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAKhB,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAML,KAAK,yBAAyB,EAG/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,yBAAyB,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CACzC,CAAC;AAuGF;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU,CAgB3F"}

package/dist/page-result.js

@@ -0,0 +1,101 @@
+import { RequestAbortedError } from '@fluojs/http/portable';
+import { registerFrameworkResponseValueFinalizer } from '@fluojs/http/internal';
+import { isValidElement } from 'react';
+import { getReactPathMetadata } from './decorators.js';
+import { bindReactSsrDiagnosticHandler, createReactSsrDiagnostic, REACT_SSR_DIAGNOSTIC_CODES, REACT_SSR_DIAGNOSTIC_PHASES, ReactSsrDiagnosticError, readReactSsrDiagnosticMarker, reportReactSsrDiagnostic } from './diagnostics.js';
+import { getReactRenderPolicies } from './render-policy.js';
+import { isReactServerEntry } from './server-entry.js';
+function isRequestAborted(context) {
+  return context.request.signal?.aborted === true || context.request.isAborted?.() === true;
+}
+function reportReactPageFailure(runtime, error, context) {
+  const marker = readReactSsrDiagnosticMarker(context, error);
+  if (marker !== undefined) {
+    reportReactSsrDiagnostic(runtime.onDiagnostic, createReactSsrDiagnostic({
+      code: marker.code,
+      error,
+      phase: marker.phase,
+      request: context.request,
+      ...(context.requestId === undefined ? {} : {
+        requestId: context.requestId
+      })
+    }));
+    return;
+  }
+  if (error instanceof ReactSsrDiagnosticError) {
+    reportReactSsrDiagnostic(runtime.onDiagnostic, createReactSsrDiagnostic({
+      code: error.code,
+      error,
+      phase: error.phase,
+      request: context.request,
+      ...(context.requestId === undefined ? {} : {
+        requestId: context.requestId
+      })
+    }));
+    return;
+  }
+  if (error instanceof RequestAbortedError || isRequestAborted(context)) {
+    reportReactSsrDiagnostic(runtime.onDiagnostic, createReactSsrDiagnostic({
+      code: REACT_SSR_DIAGNOSTIC_CODES.requestAbort,
+      error,
+      phase: REACT_SSR_DIAGNOSTIC_PHASES.requestAbort,
+      request: context.request,
+      ...(context.requestId === undefined ? {} : {
+        requestId: context.requestId
+      })
+    }));
+    return;
+  }
+  if (!context.response.committed) {
+    reportReactSsrDiagnostic(runtime.onDiagnostic, createReactSsrDiagnostic({
+      code: REACT_SSR_DIAGNOSTIC_CODES.httpPipelineFailure,
+      error,
+      phase: REACT_SSR_DIAGNOSTIC_PHASES.httpPipeline,
+      request: context.request,
+      ...(context.requestId === undefined ? {} : {
+        requestId: context.requestId
+      })
+    }));
+  }
+}
+function finalizeReactPageResult(runtime, context) {
+  if (getReactPathMetadata(context.handler.controllerToken, context.handler.methodName) === undefined) {
+    return context.value;
+  }
+  if (isReactServerEntry(context.value)) {
+    return context.value;
+  }
+  if (!isValidElement(context.value)) {
+    return context.value;
+  }
+  if (runtime.renderPage === undefined) {
+    throw new ReactSsrDiagnosticError('A @Path handler returned a ReactElement, but ReactModule.forRoot(...) has no renderPage callback. ' + 'Configure renderPage or return createReactServerEntry(...) explicitly.', {
+      code: REACT_SSR_DIAGNOSTIC_CODES.missingPageRenderer,
+      phase: REACT_SSR_DIAGNOSTIC_PHASES.httpPipeline
+    });
+  }
+  const policies = getReactRenderPolicies(context.handler.controllerToken, context.handler.methodName);
+  const entry = runtime.renderPage(context.value, context.requestContext, policies);
+  return entry;
+}
+
+/**
+ * Creates module middleware that finalizes React page values through the HTTP response lifecycle.
+ *
+ * @param runtime Module-level renderer and diagnostic configuration.
+ * @returns Middleware that installs request-local React response state.
+ */
+export function createReactPageResultMiddleware(runtime) {
+  return {
+    async handle(context, next) {
+      bindReactSsrDiagnosticHandler(context.requestContext, runtime.onDiagnostic);
+      registerFrameworkResponseValueFinalizer(context.requestContext, finalizerContext => finalizeReactPageResult(runtime, finalizerContext));
+      try {
+        await next();
+      } catch (error) {
+        reportReactPageFailure(runtime, error, context.requestContext);
+        throw error;
+      }
+    }
+  };
+}

package/dist/render-diagnostics.d.ts

@@ -0,0 +1,25 @@
+import type { ReactRenderContext } from './render.js';
+import type { ReactServerEntry } from './server-entry.js';
+/** Recoverable React render error retained until the response shell can commit. */
+export type PendingReactRecoverableError = {
+    /** Original recoverable render failure. */
+    readonly error: unknown;
+    /** React-provided metadata, when available. */
+    readonly errorInfo?: unknown;
+};
+type ReactRenderDiagnostics = {
+    readonly preservePreCommitShellError: (error: unknown) => unknown;
+    readonly reportRequestAbort: () => void;
+    readonly reportRecoverableError: (event: PendingReactRecoverableError) => void;
+    readonly reportRecoverableErrors: (events: readonly PendingReactRecoverableError[]) => void;
+};
+/**
+ * Creates request-local reporting helpers for one React server entry render.
+ *
+ * @param entry React server entry whose callbacks receive recoverable errors.
+ * @param requestContext Active request and response lifecycle context.
+ * @returns Helpers that classify pre-commit failures and report recoverable errors.
+ */
+export declare function createReactRenderDiagnostics(entry: ReactServerEntry, requestContext: ReactRenderContext): ReactRenderDiagnostics;
+export {};
+//# sourceMappingURL=render-diagnostics.d.ts.map

package/dist/render-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-diagnostics.d.ts","sourceRoot":"","sources":["../src/render-diagnostics.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAgC,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExF,mFAAmF;AACnF,MAAM,MAAM,4BAA4B,GAAG;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,2BAA2B,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAClE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,IAAI,CAAC;IACxC,QAAQ,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,4BAA4B,KAAK,IAAI,CAAC;IAC/E,QAAQ,CAAC,uBAAuB,EAAE,CAAC,MAAM,EAAE,SAAS,4BAA4B,EAAE,KAAK,IAAI,CAAC;CAC7F,CAAC;AAmBF;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,kBAAkB,GACjC,sBAAsB,CAkFxB"}

package/dist/render-diagnostics.js

@@ -0,0 +1,94 @@
+import { RequestAbortedError } from '@fluojs/http/portable';
+import { createReactSsrDiagnostic, markReactSsrDiagnostic, REACT_SSR_DIAGNOSTIC_CODES, REACT_SSR_DIAGNOSTIC_PHASES, ReactSsrDiagnosticError, readReactSsrDiagnosticHandler, reportReactSsrDiagnostic } from './diagnostics.js';
+
+/** Recoverable React render error retained until the response shell can commit. */
+
+function createRecoverableErrorContext(errorInfo, requestContext) {
+  return {
+    code: REACT_SSR_DIAGNOSTIC_CODES.postShellRecoverableError,
+    ...(errorInfo !== undefined ? {
+      errorInfo
+    } : {}),
+    phase: REACT_SSR_DIAGNOSTIC_PHASES.postShellRecoverable,
+    request: requestContext.request,
+    ...(requestContext.requestId !== undefined ? {
+      requestId: requestContext.requestId
+    } : {})
+  };
+}
+function isDiagnosticMarkerKey(value) {
+  return typeof value === 'object' && value !== null || typeof value === 'function';
+}
+
+/**
+ * Creates request-local reporting helpers for one React server entry render.
+ *
+ * @param entry React server entry whose callbacks receive recoverable errors.
+ * @param requestContext Active request and response lifecycle context.
+ * @returns Helpers that classify pre-commit failures and report recoverable errors.
+ */
+export function createReactRenderDiagnostics(entry, requestContext) {
+  const reportRecoverableError = event => {
+    const recoverableContext = createRecoverableErrorContext(event.errorInfo, requestContext);
+    reportReactSsrDiagnostic(readReactSsrDiagnosticHandler(requestContext), createReactSsrDiagnostic({
+      code: recoverableContext.code,
+      error: event.error,
+      phase: recoverableContext.phase,
+      request: requestContext.request,
+      ...(requestContext.requestId === undefined ? {} : {
+        requestId: requestContext.requestId
+      })
+    }));
+    const hook = entry.onRecoverableError;
+    if (!hook) {
+      return;
+    }
+    try {
+      hook(event.error, recoverableContext);
+    } catch (error) {
+      if (error instanceof Error) {
+        return;
+      }
+    }
+  };
+  return {
+    preservePreCommitShellError(error) {
+      if (error instanceof RequestAbortedError || error instanceof ReactSsrDiagnosticError || requestContext.response.committed) {
+        return error;
+      }
+      if (!isDiagnosticMarkerKey(error)) {
+        return new ReactSsrDiagnosticError('React SSR failed before the response shell committed.', {
+          cause: error,
+          code: REACT_SSR_DIAGNOSTIC_CODES.preCommitShellFailure,
+          phase: REACT_SSR_DIAGNOSTIC_PHASES.preCommitShell
+        });
+      }
+      markReactSsrDiagnostic(requestContext, error, {
+        code: REACT_SSR_DIAGNOSTIC_CODES.preCommitShellFailure,
+        error,
+        phase: REACT_SSR_DIAGNOSTIC_PHASES.preCommitShell
+      });
+      return error;
+    },
+    reportRequestAbort() {
+      if (requestContext.request.signal?.aborted !== true && requestContext.request.isAborted?.() !== true) {
+        return;
+      }
+      reportReactSsrDiagnostic(readReactSsrDiagnosticHandler(requestContext), createReactSsrDiagnostic({
+        code: REACT_SSR_DIAGNOSTIC_CODES.requestAbort,
+        error: new RequestAbortedError(),
+        phase: REACT_SSR_DIAGNOSTIC_PHASES.requestAbort,
+        request: requestContext.request,
+        ...(requestContext.requestId === undefined ? {} : {
+          requestId: requestContext.requestId
+        })
+      }));
+    },
+    reportRecoverableError,
+    reportRecoverableErrors(events) {
+      for (const event of events) {
+        reportRecoverableError(event);
+      }
+    }
+  };
+}

package/dist/render-policy-metadata.d.ts

@@ -0,0 +1,40 @@
+import type { MetadataPropertyKey } from '@fluojs/core';
+/** Class-or-method decorator shape used by React render policy declarations. */
+export type ReactRenderPolicyDecorator = {
+    (value: Function, context: ClassDecoratorContext): void;
+    (value: Function, context: ClassMethodDecoratorContext): void;
+    (target: Function): void;
+    (target: object, propertyKey: MetadataPropertyKey, descriptor?: PropertyDescriptor): void;
+};
+/** Internal render policy record retained until bootstrap validation. */
+export type ReactRenderPolicyRecord = {
+    readonly kind: 'layout' | 'page-metadata' | 'suspense-fallback';
+    readonly reference: unknown;
+};
+/** One class or method decoration site in a router inheritance chain. */
+export type ReactRenderPolicySite = {
+    readonly kind: 'class';
+    readonly owner: Function;
+    readonly records: readonly ReactRenderPolicyRecord[];
+} | {
+    readonly kind: 'method';
+    readonly owner: Function;
+    readonly propertyKey: MetadataPropertyKey;
+    readonly records: readonly ReactRenderPolicyRecord[];
+};
+/**
+ * Creates a render policy decorator that records one component reference at a class or method site.
+ *
+ * @param kind Render policy kind being recorded.
+ * @param reference Component reference retained for bootstrap validation and renderer consumption.
+ * @returns A standard/legacy-compatible class-or-method decorator.
+ */
+export declare function createReactRenderPolicyDecorator(kind: ReactRenderPolicyRecord['kind'], reference: unknown): ReactRenderPolicyDecorator;
+/**
+ * Collects own class and method policy sites across a router inheritance chain.
+ *
+ * @param routerToken Router constructor whose inherited policy declarations should be collected.
+ * @returns Class sites followed by method sites, each ordered base-to-derived.
+ */
+export declare function getReactRenderPolicySites(routerToken: Function): readonly ReactRenderPolicySite[];
+//# sourceMappingURL=render-policy-metadata.d.ts.map

package/dist/render-policy-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-policy-metadata.d.ts","sourceRoot":"","sources":["../src/render-policy-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKxD,gFAAgF;AAChF,MAAM,MAAM,0BAA0B,GAAG;IACvC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACxD,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC9D,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,UAAU,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC3F,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,mBAAmB,CAAC;IAChE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACtD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACtD,CAAC;AAiGN;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,EACrC,SAAS,EAAE,OAAO,GACjB,0BAA0B,CAoC5B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,qBAAqB,EAAE,CAgCjG"}