@fluojs/react 0.1.0 → 0.2.0

package/dist/render-policy-metadata.js

@@ -0,0 +1,136 @@
+import { getOwnStandardConstructorMetadataBag } from '@fluojs/core/internal';
+
+/** Class-or-method decorator shape used by React render policy declarations. */
+
+/** Internal render policy record retained until bootstrap validation. */
+
+/** One class or method decoration site in a router inheritance chain. */
+
+const reactRenderPolicyMetadataKey = Symbol.for('fluo.react.render-policy');
+const legacyClassPolicyStore = new WeakMap();
+const legacyMethodPolicyStore = new WeakMap();
+function isStandardDecoratorContext(value) {
+  return typeof value === 'object' && value !== null && Reflect.get(value, 'kind') !== undefined;
+}
+function isClassDecoratorContext(value) {
+  return isStandardDecoratorContext(value) && value.kind === 'class';
+}
+function isMethodDecoratorContext(value) {
+  return isStandardDecoratorContext(value) && value.kind === 'method';
+}
+function isMetadataPropertyKey(value) {
+  return typeof value === 'string' || typeof value === 'symbol';
+}
+function isRenderPolicyStore(value) {
+  return typeof value === 'object' && value !== null && Array.isArray(Reflect.get(value, 'classRecords')) && Reflect.get(value, 'methodRecords') instanceof Map;
+}
+function getMetadataObject(metadata) {
+  return typeof metadata === 'object' && metadata !== null ? metadata : {};
+}
+function getStandardPolicyStoreForWrite(metadata) {
+  const bag = getMetadataObject(metadata);
+  const current = Object.hasOwn(bag, reactRenderPolicyMetadataKey) ? Reflect.get(bag, reactRenderPolicyMetadataKey) : undefined;
+  if (isRenderPolicyStore(current)) {
+    return current;
+  }
+  const created = {
+    classRecords: [],
+    methodRecords: new Map()
+  };
+  Reflect.set(bag, reactRenderPolicyMetadataKey, created);
+  return created;
+}
+function appendMethodRecord(methodRecords, propertyKey, record) {
+  methodRecords.set(propertyKey, [...(methodRecords.get(propertyKey) ?? []), record]);
+}
+function getConstructorChain(routerToken) {
+  const constructors = [];
+  let current = routerToken;
+  while (typeof current === 'function' && current !== Function.prototype) {
+    constructors.unshift(current);
+    current = Object.getPrototypeOf(current);
+  }
+  return constructors;
+}
+function getOwnStandardPolicyStore(routerToken) {
+  const value = getOwnStandardConstructorMetadataBag(routerToken)?.[reactRenderPolicyMetadataKey];
+  return isRenderPolicyStore(value) ? value : undefined;
+}
+function getOwnClassPolicyRecords(routerToken) {
+  return [...(getOwnStandardPolicyStore(routerToken)?.classRecords ?? []), ...(legacyClassPolicyStore.get(routerToken) ?? [])];
+}
+function getLegacyMethodRecords(routerToken) {
+  const prototype = Reflect.get(routerToken, 'prototype');
+  return typeof prototype === 'object' && prototype !== null ? legacyMethodPolicyStore.get(prototype) : undefined;
+}
+
+/**
+ * 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 function createReactRenderPolicyDecorator(kind, reference) {
+  const record = {
+    kind,
+    reference
+  };
+  const decorator = (valueOrTarget, contextOrPropertyKey) => {
+    if (isClassDecoratorContext(contextOrPropertyKey)) {
+      getStandardPolicyStoreForWrite(contextOrPropertyKey.metadata).classRecords.push(record);
+      return;
+    }
+    if (isMethodDecoratorContext(contextOrPropertyKey)) {
+      appendMethodRecord(getStandardPolicyStoreForWrite(contextOrPropertyKey.metadata).methodRecords, contextOrPropertyKey.name, record);
+      return;
+    }
+    if (typeof valueOrTarget === 'function' && contextOrPropertyKey === undefined) {
+      legacyClassPolicyStore.set(valueOrTarget, [...(legacyClassPolicyStore.get(valueOrTarget) ?? []), record]);
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      let methodRecords = legacyMethodPolicyStore.get(valueOrTarget);
+      if (methodRecords === undefined) {
+        methodRecords = new Map();
+        legacyMethodPolicyStore.set(valueOrTarget, methodRecords);
+      }
+      appendMethodRecord(methodRecords, contextOrPropertyKey, record);
+    }
+  };
+  return decorator;
+}
+
+/**
+ * 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 function getReactRenderPolicySites(routerToken) {
+  const constructors = getConstructorChain(routerToken);
+  const classSites = [];
+  const methodSites = [];
+  for (const constructor of constructors) {
+    const classRecords = getOwnClassPolicyRecords(constructor);
+    if (classRecords.length > 0) {
+      classSites.push({
+        kind: 'class',
+        owner: constructor,
+        records: classRecords
+      });
+    }
+    const standardMethods = getOwnStandardPolicyStore(constructor)?.methodRecords;
+    const legacyMethods = getLegacyMethodRecords(constructor);
+    const propertyKeys = new Set([...(standardMethods?.keys() ?? []), ...(legacyMethods?.keys() ?? [])]);
+    for (const propertyKey of propertyKeys) {
+      methodSites.push({
+        kind: 'method',
+        owner: constructor,
+        propertyKey,
+        records: [...(standardMethods?.get(propertyKey) ?? []), ...(legacyMethods?.get(propertyKey) ?? [])]
+      });
+    }
+  }
+  return [...classSites, ...methodSites];
+}

package/dist/render-policy.d.ts

@@ -0,0 +1,87 @@
+import type { MetadataPropertyKey } from '@fluojs/core';
+import type { ComponentType, ReactNode } from 'react';
+import type { ReactPageMetadataFactory } from './page-metadata.js';
+import type { ReactRenderContext } from './render.js';
+import { type ReactRenderPolicyDecorator } from './render-policy-metadata.js';
+/** Stable bootstrap diagnostic codes for invalid React render policy declarations. */
+export declare const REACT_RENDER_POLICY_DIAGNOSTIC_CODES: {
+    readonly duplicatePageLayout: "react-render-policy-duplicate-page-layout";
+    readonly duplicatePageMetadata: "react-render-policy-duplicate-page-metadata";
+    readonly duplicateSuspenseFallback: "react-render-policy-duplicate-suspense-fallback";
+    readonly invalidReference: "react-render-policy-invalid-reference";
+    readonly invalidTarget: "react-render-policy-invalid-target";
+    readonly missingPageRenderer: "react-render-policy-missing-page-renderer";
+};
+/** Stable code attached to a React render policy bootstrap diagnostic. */
+export type ReactRenderPolicyDiagnosticCode = (typeof REACT_RENDER_POLICY_DIAGNOSTIC_CODES)[keyof typeof REACT_RENDER_POLICY_DIAGNOSTIC_CODES];
+/** Props supplied to a page layout component by an application page renderer. */
+export type ReactPageLayoutProps = {
+    /** Page or nested layout content composed at this policy level. */
+    readonly children: ReactNode;
+    /** Active request-scoped React render context. */
+    readonly context: ReactRenderContext;
+};
+/** React component reference used to compose one page layout policy. */
+export type ReactPageLayout = ComponentType<ReactPageLayoutProps>;
+/** Props supplied to an SSR Suspense fallback component by an application page renderer. */
+export type ReactSuspenseFallbackProps = {
+    /** Active request-scoped React render context. */
+    readonly context: ReactRenderContext;
+};
+/** React component reference used as an SSR Suspense fallback. */
+export type ReactSuspenseFallback = ComponentType<ReactSuspenseFallbackProps>;
+/** Resolved render policies passed to the configured application page renderer. */
+export type ReactRenderPolicies = {
+    /** Layout references ordered from outermost class policy to innermost method policy. */
+    readonly layouts: readonly ReactPageLayout[];
+    /** Page metadata factories ordered from broadest class policy to nearest method policy. */
+    readonly pageMetadata?: readonly ReactPageMetadataFactory[];
+    /** Nearest method- or class-level SSR Suspense fallback reference. */
+    readonly suspenseFallback?: ReactSuspenseFallback;
+};
+/** Typed bootstrap failure for an invalid React render policy declaration. */
+export declare class ReactRenderPolicyConfigurationError extends Error {
+    readonly name = "ReactRenderPolicyConfigurationError";
+    /** Stable machine-readable diagnostic code. */
+    readonly code: ReactRenderPolicyDiagnosticCode;
+    /** Class or class-method label that owns the invalid declaration. */
+    readonly target: string;
+    /**
+     * Creates a render policy bootstrap diagnostic.
+     *
+     * @param code Stable diagnostic code for the invalid declaration.
+     * @param target Class or class-method label that owns the declaration.
+     */
+    constructor(code: ReactRenderPolicyDiagnosticCode, target: string);
+}
+/**
+ * Marks a React router class or `@Path(...)` method with one layout component reference.
+ *
+ * @param layout Layout component reference consumed by the configured application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export declare function PageLayout(layout: ReactPageLayout): ReactRenderPolicyDecorator;
+/**
+ * Marks a React router class or `@Path(...)` method with one SSR Suspense fallback component reference.
+ *
+ * @param fallback Fallback component reference consumed by the configured application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export declare function SuspenseFallback(fallback: ReactSuspenseFallback): ReactRenderPolicyDecorator;
+/**
+ * Resolves inherited class and method render policies for one React page handler.
+ *
+ * @param routerToken React router class containing the matched page handler.
+ * @param propertyKey Matched `@Path(...)` method property key.
+ * @returns A defensive renderer-facing policy snapshot in outer-to-inner composition order.
+ */
+export declare function getReactRenderPolicies(routerToken: Function, propertyKey: MetadataPropertyKey): ReactRenderPolicies;
+/**
+ * Validates registered router policy declarations before request dispatch begins.
+ *
+ * @param routerTokens React module controller tokens inspected at bootstrap.
+ * @param hasPageRenderer Whether the module registered an application page renderer.
+ * @returns Nothing when every declaration is valid.
+ */
+export declare function validateReactRenderPolicyControllers(routerTokens: readonly Function[], hasPageRenderer: boolean): void;
+//# sourceMappingURL=render-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-policy.d.ts","sourceRoot":"","sources":["../src/render-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAGL,KAAK,0BAA0B,EAGhC,MAAM,6BAA6B,CAAC;AAErC,sFAAsF;AACtF,eAAO,MAAM,oCAAoC;;;;;;;CAOvC,CAAC;AAEX,0EAA0E;AAC1E,MAAM,MAAM,+BAA+B,GAAG,CAC5C,OAAO,oCAAoC,CAC5C,CAAC,MAAM,OAAO,oCAAoC,CAAC,CAAC;AAErD,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG;IACjC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,oBAAoB,CAAC,CAAC;AAElE,4FAA4F;AAC5F,MAAM,MAAM,0BAA0B,GAAG;IACvC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC,0BAA0B,CAAC,CAAC;AAE9E,mFAAmF;AACnF,MAAM,MAAM,mBAAmB,GAAG;IAChC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC5D,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CACnD,CAAC;AAEF,8EAA8E;AAC9E,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,SAAkB,IAAI,yCAAyC;IAE/D,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAE/C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;gBACS,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,MAAM;CAKlE;AAiHD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,0BAA0B,CAE9E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,0BAA0B,CAE5F;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,QAAQ,EACrB,WAAW,EAAE,mBAAmB,GAC/B,mBAAmB,CA2BrB;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAClD,YAAY,EAAE,SAAS,QAAQ,EAAE,EACjC,eAAe,EAAE,OAAO,GACvB,IAAI,CAoBN"}

