@fluojs/react 0.1.0 → 0.2.0

package/dist/render.js

@@ -1,3 +1,4 @@
+import { createReactRenderDiagnostics } from './render-diagnostics.js';
 import { collectReadableStream, pipeReadableStream, throwIfReactRequestAborted } from './render-stream.js';
 const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
 
@@ -9,7 +10,7 @@ const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
 
 /** Options for rendering a React entry into one fluo response. */
 
-/** Minimal fluo request context needed to render one React HTML response. */
+/** Request-scoped fluo context available to page renderers and render policy components. */
 
 function applyEntryHeaders(entry, requestContext) {
   for (const [name, value] of Object.entries(entry.headers)) {
@@ -97,58 +98,6 @@ function createReactDomRenderOptions(options) {
     } : {})
   };
 }
-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
@@ -156,6 +105,32 @@ async function defaultRenderToReadableStream(node, options) {
   return renderToReadableStream(node, createReactDomRenderOptions(options));
 }
 
+/**
+ * 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 async function renderReactServerEntryToBytes(entry, requestContext, renderToReadableStream = defaultRenderToReadableStream) {
+  throwIfReactRequestAborted(requestContext.request);
+  let hasRenderError = false;
+  let renderError;
+  const stream = await renderToReadableStream(entry.node, createReactReadableStreamRenderOptions(entry, requestContext, error => {
+    if (!hasRenderError) {
+      hasRenderError = true;
+      renderError = error;
+    }
+  }));
+  const body = await collectReadableStream(stream, requestContext.request);
+  throwIfReactRequestAborted(requestContext.request);
+  if (hasRenderError) {
+    throw renderError;
+  }
+  return body;
+}
+
 /**
  * Renders a React server entry to one fluo HTML response using Web Streams SSR.
  *
@@ -167,35 +142,54 @@ async function defaultRenderToReadableStream(node, options) {
  * @throws RequestAbortedError before buffered responses commit when the request aborts.
  */
 export async function renderReactResponse(entry, requestContext, options = {}) {
-  throwIfReactRequestAborted(requestContext.request);
+  const diagnostics = createReactRenderDiagnostics(entry, requestContext);
   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);
+  let stream;
+  try {
+    throwIfReactRequestAborted(requestContext.request);
+    stream = await renderToReadableStream(entry.node, createReactReadableStreamRenderOptions(entry, requestContext, (error, errorInfo) => {
+      const event = errorInfo !== undefined ? {
+        error,
+        errorInfo
+      } : {
+        error
+      };
+      if (shellReady) {
+        diagnostics.reportRecoverableError(event);
+        return;
+      }
+      pendingRecoverableErrors.push(event);
+    }));
+    shellReady = true;
+    throwIfReactRequestAborted(requestContext.request);
+  } catch (error) {
+    throw diagnostics.preservePreCommitShellError(error);
+  }
   const applySuccessMetadata = () => {
     options.applySuccessResponseMetadata?.();
     applyEntryStatus(entry, requestContext);
     applyEntryHeaders(entry, requestContext);
   };
-  await writeReactStream({
-    applySuccessMetadata,
-    entry,
-    pendingRecoverableErrors,
-    requestContext,
-    stream
-  });
+  const responseStream = requestContext.response.stream;
+  if (!responseStream) {
+    let body;
+    try {
+      body = await collectReadableStream(stream, requestContext.request);
+      throwIfReactRequestAborted(requestContext.request);
+    } catch (error) {
+      throw diagnostics.preservePreCommitShellError(error);
+    }
+    applySuccessMetadata();
+    diagnostics.reportRecoverableErrors(pendingRecoverableErrors);
+    await requestContext.response.send(body);
+    return;
+  }
+  applySuccessMetadata();
+  requestContext.response.committed = true;
+  responseStream.flush?.();
+  diagnostics.reportRecoverableErrors(pendingRecoverableErrors);
+  await pipeReadableStream(stream, responseStream, requestContext.request);
+  diagnostics.reportRequestAbort();
 }

package/dist/server-entry.d.ts

@@ -1,5 +1,6 @@
-import type { FrameworkRequest } from '@fluojs/http';
+import type { FrameworkRequest } from '@fluojs/http/portable';
 import { type ReactNode } from 'react';
