@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/server/prebuilt/capture-routes.ts

@@ -0,0 +1,104 @@
+/**
+ * Candidate routes for the post-build capture pass
+ * (server/prebuilt-builder.ts, design/44-render-at-build-time.md §Build
+ * Phase): which pages carry prebuilt components, and which param combos
+ * to capture them for.
+ */
+
+import type { CoercedParams } from '../../shared/param-value.ts';
+import type { ManifestFile, ManifestSegmentNode } from '../route-matcher.ts';
+import { hasDynamicSegments } from '../sitemap-generator.ts';
+
+// ─── Route collection ─────────────────────────────────────────────────────
+
+export interface CandidateRoute {
+  urlPath: string;
+  page: ManifestFile;
+  /** Layout files along the chain that declare prebuilt components. */
+  layoutsToLoad: ManifestFile[];
+  /** Component IDs attributed to this route's page + layout chain. */
+  componentIds: string[];
+  /** Component IDs from layout files (receive SlotOutlet as children). */
+  layoutComponentIds: Set<string>;
+}
+
+/**
+ * Walk the manifest tree and collect pages whose file chain (page +
+ * layouts above it) has prebuilt components attributed to it. Slots and
+ * intercepting/private segments are not walked — slot-scoped prebuilt is
+ * already unkeyable at request time when slot params diverge (see
+ * resolveKeyParams in prebuilt-runtime.ts), so the build doesn't model
+ * slots either.
+ */
+export function collectCandidateRoutes(
+  root: ManifestSegmentNode,
+  fileComponentMap: Record<string, string[]>
+): CandidateRoute[] {
+  const routes: CandidateRoute[] = [];
+
+  const walk = (node: ManifestSegmentNode, layoutChain: ManifestFile[]) => {
+    if (node.segmentType === 'intercepting' || node.segmentType === 'private') return;
+    const chain = node.layout ? [...layoutChain, node.layout] : layoutChain;
+
+    if (node.page) {
+      const componentIds = new Set<string>();
+      const layoutIds = new Set<string>();
+      for (const f of chain)
+        for (const id of fileComponentMap[f.filePath] ?? []) {
+          componentIds.add(id);
+          layoutIds.add(id);
+        }
+      for (const id of fileComponentMap[node.page.filePath] ?? []) componentIds.add(id);
+      if (componentIds.size > 0) {
+        routes.push({
+          urlPath: node.urlPath,
+          page: node.page,
+          layoutsToLoad: chain.filter((l) => (fileComponentMap[l.filePath] ?? []).length > 0),
+          componentIds: Array.from(componentIds),
+          layoutComponentIds: layoutIds,
+        });
+      }
+    }
+
+    for (const child of node.children) walk(child, chain);
+  };
+
+  walk(root, []);
+  return routes;
+}
+
+// ─── Param enumeration ────────────────────────────────────────────────────
+
+export type ParamCombo = CoercedParams;
+
+/**
+ * Resolve the param combos to capture for a route. Static routes have
+ * exactly one combo (the empty record) — `export const prerender`-style
+ * components on static pages need no enumerator. Dynamic routes require
+ * `generateStaticSegmentParams` (design/44 §generateStaticSegmentParams);
+ * without it every request renders live and the wrapper is a no-op.
+ */
+export async function enumerateCombos(
+  route: CandidateRoute,
+  pageModule: Record<string, unknown>,
+  log: (message: string) => void
+): Promise<ParamCombo[] | null> {
+  if (!hasDynamicSegments(route.urlPath)) return [{}];
+
+  const generateFn = pageModule.generateStaticSegmentParams;
+  if (typeof generateFn !== 'function') {
+    log(
+      `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +
+        `generateStaticSegmentParams export — all its entries will render dynamically ` +
+        `until the page declares its param combos`
+    );
+    return null;
+  }
+  const combos: unknown = await (generateFn as () => unknown)();
+  if (!Array.isArray(combos)) {
+    throw new Error(
+      `generateStaticSegmentParams must return an array of param records, got ${typeof combos}`
+    );
+  }
+  return combos as ParamCombo[];
+}

package/src/server/prebuilt/capture-state.ts

@@ -1,89 +1,196 @@
 /**
- * Build-time capture state — the channel between the post-build capture
- * pass (server/prebuilt-builder.ts) and the `__prebuilt` wrapper
- * (server/prebuilt-runtime.ts).
+ * Capture state — the channel between a payload capture and the
+ * `__prebuilt` wrappers that render inside it (server/prebuilt-runtime.ts).
  *
- * During capture, a wrapped component's subtree may render OTHER wrapped
- * components. With no payload source registered (the capture pass runs
- * before artifacts exist), those inner wrappers render live and their
- * output is baked flat into the outer entry — the nesting clamp of
- * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The capture
- * pass is the designated detection point for that clamp, so the wrapper
- * reports every render that happens while a capture is active:
+ * Two callers capture a wrapped component's flight payload:
  *
- * - **Cycle**: the inner wrapper IS the component being captured (directly
- *   or transitively — the transitive case still renders the outer's own
- *   wrapper, so the identity check catches both). Left alone this recurses
+ * - **Build time**: the post-build capture pass (server/prebuilt-builder.ts)
+ *   renders each registry entry in turn.
+ * - **Request time**: `captureComponentPayload()` in prebuilt-runtime.ts
+ *   renders a component in isolation for an inline re-render (full miss,
+ *   stale entry, tombstone) or an SWR background re-render. These run
+ *   concurrently with other requests' renders — and with each other.
+ *
+ * During a capture, the component's subtree may render OTHER wrapped
+ * components. Those inner wrappers render live and their output is baked
+ * flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The wrapper
+ * reports every render that happens inside a capture:
+ *
+ * - **Cycle**: the inner render IS the entry being captured — same
+ *   component id AND same props key (TIM-1547). Left alone this recurses
  *   until the render times out; instead the wrapper throws
  *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
- *   the cycle while the build continues (doc 44 skip-and-report policy).
- * - **Nesting**: any other wrapper render is recorded as an (outer, inner)
- *   pair. The builder warns after the entry completes when the inner
- *   declares a refresh channel the outer cannot honor (doc 45 clamp rule).
+ *   the cycle (build continues per doc 44 skip-and-report policy; at
+ *   request time the re-render fails and is not cached, and the wrapper
+ *   falls back as for any failed re-render). A component that renders
+ *   itself with different props (a comment thread, a tree) is legitimate
+ *   recursion with a base case and bakes flat like any other nesting.
+ * - **Nesting**: any other wrapper render is recorded per inner component
+ *   with the tags it resolved to. Both capture callers run the clamp rule
+ *   over those records when the entry completes (prebuilt/lifetime.ts).
+ *
+ * Identity is the capture ROOT only. A wrapper cannot see the wrappers
+ * between it and the root: Flight renders a component's children after
+ * the wrapper has returned, in Flight's own async context, not in a frame
+ * the wrapper could enter. So a same-key cycle that closes below the root
+ * (`A(p1) → A(p2) → A(p2) → …`) is not detected here; it is also an
+ * infinite recursion without caching, and the capture's render timeout
+ * fails it.
  *
- * Captures run strictly sequentially (one entry at a time), so a single
- * module-level slot is sufficient — there is never a second active capture
- * to confuse renders between. At request time `active` is null and
- * `noteWrapperRender` is a single null-check.
+ * The props key is the props half of the cache key (data props only,
+ * framework children outlet stripped — the same inputs the cache key
+ * hashes). The params half is left out: every render inside one capture
+ * reads the same segment params, so props decide identity. Unkeyable props
+ * (live React elements, …) cannot be proven identical and are never a
+ * cycle.
+ *
+ * Each capture's state lives in an AsyncLocalStorage store entered by
+ * `CaptureScope.run()`, so it is visible only to renders started inside
+ * that capture — including work Flight resumes after an await, which runs
+ * in the context the awaited promise was created in. A concurrent request
+ * rendering the same component is not a cycle, and a concurrent request
+ * rendering a different cached component still revives it from cache
+ * instead of baking it live (TIM-1536). Outside any capture
+ * `noteWrapperRender` is a single store lookup.
  */
 
+import {
+  prebuiltCaptureAls,
+  requestContextAls,
+  type PrebuiltCaptureStore,
+} from '../als-registry.ts';
 import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+import { computeComponentCacheKey, splitSlotProps } from './cache-key.ts';
+import { resolveTags } from './lifetime.ts';
+import { withoutChildrenOutlet } from './slots.ts';
 
 /** A wrapped component that rendered inside an active capture. */
 export interface NestedWrapperRender {
   innerId: string;
   options: PrebuiltComponentOptions;
+  /**
+   * Every tag the inner resolved to across its renders in this capture;
+   * null when its tags function threw (the tags are unknown).
+   */
+  tags: string[] | null;
+}
+
+/** Per-inner record kept while the capture runs. */
+export interface NestedRecord {
+  options: PrebuiltComponentOptions;
+  tags: Set<string> | null;
 }
 
-/** Thrown by the wrapper when a capture renders its own component. */
+/** Thrown by the wrapper when a capture renders its own entry. */
 export class PrebuiltCaptureCycleError extends Error {
   constructor(componentId: string) {
     super(
-      `[timber] cache.component "${componentId}" renders itself (directly or through ` +
-        `other components) — prerendering it would recurse forever. Remove the cycle ` +
-        `or drop { prerender: true } on this component.`
+      `[timber] cache.component "${componentId}" renders itself with the same props ` +
+        `(directly or through other components) — capturing its payload would recurse ` +
+        `forever. Remove the cycle or stop caching this component with cache.component.`
     );
     this.name = 'PrebuiltCaptureCycleError';
   }
 }
 
-let active: { outerId: string; nested: Map<string, PrebuiltComponentOptions> } | null = null;
+/** One capture's state, entered for the duration of its render. */
+export interface CaptureScope {
+  /**
+   * Run `fn` inside this capture. Flight renders in the async context it
+   * was started (and pinged) from, so the render must be CREATED inside
+   * `run`; every wrapper it renders then sees this capture.
+   */
+  run<T>(fn: () => T): T;
+  /** Wrapped components that rendered inside this capture so far. */
+  nestedRenders(): NestedWrapperRender[];
+}
 
 /**
- * Mark a capture as active. The builder calls this immediately before
- * rendering an entry and MUST pair it with `endCapture()` in a finally.
+ * The props half of a render's cache key, or null when unkeyable. Same
+ * inputs `tryRevivePayload` hashes: data props only for slot components,
+ * the framework-injected children outlet stripped.
  */
-export function beginCapture(outerId: string): void {
-  active = { outerId, nested: new Map() };
+function propsKey(
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): string | null {
+  let keyProps = props;
+  if (options.slots && options.slots.length > 0) {
+    const split = splitSlotProps(props, options.slots);
+    if (split === null) return null;
+    keyProps = split.dataProps;
+  }
+  return computeComponentCacheKey(withoutChildrenOutlet(keyProps), {});
 }
 
 /**
- * End the active capture and return the wrapped components that rendered
- * inside it (first options object wins per inner ID).
+ * Open a capture of component `outerId` rendered with `props`. Its state
+ * ends with the scope object.
  */
-export function endCapture(): NestedWrapperRender[] {
-  const nested = active?.nested;
-  active = null;
-  if (!nested) return [];
-  return Array.from(nested, ([innerId, options]) => ({ innerId, options }));
+export function createCaptureScope(
+  outerId: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): CaptureScope {
+  const store: PrebuiltCaptureStore = {
+    outerId,
+    outerPropsKey: propsKey(options, props),
+    nested: new Map(),
+  };
+  return {
+    run: (fn) => prebuiltCaptureAls.run(store, fn),
+    nestedRenders: () =>
+      Array.from(store.nested, ([innerId, record]) => ({
+        innerId,
+        options: record.options,
+        tags: record.tags && Array.from(record.tags),
+      })),
+  };
 }
 
-/** Whether a build-time capture is currently rendering. */
+/** Whether the current render is inside a capture. */
 export function isCaptureActive(): boolean {
-  return active !== null;
+  return prebuiltCaptureAls.getStore() !== undefined;
 }
 
 /**
- * Called by the `__prebuilt` wrapper on every render. No-op unless a
- * capture is active. Throws `PrebuiltCaptureCycleError` when the wrapper
- * belongs to the component currently being captured.
+ * Called by the `__prebuilt` wrapper on every render. No-op outside a
+ * capture. Throws `PrebuiltCaptureCycleError` when the render is the
+ * entry the enclosing capture is producing.
  */
-export function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions): void {
-  if (active === null) return;
-  if (innerId === active.outerId) {
-    throw new PrebuiltCaptureCycleError(innerId);
+export function noteWrapperRender(
+  innerId: string,
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): void {
+  const capture = prebuiltCaptureAls.getStore();
+  if (capture === undefined) return;
+  if (innerId === capture.outerId && capture.outerPropsKey !== null) {
+    if (propsKey(options, props) === capture.outerPropsKey) {
+      throw new PrebuiltCaptureCycleError(innerId);
+    }
+  }
+  let record = capture.nested.get(innerId);
+  if (record === undefined) {
+    record = { options, tags: new Set() };
+    capture.nested.set(innerId, record);
   }
-  if (!active.nested.has(innerId)) {
-    active.nested.set(innerId, options);
+  if (record.tags !== null && options.tags) {
+    // A diagnostic must not change the capture. The tags function is user
+    // code, so it runs with the request context exited: a read of
+    // segment params, headers, or cookies inside it must not be charged
+    // to the OUTER entry (a build-time context violation, a lost
+    // param-independence proof, a key-discipline report). A tags function
+    // that throws — including because it needed that context — leaves the
+    // inner's tags unknown, which the clamp rule treats as not covered by
+    // the outer; the warning says so. The throw itself is not reported
+    // here: it belongs to the inner, which may never be cached on its own.
+    const tags = record.tags;
+    try {
+      for (const tag of requestContextAls.exit(() => resolveTags(options, props))) tags.add(tag);
+    } catch {
+      record.tags = null;
+    }
   }
 }

package/src/server/prebuilt/lifetime.ts

@@ -0,0 +1,151 @@
+/**
+ * Lifetime declarations of a `cache.component` — `prerender`, `ttl`,
+ * `tags` (design/45-cache-lifetimes.md) — and the nesting clamp between
+ * two of them (§Nesting Semantics, TIM-1136).
+ *
+ * The clamp rule lives here once, for both places a capture can embed one
+ * wrapped component in another: the post-build capture pass
+ * (server/prebuilt-builder.ts) and request-time re-renders
+ * (`captureComponentPayload()` in server/prebuilt-runtime.ts, TIM-1545).
+ */
+
+import { splitSlotProps } from './cache-key.ts';
+import type { NestedWrapperRender } from './capture-state.ts';
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+
+/** Whether the component has a runtime lifetime (ttl or tags). */
+export function hasRuntimeLifetime(options: PrebuiltComponentOptions): boolean {
+  return options.ttl !== undefined || options.tags != null;
+}
+
+/**
+ * Resolve tags from options (may be static array or function of props).
+ * Function-form tags receive DATA props only — slot props are excluded so
+ * the tags fn never sees SlotOutlet placeholders (capture paths pass
+ * placeholder-substituted props) and tags stay deterministic per key.
+ */
+export function resolveTags(
+  options: PrebuiltComponentOptions,
+  props: Record<string, unknown>
+): string[] {
+  if (!options.tags) return [];
+  if (Array.isArray(options.tags)) return options.tags;
+  const slots = options.slots;
+  // The split cannot fail here — capture paths pass framework-built shell
+  // props — but stay total: fall back to the props as given.
+  const fnProps =
+    slots && slots.length > 0 ? (splitSlotProps(props, slots)?.dataProps ?? props) : props;
+  return options.tags(fnProps);
+}
+
+// ─── Nesting clamp (design/45 §Nesting Semantics) ────────────────────────
+
+/** The entry a capture is producing: its declaration and resolved tags. */
+export interface CapturedLifetime {
+  id: string;
+  options: PrebuiltComponentOptions;
+  tags: readonly string[];
+}
+
+/**
+ * Why an embedded copy of `inner` goes stale inside `outer`, or null when
+ * the outer's refreshes cover every refresh channel the inner declares:
+ *
+ * - `shorterTtl`: the inner's ttl is shorter than the outer's effective
+ *   lifetime (its ttl, or deploy-long without one).
+ * - `missingTags`: tags the inner resolved to that the outer lacks —
+ *   `revalidateTag` on them refreshes the inner's own entries, never the
+ *   copy. `null` inner tags (a tags function threw) cannot be proven a
+ *   subset, so they count as missing.
+ *
+ * Declaring the inner's tags on the outer is the documented fix, and it
+ * silences the tag half by construction.
+ */
+function clampReasons(
+  outer: CapturedLifetime,
+  inner: NestedWrapperRender
+): { shorterTtl: boolean; missingTags: string[] | null } | null {
+  const outerTtl = outer.options.ttl ?? Infinity;
+  const shorterTtl = inner.options.ttl !== undefined && inner.options.ttl < outerTtl;
+  const missingTags =
+    inner.tags === null ? null : inner.tags.filter((t) => !outer.tags.includes(t));
+  if (!shorterTtl && missingTags !== null && missingTags.length === 0) return null;
+  return { shorterTtl, missingTags };
+}
+
+/** Render a lifetime declaration for the clamp warning. */
+function describeLifetime(
+  options: PrebuiltComponentOptions,
+  tags: readonly string[] | null
+): string {
+  const parts: string[] = [];
+  if (options.prerender) parts.push('prerender');
+  if (options.ttl !== undefined) parts.push(`ttl: ${options.ttl}`);
+  if (tags === null) parts.push('tags: fn');
+  else if (tags.length > 0) parts.push(`tags: ${JSON.stringify(tags)}`);
+  return parts.join(', ') || 'no lifetime';
+}
+
+/** When the outer entry — and so every copy embedded in it — refreshes. */
+function describeRefresh(outer: CapturedLifetime): string {
+  const parts: string[] = [];
+  if (outer.options.ttl !== undefined) parts.push(`every ${outer.options.ttl}s`);
+  if (outer.tags.length > 0) parts.push(`on revalidateTag of its own tags`);
+  // Component keys are per-deploy, so every entry refreshes on redeploy.
+  parts.push('on redeploy');
+  return parts.join(', or ');
+}
+
+/**
+ * Warn for each wrapped component embedded in `outer`'s captured payload
+ * whose refresh channels the outer cannot honor. Once per (outer, inner)
+ * pair for the lifetime of `warnedPairs` — the builder passes one per
+ * build, the runtime one per process, since re-renders repeat. The key is
+ * the pair alone, not the reason: resolved tags vary with props, and a key
+ * that included them would grow with the data. So the first clamp found
+ * for a pair is the one reported. Returns the number of warnings emitted.
+ */
+export function warnNestingClamps(
+  outer: CapturedLifetime,
+  nested: readonly NestedWrapperRender[],
+  warnedPairs: Set<string>,
+  log: (message: string) => void
+): number {
+  let count = 0;
+  for (const inner of nested) {
+    const reasons = clampReasons(outer, inner);
+    if (reasons === null) continue;
+    const pairKey = `${outer.id}\0${inner.innerId}`;
+    if (warnedPairs.has(pairKey)) continue;
+    warnedPairs.add(pairKey);
+    count++;
+    const outerLifetime = describeLifetime(outer.options, outer.tags);
+    const innerLifetime = describeLifetime(inner.options, inner.tags);
+    const consequences: string[] = [];
+    if (reasons.missingTags === null) {
+      consequences.push(
+        `${inner.innerId}'s tags could not be resolved during the capture (its tags function ` +
+          `threw or needed request context), so revalidating them may NOT update the embedded copy.`
+      );
+    } else if (reasons.missingTags.length > 0) {
+      const calls = reasons.missingTags.map((t) => `revalidateTag(${JSON.stringify(t)})`);
+      consequences.push(
+        `${calls.join(', ')} will NOT update the embedded copy; tag ${outer.id} itself if you ` +
+          `need that.`
+      );
+    }
+    if (reasons.shorterTtl) {
+      consequences.push(
+        `${inner.innerId}'s ttl: ${inner.options.ttl} does not apply to the embedded copy.`
+      );
+    }
+    log(
+      `[timber] ${inner.innerId} (${innerLifetime}) is embedded in ` +
+        `${outer.options.prerender ? 'prerendered' : 'cached'} ${outer.id} — the embedded ` +
+        `copy refreshes only when ${outer.id} does (${describeRefresh(outer)}). ` +
+        `${consequences.join(' ')} Chain: ${outer.id} (${outerLifetime}) → ${inner.innerId} ` +
+        `(${innerLifetime})`
+    );
+  }
+  return count;
+}

