@timber-js/app 0.2.0-alpha.192 → 0.2.0-alpha.195

package/src/server/route-element-builder.ts

@@ -17,43 +17,40 @@
 
 import { createElement, Fragment } from 'react';
 
-import { withSpan } from './tracing.js';
-import type { RouteMatch } from './pipeline.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
-import type { Metadata } from './types.js';
-import { DenySignal, RedirectSignal } from './primitives.js';
-import { MetadataCollector, MetadataHead } from './metadata-collector.js';
-import { AccessGate } from './access-gate.js';
-import { requestContextAls } from './als-registry.js';
-import { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.js';
-import type { DenyPageEntry } from './deny-boundary.js';
-import { LAYOUT_CHILDREN_SLOT } from './prebuilt/slots.js';
+import { withSpan } from './tracing.ts';
+import type { RouteMatch } from './pipeline.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { Metadata } from './types.ts';
+import { DenySignal, RedirectSignal } from './primitives.ts';
+import { MetadataCollector, MetadataHead } from './metadata-collector.ts';
+import { AccessGate } from './access-gate.tsx';
+import { requestContextAls } from './als-registry.ts';
+import { PageDenyBoundary, buildDenyPageChain, handleCaughtDeny } from './deny-boundary.ts';
+import type { DenyPageEntry } from './deny-boundary.ts';
 import {
   resolveSlotProps,
   publishSlotSegmentParams,
   emitSlotInfoForSkippedLayout,
   type SlotSkipEntry,
-} from './slot-resolver.js';
-import { consumedUrlParts } from './chain-url-parts.js';
-import { withPublishedParams } from './publish-params.js';
-import type { RscPayloadRoot } from '../shared/payload-root.js';
-import { SegmentProvider } from '../client/segment-context.js';
-import { SegmentOutlet } from '../client/segment-outlet.js';
-import { SlotOutlet } from '../client/slot-outlet.js';
-import { SlotsProvider } from '../client/slot-provider.js';
-
-import { TimberErrorBoundary } from '../client/error-boundary.js';
-import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
-import type { InterceptionContext } from './pipeline.js';
-import { shouldSkipSegment, type ClientStateTree } from './state-tree-diff.js';
-import { truncateSkippableForChangedSlots } from './skippable-prefix.js';
+} from './slot-resolver.ts';
+import { consumedUrlParts } from './chain-url-parts.ts';
+import { withPublishedParams } from './publish-params.ts';
+import type { RscPayloadRoot } from '../shared/payload-root.ts';
+import { SegmentProvider } from '../client/segment-context.ts';
+import { SegmentOutlet } from '../client/segment-outlet.tsx';
+
+import { TimberErrorBoundary } from '../client/error-boundary.tsx';
+import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.ts';
+import type { InterceptionContext } from './pipeline.ts';
+import { shouldSkipSegment, type ClientStateTree } from './state-tree-diff.ts';
+import { truncateSkippableForChangedSlots } from './skippable-prefix.ts';
 import {
   computeSegmentKeys,
   computeSegmentTreePaths,
   computeSlotKey,
-} from '../routing/segment-keys.js';
-import { setFirstDeniedSegmentIndex } from './deny-boundary.js';
-import { loadModule } from './safe-load.js';
+} from '../routing/segment-keys.ts';
+import { setFirstDeniedSegmentIndex } from './deny-boundary.ts';
+import { loadModule } from './safe-load.ts';
 
 /**
  * Replace the outermost SegmentOutlet in a partial payload with its
@@ -81,6 +78,59 @@ function replaceOutermostSegmentOutlet(
   return element;
 }
 
+/**
+ * Whether a layout's returned tree still contains its children boundary.
+ *
+ * Layouts may forward `children` through a non-children prop or clone it with
+ * React.Children/cloneElement. Checking only `props.children` or object
+ * identity would incorrectly classify those layouts as suppressing their
+ * descendants and let shell settlement complete before an async child deny.
+ */
+export function containsLayoutChildren(
+  node: unknown,
+  boundaryType: React.ElementType,
+  seen = new WeakSet<object>()
+): boolean {
+  if (node == null || typeof node !== 'object') return false;
+  if (seen.has(node)) return false;
+  seen.add(node);
+  try {
+    if (Array.isArray(node)) {
+      return node.some((child) => containsLayoutChildren(child, boundaryType, seen));
+    }
+    if ('$$typeof' in node && 'type' in node && 'props' in node) {
+      if (node.type === boundaryType) return true;
+      // React's development element also exposes `_owner`; following it can
+      // walk back into the currently rendering layout's pending props and
+      // falsely "find" a child that the returned tree actually suppressed.
+      return containsLayoutChildren(node.props, boundaryType, seen);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(node);
+    return Object.values(descriptors).some(
+      (descriptor) =>
+        'value' in descriptor &&
+        descriptor.enumerable === true &&
+        containsLayoutChildren(descriptor.value, boundaryType, seen)
+    );
+  } catch {
+    // An opaque return value cannot safely prove that it retained the
+    // boundary. Treat it as suppression so an uninspectable Proxy cannot
+    // strand every descendant settlement promise and hang the response.
+    return false;
+  }
+}
+
+export function descendantSettleCallbacks(
+  callbacks: Array<() => void>,
+  layoutSettled: (() => void) | undefined
+): Array<() => void> {
+  // A tracked layout appended its own callback last; descendants are every
+  // callback before it. An untracked layout appended nothing, so all current
+  // callbacks belong to descendants. `slice(0, undefined)` is not equivalent
+  // to `slice()` — it returns an empty array.
+  return layoutSettled ? callbacks.slice(0, -1) : callbacks.slice();
+}
+
 // ─── Client Reference Detection ──────────────────────────────────────────
 
 /**
@@ -367,21 +417,27 @@ export async function buildRouteElement(
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
   // Shell settlement tracking (TIM-1045 pages, TIM-1208 layouts).
-  // SlotsProvider is 'use client', so React Flight eagerly
-  // serializes both the layout and child content as independent subtrees —
-  // the page can settle before an outer layout. We need all deny-capable
-  // components to settle before committing the HTTP status.
+  // Multiple deny-capable components can suspend independently. We need all
+  // of them to settle before committing the HTTP status.
   //
   // Each tracked component gets its own deferred. shellSettled resolves
   // when ALL settle (Promise.all) OR when any in-tree deny fires
   // (short-circuit via onDenyStatus — covers AccessGate, TracedLayout,
   // and PageDenyBoundary without threading callbacks into each).
   const shellPromises: Promise<void>[] = [];
+  const shellSettleCallbacks: Array<() => void> = [];
   let resolveShortCircuit: (() => void) | undefined;
   const trackShellComponent = (): (() => void) => {
     let resolve!: () => void;
     shellPromises.push(new Promise<void>((r) => (resolve = r)));
-    return resolve;
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    shellSettleCallbacks.push(settle);
+    return settle;
   };
 
   // Build the page element.
@@ -681,18 +737,18 @@ export async function buildRouteElement(
       const parallelRouteKeys = Object.keys(segment.slots ?? {});
 
       // Build the layout element.
-      // Layouts receive <SlotOutlet slot={LAYOUT_CHILDREN_SLOT} /> as
-      // children — a stable client reference — instead of the varying
-      // inner content. The actual child content is provided via
-      // SlotsProvider above the layout. Uses a reserved slot name to
-      // avoid collision with user-declared cache.component slots.
-      // See design/45-cache-lifetimes.md §Layout Propagation.
-      const childOutlet = h(SlotOutlet, { slot: LAYOUT_CHILDREN_SLOT });
+      // Keep the descendant tree in a SERVER layout's children prop. Moving it
+      // to a client-provider prop above that layout makes React Flight evaluate
+      // and serialize it independently, even when the layout denies access or
+      // deliberately omits children. Client layouts cannot provide this
+      // containment: Flight must serialize their server-valued children props
+      // before they execute in the browser. Convention lint warns users not to
+      // treat a client layout as an authorization or data-hiding boundary.
       let layoutElement: React.ReactElement;
       if (isClientReference(layoutComponent)) {
         layoutElement = h(layoutComponent, {
           ...slotProps,
-          children: childOutlet,
+          children: element,
         });
       } else {
         // Server component layout — wrap with OTEL tracing AND DenySignal
@@ -705,11 +761,20 @@ export async function buildRouteElement(
         const layoutDenyPages = denyPageChains.get(i);
         const hasLayoutDenyChain = !!layoutDenyPages && layoutDenyPages.length > 0;
         const onLayoutSettled = hasLayoutDenyChain ? trackShellComponent() : undefined;
+        const descendantSettlers = descendantSettleCallbacks(shellSettleCallbacks, onLayoutSettled);
+        const LayoutChildrenBoundary = ({ children }: { children: React.ReactNode }) => children;
         const TracedLayout = async (props: Record<string, unknown>) => {
           try {
-            return await withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
+            const rendered = await withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
               (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
             );
+            // A layout is allowed to suppress children. Descendant deny-capable
+            // components will never execute in that case, so settle their
+            // bookkeeping rather than leaving the RSC response waiting forever.
+            if (!containsLayoutChildren(rendered, LayoutChildrenBoundary)) {
+              for (const settle of descendantSettlers) settle();
+            }
+            return rendered;
           } catch (error: unknown) {
             // A layout that denied never renders its own chrome — it threw
             // instead of returning it — so an entry this segment owns is
@@ -728,17 +793,10 @@ export async function buildRouteElement(
         };
         layoutElement = h(TracedLayout, {
           ...slotProps,
-          children: childOutlet,
+          children: h(LayoutChildrenBoundary, { children: element }),
         });
       }
 
-      // Wrap the layout in SlotsProvider so the SlotOutlet inside the
-      // layout's children can read the actual child content.
-      layoutElement = h(SlotsProvider, {
-        values: { [LAYOUT_CHILDREN_SLOT]: element },
-        children: layoutElement,
-      });
-
       const segmentProviderElement = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,

package/src/server/route-handler.ts

@@ -8,10 +8,10 @@
  * See design/07-routing.md §"route.ts — API Endpoints"
  */
 
-import type { RouteContext } from './types.js';
-import { logRouteError } from './logger.js';
-import { DenySignal, RedirectSignal } from './primitives.js';
-import { stripHeadBody } from './head-response.js';
+import type { RouteContext } from './types.ts';
+import { logRouteError } from './logger.ts';
+import { DenySignal, RedirectSignal } from './primitives.ts';
+import { stripHeadBody } from './head-response.ts';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/server/route-matcher.ts

@@ -8,17 +8,17 @@
  * See design/07-routing.md §"Request Lifecycle"
  */
 
-import type { RouteMatch } from './pipeline.js';
-import type { MiddlewareFn } from './middleware-runner.js';
-import type { SegmentNode, RouteTree } from '../routing/types.js';
+import type { RouteMatch } from './pipeline.ts';
+import type { MiddlewareFn } from './middleware-runner.ts';
+import type { SegmentNode, RouteTree } from '../routing/types.ts';
 import {
   METADATA_ROUTE_CONVENTIONS,
   isStaticMetadataExtension,
   resolveStaticContentType,
   resolveServePathForFile,
   type MetadataRouteType,
-} from './metadata-routes.js';
-import { matchUrlParts } from './tree-match.js';
+} from './metadata-routes.ts';
+import { matchUrlParts } from './tree-match.ts';
 
 // ─── Manifest Types ───────────────────────────────────────────────────────
 //