package/dist/render-policy.js

@@ -0,0 +1,203 @@
+import { getReactPathMetadata, getReactRouterMetadata } from './decorators.js';
+import { createReactRenderPolicyDecorator, getReactRenderPolicySites } from './render-policy-metadata.js';
+
+/** Stable bootstrap diagnostic codes for invalid React render policy declarations. */
+export const REACT_RENDER_POLICY_DIAGNOSTIC_CODES = {
+  duplicatePageLayout: 'react-render-policy-duplicate-page-layout',
+  duplicatePageMetadata: 'react-render-policy-duplicate-page-metadata',
+  duplicateSuspenseFallback: 'react-render-policy-duplicate-suspense-fallback',
+  invalidReference: 'react-render-policy-invalid-reference',
+  invalidTarget: 'react-render-policy-invalid-target',
+  missingPageRenderer: 'react-render-policy-missing-page-renderer'
+};
+
+/** Stable code attached to a React render policy bootstrap diagnostic. */
+
+/** Props supplied to a page layout component by an application page renderer. */
+
+/** React component reference used to compose one page layout policy. */
+
+/** Props supplied to an SSR Suspense fallback component by an application page renderer. */
+
+/** React component reference used as an SSR Suspense fallback. */
+
+/** Resolved render policies passed to the configured application page renderer. */
+
+/** Typed bootstrap failure for an invalid React render policy declaration. */
+export class ReactRenderPolicyConfigurationError extends Error {
+  name = 'ReactRenderPolicyConfigurationError';
+
+  /** Stable machine-readable diagnostic code. */
+  code;
+
+  /** Class or class-method label that owns the invalid declaration. */
+  target;
+
+  /**
+   * Creates a render policy bootstrap diagnostic.
+   *
+   * @param code Stable diagnostic code for the invalid declaration.
+   * @param target Class or class-method label that owns the declaration.
+   */
+  constructor(code, target) {
+    super(`${code}: ${target}`);
+    this.code = code;
+    this.target = target;
+  }
+}
+function siteTarget(site) {
+  const className = site.owner.name || '<anonymous>';
+  return site.kind === 'class' ? className : `${className}.${String(site.propertyKey)}`;
+}
+function recordsForKind(records, kind) {
+  return records.filter(record => record.kind === kind);
+}
+function isPageLayoutReference(value) {
+  return typeof value === 'function';
+}
+function isPageMetadataFactory(value) {
+  return typeof value === 'function';
+}
+function isSuspenseFallbackReference(value) {
+  return typeof value === 'function';
+}
+function readPageLayout(site) {
+  const records = recordsForKind(site.records, 'layout');
+  if (records.length > 1) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.duplicatePageLayout, siteTarget(site));
+  }
+  const [record] = records;
+  if (record === undefined) {
+    return undefined;
+  }
+  const {
+    reference
+  } = record;
+  if (!isPageLayoutReference(reference)) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.invalidReference, siteTarget(site));
+  }
+  return reference;
+}
+function readPageMetadataFactory(site) {
+  const records = recordsForKind(site.records, 'page-metadata');
+  if (records.length > 1) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.duplicatePageMetadata, siteTarget(site));
+  }
+  const [record] = records;
+  if (record === undefined) {
+    return undefined;
+  }
+  const {
+    reference
+  } = record;
+  if (!isPageMetadataFactory(reference)) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.invalidReference, siteTarget(site));
+  }
+  return reference;
+}
+function readSuspenseFallback(site) {
+  const records = recordsForKind(site.records, 'suspense-fallback');
+  if (records.length > 1) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.duplicateSuspenseFallback, siteTarget(site));
+  }
+  const [record] = records;
+  if (record === undefined) {
+    return undefined;
+  }
+  const {
+    reference
+  } = record;
+  if (!isSuspenseFallbackReference(reference)) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.invalidReference, siteTarget(site));
+  }
+  return reference;
+}
+function assertValidPolicyTarget(site) {
+  const valid = site.kind === 'class' ? getReactRouterMetadata(site.owner) !== undefined : getReactPathMetadata(site.owner, site.propertyKey) !== undefined;
+  if (!valid) {
+    throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.invalidTarget, siteTarget(site));
+  }
+}
+
+/**
+ * Marks a React router class or `@Path(...)` method with one layout component reference.
+ *
+ * @param layout Layout component reference consumed by the configured application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export function PageLayout(layout) {
+  return createReactRenderPolicyDecorator('layout', layout);
+}
+
+/**
+ * Marks a React router class or `@Path(...)` method with one SSR Suspense fallback component reference.
+ *
+ * @param fallback Fallback component reference consumed by the configured application page renderer.
+ * @returns A class-or-method decorator that records render-only metadata without changing HTTP matching.
+ */
+export function SuspenseFallback(fallback) {
+  return createReactRenderPolicyDecorator('suspense-fallback', fallback);
+}
+
+/**
+ * Resolves inherited class and method render policies for one React page handler.
+ *
+ * @param routerToken React router class containing the matched page handler.
+ * @param propertyKey Matched `@Path(...)` method property key.
+ * @returns A defensive renderer-facing policy snapshot in outer-to-inner composition order.
+ */
+export function getReactRenderPolicies(routerToken, propertyKey) {
+  const sites = getReactRenderPolicySites(routerToken);
+  const relevantSites = sites.filter(site => site.kind === 'class' || site.propertyKey === propertyKey);
+  const layouts = [];
+  const pageMetadata = [];
+  let suspenseFallback;
+  for (const site of relevantSites) {
+    const layout = readPageLayout(site);
+    const metadataFactory = readPageMetadataFactory(site);
+    const fallback = readSuspenseFallback(site);
+    if (layout !== undefined) {
+      layouts.push(layout);
+    }
+    if (metadataFactory !== undefined) {
+      pageMetadata.push(metadataFactory);
+    }
+    if (fallback !== undefined) {
+      suspenseFallback = fallback;
+    }
+  }
+  return {
+    layouts,
+    ...(pageMetadata.length === 0 ? {} : {
+      pageMetadata
+    }),
+    ...(suspenseFallback === undefined ? {} : {
+      suspenseFallback
+    })
+  };
+}
+
+/**
+ * Validates registered router policy declarations before request dispatch begins.
+ *
+ * @param routerTokens React module controller tokens inspected at bootstrap.
+ * @param hasPageRenderer Whether the module registered an application page renderer.
+ * @returns Nothing when every declaration is valid.
+ */
+export function validateReactRenderPolicyControllers(routerTokens, hasPageRenderer) {
+  for (const routerToken of routerTokens) {
+    const sites = getReactRenderPolicySites(routerToken);
+    if (sites.length === 0) {
+      continue;
+    }
+    if (!hasPageRenderer) {
+      throw new ReactRenderPolicyConfigurationError(REACT_RENDER_POLICY_DIAGNOSTIC_CODES.missingPageRenderer, routerToken.name || '<anonymous>');
+    }
+    for (const site of sites) {
+      assertValidPolicyTarget(site);
+      readPageLayout(site);
+      readPageMetadataFactory(site);
+      readSuspenseFallback(site);
+    }
+  }
+}