package/src/server/prebuilt/slots.ts

@@ -19,6 +19,7 @@ import type { SlotValues } from '../../client/slot-context.ts';
 import { SlotOutlet } from '../../client/slot-outlet.tsx';
 import { SlotsProvider } from '../../client/slot-provider.tsx';
 import { splitSlotProps } from './cache-key.ts';
+import { hasRuntimeLifetime } from './lifetime.ts';
 import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
 
 /**
@@ -65,6 +66,18 @@ export function isChildrenSlotOutletElement(value: unknown): boolean {
   }
 }
 
+/**
+ * `props` without the framework-injected children outlet — the key props
+ * of a render. The outlet is the same client reference on every request,
+ * so it never varies the cache key; user-provided children stay (and
+ * leave the props unkeyable). See design/45 §Layout Propagation, TIM-1181.
+ */
+export function withoutChildrenOutlet(props: Record<string, unknown>): Record<string, unknown> {
+  if (!isChildrenSlotOutletElement(props.children)) return props;
+  const { children: _children, ...rest } = props;
+  return rest;
+}
+
 /**
  * Outcome of validating a `slots` declaration at registration time.
  *
@@ -122,8 +135,7 @@ export function resolveSlotNames(id: string, options: PrebuiltComponentOptions):
     return { kind: 'disabled' };
   }
   if (slots.length === 0) return { kind: 'none' };
-  const hasRuntimeLifetime = options.ttl !== undefined || options.tags != null;
-  if (!hasRuntimeLifetime) {
+  if (!hasRuntimeLifetime(options)) {
     console.warn(
       `[timber] cache.component "${id}": slots require a runtime lifetime ` +
         `(ttl and/or tags). Slot caching is disabled.`

package/src/server/prebuilt/synthetic-store.ts

@@ -89,6 +89,9 @@ export function createBuildTimeStore(
     segmentParamsRead: false,
   };
   const store: RequestContextStore = {
+    // No request at build time, so a stale-while-revalidate failure during
+    // capture is logged and not reported against a made-up one.
+    request: null,
     headers: new Headers(),
     originalHeaders: new Headers(),
     cookieHeader: '',