package/src/server/rsc-cache-key-guard.ts

@@ -25,8 +25,8 @@
  * See design/19-client-navigation.md §"The `_rsc` cache key".
  */
 
-import { rscCacheKey, isRscCacheKeyShape, RSC_KEY_PARAM } from '../shared/rsc-cache-key.js';
-import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+import { rscCacheKey, isRscCacheKeyShape, RSC_KEY_PARAM } from '../shared/rsc-cache-key.ts';
+import { isRscContentType } from '../shared/rsc-media-type.ts';
 
 /**
  * Legacy shared-cache control fields that predate RFC 9213 and so do not
@@ -122,9 +122,7 @@ export async function hasValidRscCacheKey(req: Request): Promise<boolean> {
  * #36c.
  */
 export function hardenRscPayloadResponse(response: Response): void {
-  const contentType = response.headers.get('content-type');
-  if (!contentType) return;
-  if (contentType.split(';')[0].trim().toLowerCase() !== RSC_CONTENT_TYPE) return;
+  if (!isRscContentType(response.headers.get('content-type'))) return;
   response.headers.set('X-Content-Type-Options', 'nosniff');
 }
 

package/src/server/rsc-entry/action-middleware-runner.ts

@@ -18,18 +18,18 @@
  * this in try/catch.
  */
 