package/dist/render-stream.d.ts

@@ -1,4 +1,4 @@
-import { type FrameworkRequest, type FrameworkResponseStream } from '@fluojs/http';
+import { type FrameworkRequest, type FrameworkResponseStream } from '@fluojs/http/portable';
 /** Minimal request abort surface used while React Web Streams are read. */
 export type ReactAbortSource = Pick<FrameworkRequest, 'isAborted' | 'signal'>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"render-stream.d.ts","sourceRoot":"","sources":["../src/render-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAOxG,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AA+B9E;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAIzE;AAyBD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAuCrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,EAAE,uBAAuB,EAC/B,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgCf"}
+{"version":3,"file":"render-stream.d.ts","sourceRoot":"","sources":["../src/render-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAuB,MAAM,uBAAuB,CAAC;AAejH,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AAuD9E;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAIzE;AAyDD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAuCrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,EAAE,uBAAuB,EAC/B,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA+Df"}

package/dist/render-stream.js

@@ -1,4 +1,4 @@
-import { RequestAbortedError } from '@fluojs/http';
+import { RequestAbortedError } from '@fluojs/http/portable';
 
 /** Minimal request abort surface used while React Web Streams are read. */
 
@@ -28,6 +28,24 @@ function createAbortWait(signal) {
     promise
   };
 }
