@timber-js/app 0.2.0-alpha.161 → 0.2.0-alpha.164

package/src/client/slot-context.ts

@@ -0,0 +1,48 @@
+/**
+ * SlotContext — delivers live slot content to SlotOutlet holes inside
+ * cached component shells (TIM-1173).
+ *
+ * A `cache.component(Fn, { slots: [...] })` shell is captured with a
+ * stable <SlotOutlet slot={name} /> client reference in place of each
+ * declared slot prop. At request time the revived shell is wrapped in a
+ * SlotsProvider carrying the live slot values; each outlet reads its
+ * value from this context by name.
+ *
+ * The value is a per-instance record — the NEAREST provider wins, so two
+ * instances of the same cached component on one page each resolve their
+ * own children, and a slot component nested inside another slot
+ * component's children reads its own provider, not the outer one.
+ *
+ * Generalizes the ChildSegmentContext pattern (TIM-1181) from a single
+ * implicit `children` hole on layouts to explicitly declared, named slot
+ * props on any cached component.
+ *
+ * SINGLETON GUARANTEE: globalThis + Symbol.for — the RSC client bundler
+ * can duplicate this module across chunks; globalThis guarantees a single
+ * context instance. Same pattern as ChildSegmentContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+export type SlotValues = Record<string, ReactNode>;
+
+const CTX_KEY = Symbol.for('__timber_slot_ctx');
+
+function getOrCreateContext(): React.Context<SlotValues | null> {
+  const existing = (globalThis as Record<symbol, unknown>)[CTX_KEY] as
+    | React.Context<SlotValues | null>
+    | undefined;
+  if (existing !== undefined) return existing;
+  if (typeof React.createContext === 'function') {
+    const ctx = React.createContext<SlotValues | null>(null);
+    (globalThis as Record<symbol, unknown>)[CTX_KEY] = ctx;
+    return ctx;
+  }
+  return undefined as unknown as React.Context<SlotValues | null>;
+}
+
+export const SlotContext = getOrCreateContext();

package/src/client/slot-outlet.tsx

@@ -0,0 +1,22 @@
+/**
+ * SlotOutlet — the hole in a cached component shell (TIM-1173).
+ *
+ * At capture time the prebuilt runtime renders the wrapped component with
+ * <SlotOutlet slot={name} /> in place of each declared slot prop. Being a
+ * client component, it serializes into the flight payload as a stable,
+ * deterministic client reference — the same bytes regardless of what live
+ * content will fill the hole. At request time the revived shell sits under
+ * a SlotsProvider and each outlet reads its live value from SlotContext.
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+import { SlotContext } from './slot-context.js';
+
+export function SlotOutlet({ slot }: { slot: string }) {
+  const values = useContext(SlotContext);
+  return values ? (values[slot] ?? null) : null;
+}

package/src/client/slot-provider.tsx

@@ -0,0 +1,25 @@
+/**
+ * SlotsProvider — wraps a revived cached shell to supply live slot content
+ * to the SlotOutlet holes inside it (TIM-1173).
+ *
+ * Tree structure per cached-component instance:
+ *   SlotsProvider(values={children: <Live />})
+ *     └── revived shell
+ *          └── SlotOutlet(slot="children") → reads context → <Live />
+ *
+ * See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+'use client';
+
+import { createElement, type ReactNode } from 'react';
+import { SlotContext, type SlotValues } from './slot-context.js';
+
+interface SlotsProviderProps {
+  values: SlotValues;
+  children: ReactNode;
+}
+
+export function SlotsProvider({ values, children }: SlotsProviderProps) {
+  return createElement(SlotContext.Provider, { value: values }, children);
+}

package/src/config-types.ts

@@ -137,7 +137,8 @@ export interface TimberUserConfig {
    * the connection is closed. Protects against hung fetches and Suspense
    * components that never resolve.
    *
-   * Set to 0 to disable (not recommended in production).
+   * Setting 0 uses a 120-second safety ceiling rather than disabling
+   * the timeout entirely.
    * Default: 30000 (30 seconds).
    *
    * See design/02-rendering-pipeline.md §"Streaming Constraints".

package/src/dev-tools/logs.ts

@@ -228,6 +228,13 @@ function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
       // Server runtime logs (render errors, action errors, etc.) are preserved.
       if (isFrameworkInternalCaller()) return;
 
+      // Break the server→browser→server console forwarding loop. Vite's
+      // forwardConsole re-logs browser console output on the server via
+      // `logger.error("[console.error] ...")`. Our patch would send it back
+      // to the browser, Vite's client patch forwards it again → exponential
+      // log spam. Detect the `[console.<level>]` prefix Vite adds and skip.
+      if (typeof args[0] === 'string' && args[0].includes('[console.')) return;
+
       // Serialize and forward to browser
       try {
         const payload: ServerLogPayload = {

package/src/plugin-context.ts

@@ -11,6 +11,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { parseAst } from 'vite';
 import type { RouteTree } from './routing/types';
 import type { BuildManifest } from './server/build-manifest';
 import type { CaptureSummary } from './server/prebuilt-builder';
@@ -18,6 +19,7 @@ import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
 import type { HoldingServer } from './dev-tools/holding-server.js';
+import type { ProgramNode } from './plugins/callsite-ast.js';
 
 // Re-export for sub-plugin convenience — they import from plugin-context.ts
 export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
@@ -147,6 +149,57 @@ export interface PluginContext {
   prebuiltLazyChunks?: Map<string, string>;
   /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
   captureSummary?: CaptureSummary;
+  /**
+   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
+   * transforms. Collapses both cross-plugin and cross-environment duplicate
+   * parses: identical code hits, rewritten code misses (correct because Vite
+   * transforms chain — a rewrite produces different code). Bounded LRU (32
+   * entries) so it doesn't hold programs for the whole build.
+   *
+   * Consumers MUST treat the returned ProgramNode as read-only — they collect
+   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
+   */
+  parseCached?: ParseMemo;
+}
+
+// ── AST parse memo ───────────────────────────────────────────────────────
+
+const PARSE_MEMO_CAPACITY = 32;
+
+/**
+ * Content-keyed LRU memo for `parseAst`. Transforms for the same module run
+ * back-to-back across plugins and environments, so a tiny window captures the
+ * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.
+ */
+export class ParseMemo {
+  private cache = new Map<string, ProgramNode>();
+
+  /**
+   * Parse code, returning a cached ProgramNode if the same code was parsed
+   * before. The returned AST MUST NOT be mutated — it may be shared across
+   * multiple consumers.
+   */
+  parse(code: string): ProgramNode {
+    const existing = this.cache.get(code);
+    if (existing) {
+      // LRU refresh: move to end
+      this.cache.delete(code);
+      this.cache.set(code, existing);
+      return existing;
+    }
+    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+    if (this.cache.size >= PARSE_MEMO_CAPACITY) {
+      // Evict oldest (first inserted)
+      const firstKey = this.cache.keys().next().value!;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(code, program);
+    return program;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
 }
 
 // ── App directory resolution ──────────────────────────────────────────────
@@ -197,6 +250,7 @@ export function createPluginContext(config?: TimberUserConfig, root?: string): P
     timer: createStartupTimer(),
     holdingServer: null,
     buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+    parseCached: new ParseMemo(),
   };
 }
 