-import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.js';
+import { getCookiesForSsr, getSetCookieHeaders } from '../cookie-context.ts';
 import {
   applyRequestHeaderOverlay,
   runWithRequestContext,
   setMutableCookieContext,
   setSegmentParams,
-} from '../request-context.js';
-import { runMiddlewareChain } from '../middleware-runner.js';
-import { DenySignal, RedirectSignal } from '../primitives.js';
-import { ParamCoercionError } from '../route-element-builder.js';
-import type { RouteMatch } from '../pipeline.js';
-import type { MiddlewareContext } from '../types.js';
+} from '../request-context.ts';
+import { runMiddlewareChain } from '../middleware-runner.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { ParamCoercionError } from '../route-element-builder.ts';
+import type { RouteMatch } from '../pipeline.ts';
+import type { MiddlewareContext } from '../types.ts';
 
 /** Coerce a matched route's segment params via its `params.ts` codecs. */
 export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<void>;

package/src/server/rsc-entry/api-handler.ts

@@ -6,14 +6,15 @@
  * See design/04-authorization.md §"Auth in API Routes".
  */
 
-import { withSpan, setSpanAttribute } from '../tracing.js';
-import type { ManifestSegmentNode } from '../route-matcher.js';
-import { loadModule } from '../safe-load.js';
-import { DenySignal, RedirectSignal } from '../primitives.js';
-import { handleRouteRequest } from '../route-handler.js';
-import { stripHeadBody } from '../head-response.js';
-import type { RouteModule } from '../route-handler.js';
-import type { RouteContext } from '../types.js';
+import { withSpan, setSpanAttribute } from '../tracing.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { loadModule } from '../safe-load.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { handleRouteRequest } from '../route-handler.ts';
+import { stripHeadBody } from '../head-response.ts';
+import { isDebug } from '../debug.ts';
+import type { RouteModule } from '../route-handler.ts';
+import type { RouteContext } from '../types.ts';
 
 /**
  * Handle a `route.ts` request.
@@ -125,10 +126,18 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveStatusFile } = await import('../status-code-resolver.js');
+  const { resolveStatusFile } = await import('../status-code-resolver.ts');
 
   const resolution = resolveStatusFile(deny.status, segments, 'json');
   if (resolution) {
+    if (isDebug() && deny.data !== undefined) {
+      console.warn(
+        `[timber] deny(${deny.status}, data) resolved to ${resolution.file.filePath}, ` +
+          `which is a static JSON file. The data argument is dropped — JSON status files ` +
+          `are returned verbatim with no interpolation. If you need the data in the ` +
+          `response, use a route handler (route.ts) that returns Response.json() directly.`
+      );
+    }
     const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;
     responseHeaders.set('content-type', 'application/json; charset=utf-8');

package/src/server/rsc-entry/deny-fallback.ts

@@ -10,16 +10,16 @@
  * Design docs: 04-authorization.md, 10-error-handling.md
  */
 