+function createResponseCloseObserver(target) {
+  let closeObserved = target.closed;
+  let removeListener;
+  const promise = closeObserved ? Promise.resolve('closed') : target.onClose ? new Promise(resolve => {
+    removeListener = target.onClose?.(() => {
+      closeObserved = true;
+      resolve('closed');
+    }) ?? undefined;
+  }) : undefined;
+  return {
+    cleanup: () => {
+      removeListener?.();
+      removeListener = undefined;
+    },
+    isClosed: () => closeObserved || target.closed,
+    promise
+  };
+}
 function isReactRequestAborted(source) {
   return source.isAborted?.() === true || source.signal?.aborted === true;
 }
@@ -42,20 +60,39 @@ export function throwIfReactRequestAborted(source) {
     throw new RequestAbortedError();
   }
 }
-async function readNextChunk(reader, abortSource) {
+async function readNextChunk(reader, abortSource, responseClose) {
   if (isReactRequestAborted(abortSource)) {
     return 'aborted';
   }
+  if (responseClose?.isClosed()) {
+    return 'closed';
+  }
+  const stops = [];
   const abort = createAbortWait(abortSource.signal);
-  if (!abort) {
+  if (abort) {
+    stops.push(abort.promise);
+  }
+  if (responseClose?.promise) {
+    stops.push(responseClose.promise);
+  }
+  if (stops.length === 0) {
     const next = await reader.read();
-    return isReactRequestAborted(abortSource) ? 'aborted' : next;
+    if (isReactRequestAborted(abortSource)) {
+      return 'aborted';
+    }
+    return responseClose?.isClosed() ? 'closed' : next;
   }
   try {
-    const next = await Promise.race([reader.read(), abort.promise]);
-    return next === 'aborted' || isReactRequestAborted(abortSource) ? 'aborted' : next;
+    const next = await Promise.race([reader.read(), ...stops]);
+    if (next === 'aborted' || isReactRequestAborted(abortSource)) {
+      return 'aborted';
+    }
+    if (next === 'closed' || responseClose?.isClosed()) {
+      return 'closed';
+    }
+    return next;
   } finally {
-    abort.cleanup();
+    abort?.cleanup();
   }
 }
 
@@ -109,24 +146,52 @@ export async function collectReadableStream(stream, abortSource) {
  */
 export async function pipeReadableStream(stream, target, abortSource) {
   const reader = stream.getReader();
+  let responseClose;
+  let cancelPromise;
+  let sourceCompleted = false;
+  let stopped = false;
+  const cancelReaderOnce = () => {
+    cancelPromise ??= reader.cancel();
+    return cancelPromise;
+  };
   try {
-    while (!isReactRequestAborted(abortSource) && !target.closed) {
-      const next = await readNextChunk(reader, abortSource);
-      if (next === 'aborted') {
+    responseClose = createResponseCloseObserver(target);
+    while (!isReactRequestAborted(abortSource) && !responseClose.isClosed()) {
+      const next = await readNextChunk(reader, abortSource, responseClose);
+      if (next === 'aborted' || next === 'closed') {
+        stopped = true;
         break;
       }
       if (next.done) {
+        sourceCompleted = true;
         break;
       }
-      const accepted = target.write(next.value);
-      if (!accepted) {
-        await target.waitForDrain?.();
+      try {
+        const accepted = target.write(next.value);
+        if (responseClose.isClosed()) {
+          stopped = true;
+          break;
+        }
+        if (!accepted) {
+          const drain = target.waitForDrain?.();
+          if (drain) {
+            await (responseClose.promise ? Promise.race([drain, responseClose.promise]) : drain);
+          }
+          if (responseClose.isClosed()) {
+            stopped = true;
+            break;
+          }
+        }
+      } catch (error) {
+        await Promise.allSettled([cancelReaderOnce()]);
+        throw error;
       }
     }
-    if (isReactRequestAborted(abortSource)) {
-      await reader.cancel();
+    if (!sourceCompleted && (stopped || isReactRequestAborted(abortSource) || responseClose.isClosed())) {
+      await cancelReaderOnce();
     }
   } finally {
+    responseClose?.cleanup();
     reader.releaseLock();
     if (!target.closed) {
       target.close();

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import type { RequestContext } from '@fluojs/http';
+import type { RequestContext } from '@fluojs/http/portable';
 import type { ReactNode } from 'react';
 import type { ReactAssetMap, ReactBootstrapAsset, ReactServerEntry } from './server-entry.js';
 /** Readable stream returned by React's Web Streams SSR renderer. */
@@ -34,8 +34,17 @@ export type RenderReactResponseOptions = {
     /** 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'>;
+/** Request-scoped fluo context available to page renderers and render policy components. */
+export type ReactRenderContext = Pick<RequestContext, 'container' | 'request' | 'requestId' | 'response'>;
+/**
+ * Buffers a React server entry without mutating or committing a framework response.
+ *
+ * @param entry React server entry whose node and hydration assets are rendered.
+ * @param requestContext HTTP-owned request and abort surfaces.
+ * @param renderToReadableStream Optional Web Streams renderer override.
+ * @returns Complete HTML bytes after the render finishes without errors.
+ */
+export declare function renderReactServerEntryToBytes(entry: ReactServerEntry, requestContext: Pick<ReactRenderContext, 'request'>, renderToReadableStream?: ReactReadableStreamRenderer): Promise<Uint8Array>;
 /**
  * Renders a React server entry to one fluo HTML response using Web Streams SSR.
  *

package/dist/render.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EAEnB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAI3B,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,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,cAAc,EACd,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CACnD,CAAC;AA+EF;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC,EACnD,sBAAsB,GAAE,2BAA2D,GAClF,OAAO,CAAC,UAAU,CAAC,CAqBrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,gBAAgB,EACvB,cAAc,EAAE,kBAAkB,EAClC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA0Df"}