package/src/plugins/cache.ts

@@ -55,7 +55,6 @@
 
 import { relative } from 'node:path';
 import MagicString from 'magic-string';
-import { parseAst } from 'vite';
 import type { Plugin } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import {
@@ -147,7 +146,7 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
 
       let program: ProgramNode;
       try {
-        program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+        program = ctx.parseCached!.parse(code);
       } catch {
         return;
       }

package/src/plugins/client-chunks.ts

@@ -48,6 +48,47 @@ function findAppBoundary(
   return { inApp: true, segment: null };
 }
 
+/**
+ * Check if a string is a bare import specifier (package name, not a path).
+ * Bare specifiers don't start with `.`, `/`, or contain `:/`.
+ */
+function isBareSpecifier(id: string): boolean {
+  return !id.startsWith('.') && !id.startsWith('/') && !id.includes(':/');
+}
+
+/**
+ * Look up facade ancestors for a module ID, handling bare package specifiers.
+ *
+ * The facade ancestry map is keyed by absolute resolved paths (from Rollup's
+ * moduleIds), but the RSC plugin passes bare package names (e.g. 'streamdown')
+ * as meta.id for npm package client references (TIM-1108). When a direct
+ * lookup misses and the id is a bare specifier, scan map keys for a matching
+ * node_modules path.
+ */
+function lookupFacades(
+  id: string,
+  sharedModuleFacades: Map<string, string[]>
+): string[] | undefined {
+  const direct = sharedModuleFacades.get(id);
+  if (direct) return direct;
+
+  if (!isBareSpecifier(id)) return undefined;
+
+  // Bare specifier: match against node_modules/<name>/ in map keys.
+  // Scoped packages use @scope/name, unscoped use just name.
+  // A package may have multiple module IDs in the RSC bundle (e.g. main
+  // entry + re-exported submodules), so aggregate facades from all matches.
+  const needle = `/node_modules/${id}/`;
+  let merged: string[] | undefined;
+  for (const [key, facades] of sharedModuleFacades) {
+    if (key.includes(needle)) {
+      if (!merged) merged = [...facades];
+      else merged.push(...facades);
+    }
+  }
+  return merged;
+}
+
 /**
  * For a `shared:` client reference, check the facade ancestry map to
  * see if all consuming facades belong to the same route boundary.
@@ -60,7 +101,7 @@ function reclassifySharedModule(
   root: string,
   sharedModuleFacades: Map<string, string[]>
 ): string | null {
-  const facades = sharedModuleFacades.get(meta.id);
+  const facades = lookupFacades(meta.id, sharedModuleFacades);
   if (!facades || facades.length === 0) return null;
 
   const boundaries = new Set<string>();

package/src/plugins/dev-server.ts

@@ -17,6 +17,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { TLSSocket } from 'node:tls';
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { sendNodeResponse } from 'srvx/node';
 import type { PluginContext } from '../plugin-context.js';
 import {
   sendErrorToOverlay,
@@ -298,8 +299,17 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
       // See design/25-production-deployments.md.
       const finalResponse = compressResponse(webRequest, webResponse);
 
-      // Convert Web Response → Node ServerResponse
-      await sendWebResponse(res, finalResponse);
+      // Flush headers eagerly so streaming responses (SSE, long-polling)
+      // reach the client before the first body chunk. Node.js buffers
+      // headers until write()/end() otherwise, which stalls EventSource
+      // clients that wait for the response to open. srvx's writeHead
+      // skips if headersSent is already true, so pre-flushing is safe.
+      res.writeHead(finalResponse.status, [...finalResponse.headers].flat());
+      res.flushHeaders();
+
+      // Stream the body with backpressure and disconnect handling.
+      // srvx skips its own writeHead since headers are already sent.
+      await sendNodeResponse(res, finalResponse);
     } catch (error) {
       // Pipeline error — classify the phase, send to overlay, respond 500.
       // The dev server remains running for recovery on file fix + HMR.
@@ -448,73 +458,6 @@ function nodeReadableToWebStream(nodeStream: IncomingMessage): ReadableStream<Ui
   });
 }
 
-/**
- * Write a Web Response to a Node ServerResponse.
- *
- * Copies status code, headers, and streams the body.
- */
-async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response): Promise<void> {
-  nodeRes.statusCode = webResponse.status;
-
-  // Copy headers. Set-Cookie needs special handling: Headers.forEach()
-  // joins multiple Set-Cookie values with ", " into one entry, but each
-  // cookie must be its own header per RFC 6265 §4.1. Use getSetCookie()
-  // to preserve individual Set-Cookie headers.
-  webResponse.headers.forEach((value, key) => {
-    if (key.toLowerCase() !== 'set-cookie') {
-      nodeRes.setHeader(key, value);
-    }
-  });
-  const setCookies = webResponse.headers.getSetCookie();
-  if (setCookies.length > 0) {
-    nodeRes.setHeader('Set-Cookie', setCookies);
-  }
-
-  // Stream the body
-  if (!webResponse.body) {
-    nodeRes.end();
-    return;
-  }
-
-  // Flush headers immediately so the client can start processing
-  // the response (critical for SSE and other streaming responses).
-  nodeRes.flushHeaders();
-
-  const reader = webResponse.body.getReader();
-
-  // Cancel the reader when the client disconnects. This causes any pending
-  // reader.read() to reject, breaking the pump loop. Critical for SSE and
-  // other infinite streams — without this, disconnected clients leak readers.
-  let clientDisconnected = false;
-  const onClose = () => {
-    clientDisconnected = true;
-    reader.cancel('Client disconnected').catch(() => {});
-  };
-  nodeRes.on('close', onClose);
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      // write() returns false when the kernel buffer is full, but we
-      // don't need back-pressure here — just keep pushing chunks.
-      nodeRes.write(value);
-    }
-  } catch (err) {
-    // reader.cancel() from the close handler causes read() to reject.
-    // This is expected on client disconnect — not an error.
-    if (!clientDisconnected) {
-      throw err;
-    }
-  } finally {
-    nodeRes.off('close', onClose);
-    reader.releaseLock();
-    if (!nodeRes.writableEnded) {
-      nodeRes.end();
-    }
-  }
-}
-
 // ─── URL Classification ──────────────────────────────────────────────────
 
 /**

package/src/plugins/prebuilt-options-analysis.ts

@@ -0,0 +1,175 @@
+/**
+ * Static analysis of `cache.component(fn, options)` option literals for
+ * the timber-prebuilt transform: can this call site's options put the
+ * component in the prerender tier?
+ *
+ * Runtime-tier call sites must do NO build work — recording them would
+ * make the post-build hook import the built RSC entry (running production
+ * startup) and load route modules for routes that have nothing to
+ * prerender (codex P2 on PR #836). The analysis is conservative in one
+ * direction only: over-inclusion costs a wasted entry load (the capture
+ * pass re-checks the real options at runtime and skips), under-inclusion
+ * would silently skip prerendering.
+ */
+
+import type { CallExpressionNode, PositionedNode } from './callsite-ast.js';
+
+const EXPRESSION_WRAPPER_TYPES = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/** Unwrap TS expression wrappers (`as`, `satisfies`, `!`, parens). */
+export function unwrapExpression(node: PositionedNode): PositionedNode {
+  let current = node;
+  while (EXPRESSION_WRAPPER_TYPES.has(current.type) && current.expression) {
+    current = current.expression as PositionedNode;
+  }
+  return current;
+}
+
+interface ObjectPropertyNode extends PositionedNode {
+  type: 'Property';
+  computed?: boolean;
+  key: PositionedNode & { name?: string; value?: unknown };
+  value: PositionedNode & { value?: unknown };
+}
+
+/** Three-state static knowledge about a property's runtime effect. */
+type Tri = 'yes' | 'no' | 'unknown';
+
+/**
+ * Statically classify a `slots` value node against resolveSlotNames'
+ * runtime rules (server/prebuilt/slots.ts):
+ *
+ * - `yes` — certainly an ACTIVE shape: dense, non-empty array literal of
+ *   non-empty string literals.
+ * - `no` — certainly NOT active (absent/empty/malformed): registration
+ *   falls back to non-slot semantics with `prerender` preserved.
+ * - `unknown` — identifiers, spreads, holes, non-literal elements.
+ */
+function classifySlotsValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'ArrayExpression') {
+    const elements = ((value as unknown as { elements: (PositionedNode | null)[] }).elements ??
+      []) as (PositionedNode | null)[];
+    if (elements.length === 0) return 'no'; // empty → kind 'none'
+    let allValidStrings = true;
+    for (const el of elements) {
+      if (el === null) return 'no'; // hole → sparse → malformed at runtime
+      if (el.type === 'SpreadElement') return 'unknown';
+      const entry = unwrapExpression(el) as { type: string; value?: unknown };
+      if (entry.type !== 'Literal') {
+        allValidStrings = false; // could still be a valid string at runtime
+        continue;
+      }
+      if (typeof entry.value !== 'string' || entry.value.length === 0) {
+        return 'no'; // a non-string/empty literal is malformed regardless of the rest
+      }
+    }
+    return allValidStrings ? 'yes' : 'unknown';
+  }
+  if (value.type === 'Literal') return 'no'; // null / primitive → malformed → disabled
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') {
+    return 'no'; // absent
+  }
+  return 'unknown';
+}
+
+/** Statically classify whether a `ttl` value gives a runtime lifetime (`ttl !== undefined`). */
+function classifyTtlValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'Literal') return 'yes'; // any literal (number, null, …) !== undefined
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') return 'no';
+  return 'unknown';
+}
+
+/** Statically classify whether a `tags` value gives a runtime lifetime (`tags != null`). */
+function classifyTagsValue(node: PositionedNode): Tri {
+  const value = unwrapExpression(node);
+  if (value.type === 'ArrayExpression') return 'yes';
+  if (value.type === 'ArrowFunctionExpression' || value.type === 'FunctionExpression') return 'yes';
+  if (value.type === 'Literal') {
+    return (value as { value?: unknown }).value === null ? 'no' : 'yes';
+  }
+  if (value.type === 'Identifier' && (value as { name?: string }).name === 'undefined') return 'no';
+  return 'unknown';
+}
+
+/**
+ * Can this call site's options put the component in the prerender tier?
+ * The answer is static only when the options argument is an object
+ * literal:
+ *
+ *   - literal with `prerender: true`            → yes
+ *   - literal with `prerender: false`/absent    → no  (spread-free)
+ *   - literal with statically ACTIVE `slots` + certain runtime lifetime
+ *     → no — registration strips `prerender` for active slot components
+ *       (TIM-1173), so attributing the callsite would make the post-build
+ *       hook import the RSC entry and enumerate route params for entries
+ *       the capture pass then skips (codex P2 on PR #890)
+ *   - anything else (identifier, spread, non-literal values)
+ *     → conservatively yes — the capture pass re-checks at runtime
+ *
+ * Properties walk in source order with last-write-wins, mirroring
+ * object-literal evaluation: `{ prerender: false, ...opts }` may end up
+ * prerenderable (the spread can override), while `{ ...opts,
+ * prerender: false }` is statically false (codex P2 on PR #836).
+ * Computed keys are treated like spreads — they may evaluate to any of
+ * the tracked names.
+ */
+export function mayPrerender(call: CallExpressionNode): boolean {
+  if (call.arguments.length < 2) return false; // no options → no lifetime → never prerender
+  const options = unwrapExpression(call.arguments[1] as PositionedNode);
+  if (options.type !== 'ObjectExpression') return true;
+  const properties = (options as unknown as { properties: PositionedNode[] }).properties ?? [];
+
+  type Verdict = 'absent' | 'true' | 'false' | 'unknown';
+  let verdict: Verdict = 'absent';
+  let slotsActive: Tri = 'no'; // absent slots are certainly not active
+  let ttl: Tri = 'no';
+  let tags: Tri = 'no';
+
+  for (const prop of properties) {
+    if (prop.type === 'SpreadElement' || (prop as ObjectPropertyNode).computed) {
+      // A spread/computed key may write ANY of the tracked options.
+      verdict = 'unknown';
+      slotsActive = 'unknown';
+      ttl = 'unknown';
+      tags = 'unknown';
+      continue;
+    }
+    if (prop.type !== 'Property') continue;
+    const property = prop as ObjectPropertyNode;
+    const keyName =
+      property.key.type === 'Identifier'
+        ? property.key.name
+        : property.key.type === 'Literal'
+          ? String(property.key.value)
+          : undefined;
+    if (keyName === 'prerender') {
+      const value = unwrapExpression(property.value);
+      if (value.type === 'Literal') {
+        verdict = (value as { value?: unknown }).value === true ? 'true' : 'false';
+      } else {
+        verdict = 'unknown'; // `prerender: flag` — not statically known
+      }
+    } else if (keyName === 'slots') {
+      slotsActive = classifySlotsValue(property.value);
+    } else if (keyName === 'ttl') {
+      ttl = classifyTtlValue(property.value);
+    } else if (keyName === 'tags') {
+      tags = classifyTagsValue(property.value);
+    }
+  }
+
+  if (verdict !== 'true' && verdict !== 'unknown') return false;
+  // Active slots + certain runtime lifetime → registration strips
+  // prerender, so the callsite is certainly runtime-tier. Any uncertainty
+  // (slots or lifetime not statically known) keeps the conservative
+  // attribution.
+  if (slotsActive === 'yes' && (ttl === 'yes' || tags === 'yes')) return false;
+  return true;
+}