-import type { LayoutEntry } from '../deny-renderer.js';
-import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
-import type { ClientBootstrapConfig } from '../html-injectors.js';
-import { logRenderError } from '../logger.js';
-import type { PipelineConfig, RouteMatch } from '../pipeline.js';
-import type { ManifestSegmentNode } from '../route-matcher.js';
-import { loadModule } from '../safe-load.js';
-import { createDebugChannelSink } from './helpers.js';
-import { isRscRequest } from '../../shared/rsc-media-type.js';
-import { callSsr } from './ssr-bridge.js';
+import type { LayoutEntry } from '../deny-renderer.ts';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { logRenderError } from '../logger.ts';
+import type { PipelineConfig, RouteMatch } from '../pipeline.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { loadModule } from '../safe-load.ts';
+import { createDebugChannelSink } from './helpers.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { callSsr } from './ssr-bridge.ts';
 
 /**
  * Create the pipeline's deny fallback renderer.

package/src/server/rsc-entry/error-renderer.ts

@@ -13,33 +13,33 @@
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '../../rsc-runtime/rsc.js';
-
-import type { RouteMatch } from '../pipeline.js';
-import { logRenderError } from '../logger.js';
-import { appVisibleSearch } from '../../shared/rsc-cache-key.js';
-import { getSlotParamsForClient } from '../request-context.js';
-import type { ManifestSegmentNode } from '../route-matcher.js';
-import { DenySignal, RenderError } from '../primitives.js';
-import type { ClientBootstrapConfig } from '../html-injectors.js';
-import { flightInitScript, htmlEscapeJsonString } from '../flight-scripts.js';
-import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
-import type { DefaultPageRenderer, LayoutEntry } from '../deny-renderer.js';
-import type { NavContext } from '../ssr-bridge-types.js';
-import { createDebugChannelSink } from './helpers.js';
-import { isRscRequest } from '../../shared/rsc-media-type.js';
-import { withPublishedParams } from '../publish-params.js';
-import { getCookiesForSsr } from '../cookie-context.js';
-import { callSsr } from './ssr-bridge.js';
-import { teeWithErrorPropagation } from '../stream-utils.js';
-import { isDevMode } from '../debug.js';
-import { ErrorReconstituter } from '../../client/error-reconstituter.js';
-import type { SerializableError } from '../../client/error-reconstituter.js';
-import { loadModule } from '../safe-load.js';
-import { sourceMapError } from '../dev-source-map.js';
-import { isMdxFilePath as isMdxFile } from '../utils/mdx-file.js';
-import { defaultStatusPageResponse } from '../default-status-page.js';
-import { rscErrorEnvelope } from '../../shared/rsc-error-envelope.js';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.ts';
+
+import type { RouteMatch } from '../pipeline.ts';
+import { logRenderError } from '../logger.ts';
+import { appVisibleSearch } from '../../shared/rsc-cache-key.ts';
+import { getSlotParamsForClient } from '../request-context.ts';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { DenySignal, RenderError } from '../primitives.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import { flightInitScript, htmlEscapeJsonString } from '../flight-scripts.ts';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.ts';
+import type { DefaultPageRenderer, LayoutEntry } from '../deny-renderer.ts';
+import type { NavContext } from '../ssr-bridge-types.ts';
+import { createDebugChannelSink } from './helpers.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { withPublishedParams } from '../publish-params.ts';
+import { getCookiesForSsr } from '../cookie-context.ts';
+import { callSsr } from './ssr-bridge.ts';
+import { teeWithErrorPropagation } from '../stream-utils.ts';
+import { isDevMode } from '../debug.ts';
+import { ErrorReconstituter } from '../../client/error-reconstituter.tsx';
+import type { SerializableError } from '../../client/error-reconstituter.tsx';
+import { loadModule } from '../safe-load.ts';
+import { sourceMapError } from '../dev-source-map.ts';
+import { isMdxFilePath as isMdxFile } from '../utils/mdx-file.ts';
+import { defaultStatusPageResponse } from '../default-status-page.ts';
+import { rscErrorEnvelope } from '../../shared/rsc-error-envelope.ts';
 
 /**
  * A manifest file reference with lazy import and path.

package/src/server/rsc-entry/helpers.ts

@@ -4,13 +4,13 @@
  * Small, stateless functions used across the RSC entry modules.
  */
 
