@timber-js/app 0.2.0-alpha.186 → 0.2.0-alpha.187

package/src/server/ssr-entry.ts

@@ -14,10 +14,6 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-// TIM-830: Populate the search-params registry eagerly so <Link> rendered
-// during SSR can serialize flat `Partial<T>` values via registry lookup.
-// @ts-expect-error — virtual module provided by timber-routing plugin
-import 'virtual:timber-search-params-registry';
 // TIM-949: Populate the codec registry so server-rendered <Link> components
 // use codec.serialize() instead of String() fallback for URL interpolation.
 // @ts-expect-error — virtual module provided by timber-routing plugin
@@ -236,8 +232,11 @@ export async function handleSsr(
         // stage: pipeline() destroys every stage on failure, so only an
         // output kept outside the pipeline can append the noindex script
         // and close cleanly (TIM-1019).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
         const bufferedTransform = createNodeBufferedTransform();
-        const headInjector = createNodeHeadInjector(navContext.headHtml);
+        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream, {
           renderTimeoutMs,
           errorSignal: navContext._errorSignal,
@@ -296,8 +295,11 @@ export async function handleSsr(
       // HTML fragments so downstream transforms never see chunk boundaries
       // mid-tag. This prevents RSC script injection from breaking HTML
       // structure (TIM-527).
+      // Resolve the lazy segment script now that the shell is ready
+      // (AccessGates have settled, ALS deny index is authoritative).
+      const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
       let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
-      outputStream = injectHead(outputStream, navContext.headHtml);
+      outputStream = injectHead(outputStream, resolvedHeadHtml);
       outputStream = injectRscPayload(
         outputStream,
         navContext.rscStream,

package/src/server/static-generator.ts

@@ -23,6 +23,7 @@ import type { ManifestRoot, ManifestSegmentNode, ManifestFile } from './route-ma
 import { hasDynamicSegments, hasUserSitemap, resolvePathWithParams } from './sitemap-generator.js';
 import { loadModule } from './safe-load.js';
 import { METADATA_ROUTE_CONVENTIONS, resolveServePathForFile } from './metadata-routes.js';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 import {
   NOT_FOUND_ENTRY_PATH,
   NOT_FOUND_PROBE_PATH,
@@ -515,7 +516,7 @@ export async function generateStaticSite(
       // success so a transient write error doesn't orphan the flight file.
       if (htmlOk) {
         try {
-          const rscResponse = await renderUrl(handler, urlPath, 'text/x-component', timeoutMs);
+          const rscResponse = await renderUrl(handler, urlPath, RSC_CONTENT_TYPE, timeoutMs);
 
           if (rscResponse.status < 400) {
             await options.onEntry({
@@ -523,7 +524,7 @@ export async function generateStaticSite(
               status: rscResponse.status,
               headers: headersToRecord(rscResponse.headers),
               body: rscResponse.body,
-              contentType: rscResponse.headers.get('content-type') ?? 'text/x-component',
+              contentType: rscResponse.headers.get('content-type') ?? RSC_CONTENT_TYPE,
               kind: 'rsc',
             });
             summary.rendered++;

package/src/server/status-code-resolver.ts

@@ -105,16 +105,24 @@ function lookupInGroup<TFile>(
  * @param status - The HTTP status code (4xx or 5xx).
  * @param segments - The matched segment chain from root (index 0) to leaf (last).
  * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
+ * @param maxIndex - Optional upper bound on the segment index to search.
+ *   When set, the resolver only considers segments `0..maxIndex` (inclusive),
+ *   skipping any segments deeper in the tree. Used by the deny renderers to
+ *   prevent resolving a status file below a denied segment — matching
+ *   `buildDenyPageChain`'s start-at-i semantics. The error renderers omit
+ *   this parameter, so the full chain is searched — a 500 from a leaf page
+ *   should use the leaf's own `5xx.tsx`. See TIM-1358.
  */
 export function resolveStatusFile<TFile>(
   status: number,
   segments: ReadonlyArray<SegmentNode<TFile>>,
-  format: StatusFileFormat = 'component'
+  format: StatusFileFormat = 'component',
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   if (status < 400 || status > 599) return null;
-  if (format === 'json') return resolveJson(status, segments);
-  if (status <= 499) return resolve4xx(status, segments);
-  return resolve5xx(status, segments);
+  if (format === 'json') return resolveJson(status, segments, maxIndex);
+  if (status <= 499) return resolve4xx(status, segments, maxIndex);
+  return resolve5xx(status, segments, maxIndex);
 }
 
 /**
@@ -131,16 +139,19 @@ export function resolveStatusFile<TFile>(
  */
 function resolve4xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const r = lookupInGroup(segments[i].statusFiles, statusStr, '4xx', i, status);
     if (r) return r;
   }
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const errorFile = segments[i].error;
     if (errorFile) {
       return { file: errorFile, status, kind: 'error', segmentIndex: i };
@@ -159,11 +170,14 @@ function resolve4xx<TFile>(
  */
 function resolve5xx<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const segment = segments[i];
     const r = lookupInGroup(segment.statusFiles, statusStr, '5xx', i, status);
     if (r) return r;
@@ -184,12 +198,15 @@ function resolve5xx<TFile>(
  */
 function resolveJson<TFile>(
   status: number,
-  segments: ReadonlyArray<SegmentNode<TFile>>
+  segments: ReadonlyArray<SegmentNode<TFile>>,
+  maxIndex?: number
 ): StatusFileResolution<TFile> | null {
   const statusStr = String(status);
   const categoryKey = status >= 500 ? '5xx' : '4xx';
+  const start =
+    maxIndex !== undefined ? Math.min(segments.length - 1, maxIndex) : segments.length - 1;
 
-  for (let i = segments.length - 1; i >= 0; i--) {
+  for (let i = start; i >= 0; i--) {
     const r = lookupInGroup(segments[i].jsonStatusFiles, statusStr, categoryKey, i, status);
     if (r) return r;
   }

package/src/server/tree-builder.ts

@@ -12,6 +12,8 @@
 
 import type { ReactNode } from 'react';
 import type { RouteFile, SegmentNode } from '../routing/types.js';
+import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
+import type { LoadedComponent } from './utils/element-type.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -26,69 +28,6 @@ export interface LoadedModule {
 /** Function that loads a route file's module. */
 export type ModuleLoader = (file: RouteFile) => LoadedModule | Promise<LoadedModule>;
 
-/**
- * A React component reference loaded from a route module's default export.
- *
- * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
- * call sites narrow it through `isValidElementType` (below) before treating
- * it as a component. The signature is a callable returning `ReactNode` —
- * TypeScript's view of every valid React component shape, including exotic
- * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
- * callable even though their runtime values are objects with `$$typeof`
- * markers rather than functions.
- */
-export type LoadedComponent = (...args: unknown[]) => ReactNode;
-
-// Marker symbols React stamps onto exotic component types. Mirrors the
-// internal `isValidElementType` check in `react.development.js` — React
-// doesn't export it, and we don't want to add `react-is` just for this one
-// validation. Inlined the same way `isClientReference` in
-// `route-element-builder.ts` inlines the client-reference marker.
-const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
-const REACT_MEMO_TYPE = Symbol.for('react.memo');
-const REACT_LAZY_TYPE = Symbol.for('react.lazy');
-const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
-const REACT_CONTEXT_TYPE = Symbol.for('react.context');
-const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
-const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
-const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
-
-const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
-  REACT_FORWARD_REF_TYPE,
-  REACT_MEMO_TYPE,
-  REACT_LAZY_TYPE,
-  REACT_PROVIDER_TYPE,
-  REACT_CONTEXT_TYPE,
-  REACT_SUSPENSE_TYPE,
-  REACT_SUSPENSE_LIST_TYPE,
-  REACT_CLIENT_REFERENCE_TYPE,
-]);
-
-/**
- * Validate that a loaded module's `default` export is something React
- * accepts as the first argument to `createElement` — i.e. a valid component
- * type. React doesn't export `isValidElementType` (only `isValidElement`,
- * which checks for *elements*, not *component types*), so this mirrors
- * React's internal check:
- *
- *   - functions  → function or class components
- *   - objects with a `$$typeof` matching one of React's known component
- *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
- *     suspense, client references via `@vitejs/plugin-rsc`)
- *
- * Strings (HTML tag names) are valid for `createElement` but never appear
- * as a route module's default export, so they're not recognized here.
- *
- * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
- * the boundary wrapper is skipped rather than crashing inside React.
- */
-function isValidElementType(value: unknown): value is LoadedComponent {
-  if (typeof value === 'function') return true;
-  if (typeof value !== 'object' || value === null) return false;
-  const marker = (value as { $$typeof?: unknown }).$$typeof;
-  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
-}
-
 /**
  * Function that creates a React element. Matches React.createElement signature.
  *
@@ -143,22 +82,41 @@ export interface AccessGateProps {
   /** Segment name for dev logging (e.g. "authenticated", "dashboard"). */
   segmentName?: string;
   /**
-   * Pre-computed verdict from the pre-render pass. When set, AccessGate
-   * replays this verdict synchronously instead of calling accessFn.
-   * - 'pass': render children
-   * - DenySignal/RedirectSignal: throw synchronously
+   * Segment key of the gated segment (`computeSegmentKeys`). Decides whether
+   * a matched deny page renders here or is hoisted to the segment that owns
+   * it. Omitted by construction sites that build no deny chains — with no
+   * chain there is nothing to place. See TIM-1356.
    */
-  verdict?:
-    | 'pass'
-    | import('./primitives.js').DenySignal
-    | import('./primitives.js').RedirectSignal;
+  segmentKey?: string;
+  /**
+   * Index of this segment in the matched segment chain. Recorded in ALS
+   * when the gate catches a DenySignal so post-render consumers
+   * (buildSegmentInfo, X-Timber-Segments) can bound the segment list
+   * without a pre-render access pass. See TIM-1363.
+   */
+  segmentIndex?: number;
   /**
    * Deny page fallback chain. When provided and a DenySignal is caught,
    * AccessGate renders the matching deny page in-tree instead of throwing.
    * This prevents the error from reaching React Flight, eliminating the
    * second render pass. See TIM-666.
+   *
+   * Omitted for skipped segments — a deny there must hard-navigate to
+   * avoid rendering the deny page inside cached layout chrome (TIM-1074).
    */
   denyPages?: import('./deny-boundary.js').DenyPageEntry[];
+  /**
+   * When true, this gate wraps a skipped segment. On deny, the gate
+   * records the deny in ALS and rethrows so the response path can
+   * return rscErrorEnvelope for a client hard-navigate.
+   */
+  skippedSegment?: boolean;
+  /**
+   * Shell settlement callback. Called when the gate finishes (pass or
+   * deny). Tracked by shellSettled so the HTTP status is not committed
+   * before async access checks complete. See TIM-1045, TIM-1363.
+   */
+  onSettled?: () => void;
   children: ReactNode;
 }
 
@@ -192,26 +150,6 @@ export interface SlotAccessGateProps {
     | import('./primitives.js').RedirectSignal;
 }
 
-/**
- * Framework-injected error boundary wrapper.
- * Wraps content with status-code error boundary handling.
- *
- * Field types must agree with `TimberErrorBoundaryProps` in
- * `client/error-boundary.tsx`. The two are kept structurally compatible by
- * convention rather than by direct type import — tree-builder.ts is the
- * server-side construction site and may not import types from a 'use client'
- * module to keep the server barrel free of client coupling.
- */
-export interface ErrorBoundaryProps {
-  /** The component to render when an error is caught (TSX status files). */
-  fallbackComponent?: LoadedComponent;
-  /** Pre-rendered fallback element (MDX status files — see TIM-503). */
-  fallbackElement?: ReactNode;
-  /** Status code filter: 400 = any 4xx, 500 = any 5xx, specific number = exact match. */
-  status?: number;
-  children: ReactNode;
-}
-
 // ─── Tree Builder ────────────────────────────────────────────────────────────
 
 /**
@@ -272,13 +210,11 @@ export async function buildElementTree(config: TreeBuilderConfig): Promise<TreeB
     const segment = segments[i];
 
     // Wrap in error boundaries (status-code files + error.tsx)
-    element = await wrapWithErrorBoundaries(
-      segment,
-      element,
+    element = await wrapSegmentWithErrorBoundaries(segment, element, {
       loadModule,
       createElement,
-      errorBoundaryComponent
-    );
+      errorBoundaryComponent,
+    });
 
     // Wrap in AccessGate if segment has access.ts
     if (segment.access) {
@@ -355,13 +291,11 @@ async function buildSlotElement(
   let element: ReactNode = createElement(PageComponent, {});
 
   // Wrap in error boundaries
-  element = await wrapWithErrorBoundaries(
-    slotNode,
-    element,
+  element = await wrapSegmentWithErrorBoundaries(slotNode, element, {
     loadModule,
     createElement,
-    errorBoundaryComponent
-  );
+    errorBoundaryComponent,
+  });
 
   // Wrap in SlotAccessGate if slot has access.ts
   if (slotNode.access) {
@@ -387,120 +321,3 @@ async function buildSlotElement(
 
   return element;
 }
-
-// ─── Error Boundary Wrapping ─────────────────────────────────────────────────
-
-/** MDX/markdown extensions — these are server components that cannot be passed as function props. */
-const MDX_EXTENSIONS = new Set(['mdx', 'md']);
-
-/**
- * Check if a route file is an MDX/markdown file based on its extension.
- * MDX components are server components by default and cannot cross the
- * RSC→client boundary as function props. They must be pre-rendered as
- * elements and passed as fallbackElement instead of fallbackComponent.
- */
-function isMdxFile(file: RouteFile): boolean {
-  return MDX_EXTENSIONS.has(file.extension);
-}
-
-/**
- * Wrap an element with error boundaries from a segment's status-code files.
- *
- * Wrapping order (innermost to outermost):
- *   1. Specific status files (503.tsx, 429.tsx, etc.)
- *   2. Category catch-alls (4xx.tsx, 5xx.tsx)
- *   3. error.tsx (general error boundary)
- *
- * This creates the fallback chain described in design/10-error-handling.md.
- *
- * MDX status files are server components and cannot be passed as function
- * props to TimberErrorBoundary (a 'use client' component). Instead, they
- * are pre-rendered as elements and passed as fallbackElement. The error
- * boundary renders the element directly when an error is caught.
- * See TIM-503.
- */
-async function wrapWithErrorBoundaries(
-  segment: SegmentNode,
-  element: ReactNode,
-  loadModule: ModuleLoader,
-  createElement: CreateElement,
-  errorBoundaryComponent: unknown
-): Promise<ReactNode> {
-  // Wrapping is applied inside-out. The last wrap call produces the outermost boundary.
-  // Order: specific status → category → error.tsx (outermost)
-
-  if (segment.statusFiles) {
-    // Wrap with specific status files (innermost — highest priority at runtime)
-    for (const [key, file] of Object.entries(segment.statusFiles)) {
-      if (key !== '4xx' && key !== '5xx') {
-        const status = parseInt(key, 10);
-        if (!isNaN(status)) {
-          const mod = await loadModule(file);
-          // mod.default is `unknown` — narrow to a component reference.
-          // `isValidElementType` accepts memo/forwardRef objects in addition to
-          // bare functions; non-component values fall through.
-          const Component = isValidElementType(mod.default) ? mod.default : null;
-          if (Component) {
-            const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
-              ? {
-                  fallbackElement: createElement(Component, { status }),
-                  status,
-                  children: element,
-                }
-              : {
-                  fallbackComponent: Component,
-                  status,
-                  children: element,
-                };
-            element = createElement(errorBoundaryComponent, boundaryProps);
-          }
-        }
-      }
-    }
-
-    // Wrap with category catch-alls (4xx.tsx, 5xx.tsx)
-    for (const [key, file] of Object.entries(segment.statusFiles)) {
-      if (key === '4xx' || key === '5xx') {
-        const mod = await loadModule(file);
-        const Component = isValidElementType(mod.default) ? mod.default : null;
-        if (Component) {
-          const categoryStatus = key === '4xx' ? 400 : 500;
-          const boundaryProps: ErrorBoundaryProps = isMdxFile(file)
-            ? {
-                fallbackElement: createElement(Component, {}),
-                status: categoryStatus,
-                children: element,
-              }
-            : {
-                fallbackComponent: Component,
-                status: categoryStatus,
-                children: element,
-              };
-          element = createElement(errorBoundaryComponent, boundaryProps);
-        }
-      }
-    }
-  }
-
-  // Wrap with error.tsx (outermost — catches anything not matched by status files)
-  // Note: error.tsx/error.mdx receives { error, digest, reset } props.
-  // MDX error files are pre-rendered without those props (they're static content).
-  if (segment.error) {
-    const errorModule = await loadModule(segment.error);
-    const ErrorComponent = isValidElementType(errorModule.default) ? errorModule.default : null;
-    if (ErrorComponent) {
-      const boundaryProps: ErrorBoundaryProps = isMdxFile(segment.error)
-        ? {
-            fallbackElement: createElement(ErrorComponent, {}),
-            children: element,
-          }
-        : {
-            fallbackComponent: ErrorComponent,
-            children: element,
-          };
-      element = createElement(errorBoundaryComponent, boundaryProps);
-    }
-  }
-
-  return element;
-}

package/src/server/types.ts

@@ -33,21 +33,26 @@ export interface MiddlewareContext {
  * `req` is the original incoming Request; `headers` is the response-headers
  * container the framework will apply to the final Response.
  *
- * Segment params and query parameters are NOT on this context — they are
- * accessed via the same ALS-backed `.get()` accessors pages use:
+ * Segment params and query parameters are NOT on this context — they are read
+ * the same way pages read them:
  *
  * ```ts
- * // app/api/users/[id]/params.ts
- * export const segmentParams = defineSegmentParams({ id: z.coerce.number() });
+ * // app/schema.ts — every dynamic segment's codec, keyed by bracket name
+ * export default defineSchema({ segmentParams: { '[id]': z.coerce.number() } });
+ *
  * // app/api/users/[id]/route.ts
- * import { segmentParams } from './params';
+ * import { getSegmentParams } from '@timber-js/app/server';
+ * import { SEGMENT_PATH } from './$segment';
  * export async function GET() {
- *   const { id } = segmentParams.get(); // typed number — 404 on bad input
+ *   const { id } = getSegmentParams(SEGMENT_PATH); // typed number — 404 on bad input
  * }
  * ```
  *
+ * For query parameters, import a `defineSearchParams` definition and call
+ * `.get()` on it.
+ *
  * See design/07-routing.md §"RouteContext", design/23-search-params.md,
- * design/40-segment-params.md.
+ * design/41-global-params.md.
  */
 export interface RouteContext {
   req: Request;

package/src/server/utils/element-type.ts

@@ -0,0 +1,72 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+
+// Marker symbols React stamps onto exotic component types. Mirrors the
+// internal `isValidElementType` check in `react.development.js` — React
+// doesn't export it, and we don't want to add `react-is` just for this one
+// validation. Inlined the same way `isClientReference` in
+// `route-element-builder.ts` inlines the client-reference marker.
+const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
+const REACT_MEMO_TYPE = Symbol.for('react.memo');
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
+const REACT_CONTEXT_TYPE = Symbol.for('react.context');
+const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
+const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
+const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
+
+const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
+  REACT_FORWARD_REF_TYPE,
+  REACT_MEMO_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONTEXT_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_SUSPENSE_LIST_TYPE,
+  REACT_CLIENT_REFERENCE_TYPE,
+]);
+
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+export function isValidElementType(value: unknown): value is LoadedComponent {
+  if (typeof value === 'function') return true;
+  if (typeof value !== 'object' || value === null) return false;
+  const marker = (value as { $$typeof?: unknown }).$$typeof;
+  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}

package/src/shared/rsc-media-type.ts

@@ -0,0 +1,43 @@
+/**
+ * The RSC Flight media type, and the request predicate over it.
+ *
+ * One module owns the string because two independently-written spellings of
+ * "is this an RSC request?" must agree, and the consequence of them
+ * disagreeing is cache poisoning rather than a visible bug. The Cloudflare
+ * adapter's `isRsc` decides what may enter the edge cache; the origin's
+ * pipeline decides which headers may vary the response. TIM-1269 made the
+ * adapter's `VARY_HONORED` allowlist exempt `Accept` *because* `isRsc`
+ * excludes Flight responses from the cache, and exempt the `X-Timber-*`
+ * headers *because* the origin reads them only behind its own RSC check. If
+ * one predicate is ever tightened (a real media-type parse, a
+ * parameter-aware match) and the other is not, the adapter can classify a
+ * request as a document while the origin treats it as RSC, and store a
+ * Flight payload under the document's key — the class
+ * `design/48-payload-addressing.md` exists to prevent.
+ *
+ * `tests/rsc-media-type-single-source.test.ts` fails if the literal reappears
+ * in executable source outside this file.
+ *
+ * Isomorphic: zero imports, so `adapters/cloudflare.ts` — which Node's native
+ * ESM loader evaluates before Vite's resolver exists — can load it and
+ * interpolate the value into the generated worker. Same precedent as
+ * `shared/rsc-cache-key.ts`.
+ *
+ * See design/19-client-navigation.md, design/25-production-deployments.md
+ * §"`Vary` and the Workers Cache API".
+ */
+
+/** Media type of a React Flight payload. */
+export const RSC_CONTENT_TYPE = 'text/x-component';
+
+/**
+ * Is this request asking for an RSC payload rather than a full document?
+ *
+ * Substring containment, deliberately: `Accept` is a list, and a client may
+ * send `text/x-component;charset=utf-8` or list it alongside other types.
+ * Tightening this to a real media-type parse is a behaviour change that has
+ * to move the adapter's generated `isRsc` in the same commit — see above.
+ */
+export function isRscRequest(req: Request): boolean {
+  return (req.headers.get('Accept') ?? '').includes(RSC_CONTENT_TYPE);
+}