+import type { ReactSsrDiagnosticCode, ReactSsrDiagnosticPhase } from './diagnostics.js';
 /** 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. */
@@ -17,8 +18,12 @@ export type ReactBootstrapScriptDescriptor = {
 export type ReactBootstrapAsset = string | ReactBootstrapScriptDescriptor;
 /** Recoverable React render error details reported after the shell can stream. */
 export type ReactRecoverableErrorContext = {
+    /** Stable machine-readable diagnostic code for recoverable rendering failures. */
+    readonly code: ReactSsrDiagnosticCode;
     /** React-provided error metadata, such as a component stack, when available. */
     readonly errorInfo?: unknown;
+    /** Stable SSR lifecycle phase for recoverable rendering failures. */
+    readonly phase: ReactSsrDiagnosticPhase;
     /** Framework request being rendered. */
     readonly request: FrameworkRequest;
     /** Adapter-provided request id, when available. */
@@ -70,6 +75,13 @@ export type ReactServerEntry = {
     /** HTTP status to apply before streaming starts. Defaults to the current response status or `200`. */
     readonly status?: number;
 };
+/**
+ * Returns whether a value is a React server entry created or branded by the stable SSR seam.
+ *
+ * @param value Candidate response value.
+ * @returns Whether the value carries the React server entry brand.
+ */
+export declare function isReactServerEntry(value: unknown): value is ReactServerEntry;
 /**
  * Creates a runtime-neutral React server entry for streamed HTML rendering.
  *

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

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

package/dist/server-entry.js

@@ -1,5 +1,6 @@
+import { registerFrameworkResponseWriter } from '@fluojs/http/internal';
 import { cloneElement, isValidElement } from 'react';
-const responseWriterKey = Symbol.for('fluo.http.responseWriter');
+const serverEntryKey = Symbol.for('fluo.react.serverEntry');
 
 /** Header values applied before a React server entry starts streaming. */
 
@@ -17,6 +18,15 @@ const responseWriterKey = Symbol.for('fluo.http.responseWriter');
 
 /** Runtime-neutral React server entry rendered to streamed HTML by `renderReactResponse(...)`. */
 
+/**
+ * Returns whether a value is a React server entry created or branded by the stable SSR seam.
+ *
+ * @param value Candidate response value.
+ * @returns Whether the value carries the React server entry brand.
+ */
+export function isReactServerEntry(value) {
+  return typeof value === 'object' && value !== null && Reflect.get(value, serverEntryKey) === true;
+}
 function cloneAssetMap(assetMap) {
   const cloned = {};
   Object.setPrototypeOf(cloned, null);
@@ -111,16 +121,16 @@ export function createReactServerEntry(node, options = {}) {
       status: options.status
     } : {})
   };
-  Object.defineProperty(entry, responseWriterKey, {
+  Object.defineProperty(entry, serverEntryKey, {
     enumerable: false,
-    value: async context => {
-      const {
-        renderReactResponse
-      } = await import('./render.js');
-      await renderReactResponse(entry, context.requestContext, {
-        applySuccessResponseMetadata: context.applySuccessResponseMetadata
-      });
-    }
+    value: true
+  });
+  return registerFrameworkResponseWriter(entry, async context => {
+    const {
+      renderReactResponse
+    } = await import('./render.js');
+    await renderReactResponse(entry, context.requestContext, {
+      applySuccessResponseMetadata: context.applySuccessResponseMetadata
+    });
   });
-  return entry;
 }

package/dist/typegen-artifact.d.ts

@@ -0,0 +1,9 @@
+import type { ReactPageCatalogEntry } from './page-catalog.js';
+/**
+ * Parses the route catalog encoded in one canonical generated React page artifact.
+ *
+ * @param source Generated artifact source to inspect.
+ * @returns Parsed catalog entries, or `undefined` when the artifact body is malformed.
+ */
+export declare function parseGeneratedReactPageCatalog(source: string): readonly ReactPageCatalogEntry[] | undefined;
+//# sourceMappingURL=typegen-artifact.d.ts.map

package/dist/typegen-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen-artifact.d.ts","sourceRoot":"","sources":["../src/typegen-artifact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AA4F/D;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,qBAAqB,EAAE,GAAG,SAAS,CAiB3G"}

package/dist/typegen-artifact.js

@@ -0,0 +1,116 @@
+const JSON_STRING_SOURCE = '"(?:\\\\.|[^"\\\\])*"';
+const PATH_LINE_PATTERN = new RegExp(`^  readonly (${JSON_STRING_SOURCE}): (${JSON_STRING_SOURCE});$`, 'u');
+const PARAM_OPEN_PATTERN = new RegExp(`^  readonly (${JSON_STRING_SOURCE}): \\{$`, 'u');
+const PARAM_LINE_PATTERN = new RegExp(`^    readonly (${JSON_STRING_SOURCE}): string;$`, 'u');
+const PARAM_UNDEFINED_PATTERN = new RegExp(`^  readonly (${JSON_STRING_SOURCE}): undefined;$`, 'u');
+function parseJsonString(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === 'string' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+function readSection(lines, opening, closing) {
+  const start = lines.indexOf(opening);
+  if (start < 0) {
+    return undefined;
+  }
+  const end = lines.indexOf(closing, start + 1);
+  return end < 0 ? undefined : lines.slice(start + 1, end);
+}
+function parsePaths(lines) {
+  if (lines.includes('export type ReactPagePathById = Readonly<Record<never, never>>;')) {
+    return new Map();
+  }
+  const section = readSection(lines, 'export interface ReactPagePathById {', '}');
+  if (section === undefined || section.length === 0) {
+    return undefined;
+  }
+  const paths = new Map();
+  for (const line of section) {
+    const match = PATH_LINE_PATTERN.exec(line);
+    const id = match?.[1] === undefined ? undefined : parseJsonString(match[1]);
+    const path = match?.[2] === undefined ? undefined : parseJsonString(match[2]);
+    if (id === undefined || path === undefined || paths.has(id)) {
+      return undefined;
+    }
+    paths.set(id, path);
+  }
+  return paths;
+}
+function parseParams(lines) {
+  if (lines.includes('export type ReactPageParamsById = Readonly<Record<never, never>>;')) {
+    return new Map();
+  }
+  const section = readSection(lines, 'export interface ReactPageParamsById {', '}');
+  if (section === undefined || section.length === 0) {
+    return undefined;
+  }
+  const paramsById = new Map();
+  for (let index = 0; index < section.length; index += 1) {
+    const line = section[index] ?? '';
+    const undefinedMatch = PARAM_UNDEFINED_PATTERN.exec(line);
+    const undefinedId = undefinedMatch?.[1] === undefined ? undefined : parseJsonString(undefinedMatch[1]);
+    if (undefinedId !== undefined) {
+      if (paramsById.has(undefinedId)) {
+        return undefined;
+      }
+      paramsById.set(undefinedId, []);
+      continue;
+    }
+    const openMatch = PARAM_OPEN_PATTERN.exec(line);
+    const id = openMatch?.[1] === undefined ? undefined : parseJsonString(openMatch[1]);
+    if (id === undefined || paramsById.has(id)) {
+      return undefined;
+    }
+    const params = [];
+    index += 1;
+    while (index < section.length && section[index] !== '  };') {
+      const paramMatch = PARAM_LINE_PATTERN.exec(section[index] ?? '');
+      const param = paramMatch?.[1] === undefined ? undefined : parseJsonString(paramMatch[1]);
+      if (param === undefined) {
+        return undefined;
+      }
+      params.push(param);
+      index += 1;
+    }
+    if (section[index] !== '  };' || params.length === 0) {
+      return undefined;
+    }
+    paramsById.set(id, params);
+  }
+  return paramsById;
+}
+
+/**
+ * Parses the route catalog encoded in one canonical generated React page artifact.
+ *
+ * @param source Generated artifact source to inspect.
+ * @returns Parsed catalog entries, or `undefined` when the artifact body is malformed.
+ */
+export function parseGeneratedReactPageCatalog(source) {
+  const lines = source.replaceAll('\r\n', '\n').split('\n');
+  const paths = parsePaths(lines);
+  const paramsById = parseParams(lines);
+  if (paths === undefined || paramsById === undefined || paths.size !== paramsById.size) {
+    return undefined;
+  }
+  const catalog = [];
+  for (const [id, path] of paths) {
+    const params = paramsById.get(id);
+    if (params === undefined) {
+      return undefined;
+    }
+    catalog.push({
+      handler: '',
+      id,
+      kind: 'react-page',
+      method: 'GET',
+      params,
+      path,
+      router: ''
+    });
+  }
+  return catalog;
+}

package/dist/typegen.d.ts

@@ -0,0 +1,41 @@
+import type { ReactPageCatalogEntry } from './page-catalog.js';
+/** Current schema version embedded in generated React page type artifacts. */
+export declare const REACT_PAGE_TYPEGEN_ARTIFACT_VERSION = 1;
+/** Structural classification of an existing React page type artifact. */
+export type ReactPageTypeArtifactInspection = {
+    readonly status: 'malformed';
+} | {
+    readonly status: 'unsupported-version';
+    readonly version: number;
+} | {
+    readonly status: 'valid';
+    readonly version: number;
+};
+/** Stable diagnostic codes emitted by React page type generation. */
+export declare const REACT_PAGE_TYPEGEN_ERROR_CODES: {
+    readonly VERSIONED_ROUTE_UNSUPPORTED: "react-page-typegen-versioned-route-unsupported";
+};
+/** Diagnostic code emitted by React page type generation. */
+export type ReactPageTypegenErrorCode = (typeof REACT_PAGE_TYPEGEN_ERROR_CODES)[keyof typeof REACT_PAGE_TYPEGEN_ERROR_CODES];
+/** Typed failure raised when a catalog entry cannot be represented by path-only output. */
+export declare class ReactPageTypegenError extends Error {
+    readonly routeId: string;
+    readonly name = "ReactPageTypegenError";
+    readonly code: ReactPageTypegenErrorCode;
+    constructor(routeId: string);
+}
+/**
+ * Classifies generated React page type source before tooling compares its bytes.
+ *
+ * @param source Existing artifact source read from disk.
+ * @returns Its current, malformed, or unsupported-version structural status.
+ */
+export declare function inspectReactPageTypeArtifact(source: string): ReactPageTypeArtifactInspection;
+/**
+ * Generates path-only TypeScript route declarations and href builders from a React page catalog.
+ *
+ * @param catalog Bootstrap-resolved React page catalog entries.
+ * @returns Deterministic TypeScript source for application-owned route tooling.
+ */
+export declare function generateReactPageTypes(catalog: readonly ReactPageCatalogEntry[]): string;
+//# sourceMappingURL=typegen.d.ts.map

package/dist/typegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../src/typegen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG/D,8EAA8E;AAC9E,eAAO,MAAM,mCAAmC,IAAI,CAAC;AAMrD,yEAAyE;AACzE,MAAM,MAAM,+BAA+B,GACvC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,qEAAqE;AACrE,eAAO,MAAM,8BAA8B;;CAEjC,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,OAAO,8BAA8B,CAAC,CAAC;AAE7H,2FAA2F;AAC3F,qBAAa,qBAAsB,SAAQ,KAAK;IAIlC,QAAQ,CAAC,OAAO,EAAE,MAAM;IAHpC,QAAQ,CAAC,IAAI,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAA8D;gBAEjF,OAAO,EAAE,MAAM;CAGrC;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,+BAA+B,CAuB5F;AAqGD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GAAG,MAAM,CAqCxF"}

package/dist/typegen.js

@@ -0,0 +1,162 @@
+import { parseGeneratedReactPageCatalog } from './typegen-artifact.js';
+
+/** Current schema version embedded in generated React page type artifacts. */
+export const REACT_PAGE_TYPEGEN_ARTIFACT_VERSION = 1;
+const GENERATED_BANNER = `/* Generated by @fluojs/react/typegen. Artifact version: ${REACT_PAGE_TYPEGEN_ARTIFACT_VERSION}. Do not edit manually. */`;
+const GENERATED_FOOTER = '/* End generated @fluojs/react/typegen artifact. */';
+const GENERATED_BANNER_PATTERN = /^\/\* Generated by @fluojs\/react\/typegen\. Artifact version: (0|[1-9][0-9]{0,8})\. Do not edit manually\. \*\/\r?\n/u;
+
+/** Structural classification of an existing React page type artifact. */
+
+/** Stable diagnostic codes emitted by React page type generation. */
+export const REACT_PAGE_TYPEGEN_ERROR_CODES = {
+  VERSIONED_ROUTE_UNSUPPORTED: 'react-page-typegen-versioned-route-unsupported'
+};
+
+/** Diagnostic code emitted by React page type generation. */
+
+/** Typed failure raised when a catalog entry cannot be represented by path-only output. */
+export class ReactPageTypegenError extends Error {
+  name = 'ReactPageTypegenError';
+  code = REACT_PAGE_TYPEGEN_ERROR_CODES.VERSIONED_ROUTE_UNSUPPORTED;
+  constructor(routeId) {
+    super(`Versioned React page route "${routeId}" is unsupported by path-only typegen.`);
+    this.routeId = routeId;
+  }
+}
+
+/**
+ * Classifies generated React page type source before tooling compares its bytes.
+ *
+ * @param source Existing artifact source read from disk.
+ * @returns Its current, malformed, or unsupported-version structural status.
+ */
+export function inspectReactPageTypeArtifact(source) {
+  const match = GENERATED_BANNER_PATTERN.exec(source);
+  const rawVersion = match?.[1];
+  if (rawVersion === undefined) {
+    return {
+      status: 'malformed'
+    };
+  }
+  const version = Number(rawVersion);
+  if (version !== REACT_PAGE_TYPEGEN_ARTIFACT_VERSION) {
+    return {
+      status: 'unsupported-version',
+      version
+    };
+  }
+  const normalizedSource = source.replaceAll('\r\n', '\n');
+  const parsedCatalog = parseGeneratedReactPageCatalog(normalizedSource);
+  if (parsedCatalog === undefined || !normalizedSource.endsWith(`${GENERATED_FOOTER}\n`) || generateReactPageTypes(parsedCatalog) !== normalizedSource) {
+    return {
+      status: 'malformed'
+    };
+  }
+  return {
+    status: 'valid',
+    version
+  };
+}
+function stringLiteral(value) {
+  return JSON.stringify(value);
+}
+function renderPathMap(catalog) {
+  if (catalog.length === 0) {
+    return ['export type ReactPagePathById = Readonly<Record<never, never>>;'];
+  }
+  return ['export interface ReactPagePathById {', ...catalog.map(entry => `  readonly ${stringLiteral(entry.id)}: ${stringLiteral(entry.path)};`), '}'];
+}
+function uniqueParams(entry) {
+  return [...new Set(entry.params)];
+}
+function renderParamsMap(catalog) {
+  if (catalog.length === 0) {
+    return ['export type ReactPageParamsById = Readonly<Record<never, never>>;'];
+  }
+  const lines = ['export interface ReactPageParamsById {'];
+  for (const entry of catalog) {
+    const params = uniqueParams(entry);
+    if (params.length === 0) {
+      lines.push(`  readonly ${stringLiteral(entry.id)}: undefined;`);
+      continue;
+    }
+    lines.push(`  readonly ${stringLiteral(entry.id)}: {`);
+    lines.push(...params.map(param => `    readonly ${stringLiteral(param)}: string;`));
+    lines.push('  };');
+  }
+  lines.push('}');
+  return lines;
+}
+function renderHrefExpression(entry) {
+  const params = uniqueParams(entry);
+  if (params.length === 0) {
+    return stringLiteral(entry.path);
+  }
+  const paramNames = new Set(params);
+  const parts = entry.path.split('/').slice(1).flatMap(segment => {
+    const paramName = segment.startsWith(':') ? segment.slice(1) : undefined;
+    if (paramName !== undefined && paramNames.has(paramName)) {
+      return [stringLiteral('/'), `encodeURIComponent(params[${stringLiteral(paramName)}])`];
+    }
+    return [stringLiteral(`/${segment}`)];
+  });
+  return `[${parts.join(', ')}].join('')`;
+}
+function renderParameters(entry, leadingParameter) {
+  if (uniqueParams(entry).length === 0) {
+    return `(${leadingParameter ?? ''})`;
+  }
+  const expected = `ReactPageParamsById[${stringLiteral(entry.id)}]`;
+  const prefix = leadingParameter === undefined ? '' : `${leadingParameter}, `;
+  return `<Actual extends ${expected}>(${prefix}params: Actual & Record<Actual extends ${expected} ? Exclude<keyof Actual, keyof ${expected}> : never, never>)`;
+}
+function renderHref(entry) {
+  return `href: ${renderParameters(entry)}: string => ${renderHrefExpression(entry)}`;
+}
+function renderLink(entry) {
+  return `link: ${renderParameters(entry)}: ReactPageLinkProps => ({ href: ${renderHrefExpression(entry)} })`;
+}
+function renderNavigation(entry, operation) {
+  const parameters = renderParameters(entry, 'navigator: ReactPageNavigator');
+  return `${operation}: ${parameters}: void => navigator.${operation}(${renderHrefExpression(entry)})`;
+}
+function renderRoutes(catalog) {
+  const lines = ['export const reactPageRoutes = {'];
+  for (const entry of catalog) {
+    lines.push(`  ${stringLiteral(entry.id)}: {`);
+    lines.push(`    id: ${stringLiteral(entry.id)},`);
+    lines.push(`    path: ${stringLiteral(entry.path)},`);
+    lines.push(`    ${renderHref(entry)},`);
+    lines.push(`    ${renderLink(entry)},`);
+    lines.push(`    ${renderNavigation(entry, 'push')},`);
+    lines.push(`    ${renderNavigation(entry, 'replace')},`);
+    lines.push('  },');
+  }
+  lines.push('} as const;');
+  return lines;
+}
+
+/**
+ * Generates path-only TypeScript route declarations and href builders from a React page catalog.
+ *
+ * @param catalog Bootstrap-resolved React page catalog entries.
+ * @returns Deterministic TypeScript source for application-owned route tooling.
+ */
+export function generateReactPageTypes(catalog) {
+  for (const entry of catalog) {
+    if (entry.version !== undefined) {
+      throw new ReactPageTypegenError(entry.id);
+    }
+  }
+  const sortedCatalog = [...catalog].sort((left, right) => {
+    if (left.id < right.id) {
+      return -1;
+    }
+    if (left.id > right.id) {
+      return 1;
+    }
+    return 0;
+  });
+  return [GENERATED_BANNER, '', `export type ReactPageRouteId = ${sortedCatalog.length === 0 ? 'never' : sortedCatalog.map(entry => stringLiteral(entry.id)).join(' | ')};`, ...renderPathMap(sortedCatalog), ...renderParamsMap(sortedCatalog), 'export type ReactPagePath<RouteId extends ReactPageRouteId> = ReactPagePathById[RouteId];', 'export type ReactPageParams<RouteId extends ReactPageRouteId> = ReactPageParamsById[RouteId];', '/** Real-anchor props produced by one generated React page route. */', 'export type ReactPageLinkProps = { readonly href: string; };', '/** Minimal HTTP-first router surface consumed by generated push and replace methods. */', 'export interface ReactPageNavigator {', '  readonly push: (href: string) => void;', '  readonly replace: (href: string) => void;', '}', ...renderRoutes(sortedCatalog), 'export type ReactPageRoute = (typeof reactPageRoutes)[ReactPageRouteId];', GENERATED_FOOTER, ''].join('\n');
+}

package/package.json

@@ -8,7 +8,7 @@
     "runtime-neutral",
     "standard-decorators"
   ],
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -33,6 +33,10 @@
       "types": "./dist/experimental/rsc.d.ts",
       "import": "./dist/experimental/rsc.js"
     },
+    "./typegen": {
+      "types": "./dist/typegen.d.ts",
+      "import": "./dist/typegen.js"
+    },
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
@@ -44,10 +48,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.1.0",
-    "@fluojs/di": "^2.0.0",
-    "@fluojs/http": "^2.0.1",
-    "@fluojs/runtime": "^2.0.1"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/di": "^3.0.0",
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
@@ -56,11 +60,12 @@
   "devDependencies": {
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
     "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "pretest": "pnpm --dir ../.. --filter '@fluojs/react...' build",
     "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
     "test": "pnpm exec vitest run -c vitest.config.ts",
     "test:watch": "pnpm exec vitest -c vitest.config.ts"