-import type { ManifestSegmentNode } from '../route-matcher.js';
-import { swallow } from '../logger.js';
-import { computeSegmentKeys, computeSegmentTreePaths } from '../../routing/segment-keys.js';
-import type { SegmentInfo } from '../../shared/segment-info.js';
-import type { SlotSkipEntry } from '../slot-resolver.js';
-import { isClientReference } from '../route-element-builder.js';
-import { isStaticRequestDependent } from '../request-dep.js';
+import type { ManifestSegmentNode } from '../route-matcher.ts';
+import { swallow } from '../logger.ts';
+import { computeSegmentKeys, computeSegmentTreePaths } from '../../routing/segment-keys.ts';
+import type { SegmentInfo } from '../../shared/segment-info.ts';
+import type { SlotSkipEntry } from '../slot-resolver.ts';
+import { isClientReference } from '../route-element-builder.ts';
+import { isStaticRequestDependent } from '../request-dep.ts';
 
 /**
  * Create a debug channel sink that discards all debug data.
@@ -263,11 +263,11 @@ export function buildSegmentInfo(
 // Callers within rsc-entry/ import from this file; the implementations
 // live in pipeline-helpers.ts (buildRedirectResponse) and render-utils.ts
 // (isAbortError). See TIM-1071 item 1.
-export { buildRedirectResponse } from '../pipeline-helpers.js';
-export { isAbortError } from '../render-utils.js';
+export { buildRedirectResponse } from '../pipeline-helpers.ts';
+export { isAbortError } from '../render-utils.ts';
 
 // escapeHtml is now imported from server/utils/escape-html.ts
-export { escapeHtml } from '../utils/escape-html.js';
+export { escapeHtml } from '../utils/escape-html.ts';
 
 // Params no longer travel beside the payload. The payload root is the
 // outermost node of every tree the server sends (`server/publish-params.ts`),