@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/src/server/als-registry.ts

@@ -21,9 +21,10 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
@@ -39,28 +40,75 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchParams: URLSearchParams;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+   */
+  searchString: string;
+  /**
+   * Coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `getSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParams?: Record<string, string | string[]>;
+  /**
+   * The matched segment path (e.g. '/(browse)/[artistSlug]/[year]').
+   * Includes route groups and parallel slots — uniquely identifies the
+   * segment in the route tree. Set by the pipeline alongside segmentParams.
+   * Used by getSegmentParams() for dev-mode validation.
+   * See design/41-global-params.md §Runtime Validation
+   */
+  matchedSegmentPath?: string;
+  /**
+   * Per-slot coerced segment params, keyed by the slot's full tree path
+   * (e.g. '/(browse)/@shows/[artistSlug]/[...year]').
+   *
+   * Each slot walks its own segment tree and may interpret URL parts
+   * differently from the main route (e.g. catch-all vs dynamic). This
+   * map stores slot-specific params so getSegmentParams(segmentPath)
+   * returns the correct types for slot pages.
+   *
+   * See design/07-routing.md §"Parallel Slot Params"
+   */
+  slotParamsMap?: Map<string, Record<string, string | string[]>>;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */
   flushed: boolean;
   /** Whether the current context allows cookie mutation. */
   mutableContext: boolean;
+  /**
+   * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+   * server-side (inside the React tree, before React Flight sees it).
+   * The pipeline reads this after render to set the HTTP status code.
+   * See TIM-666.
+   */
+  denyStatus?: number;
+  /**
+   * Dev-only: getter for the current request's RSC debug components.
+   * Set by renderRoute() so onPipelineError can include component tree
+   * context for render-phase errors without module-level shared state.
+   */
+  debugComponentsGetter?: () => DebugComponentEntry[];
 }
 
 /** A single outgoing cookie entry in the cookie jar. */
 export interface CookieEntry {
   name: string;
   value: string;
-  options: import('./request-context.js').CookieOptions;
+  options: import('./cookie-context.js').CookieOptions;
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {

package/src/server/asset-headers.ts

@@ -15,6 +15,14 @@
  * Design docs: 18-build-system.md, 06-caching.md
  */
 
+import { IMMUTABLE_CACHE, STATIC_CACHE } from '../adapters/shared.js';
+
+// Re-export cache constants and generateHeadersFile from the shared adapter
+// module. The canonical definitions live in adapters/shared.ts because
+// adapters are loaded by Node before Vite's resolver is available — they
+// can only import from within their own directory.
+export { IMMUTABLE_CACHE, STATIC_CACHE, generateHeadersFile } from '../adapters/shared.js';
+
 /**
  * Regex matching Vite-hashed asset filenames.
  *
@@ -30,18 +38,6 @@
  */
 const HASHED_ASSET_RE = /[-.][\da-f]{8,}\.\w+$/;
 
-/** One year in seconds (365 days). */
-const ONE_YEAR = 31_536_000;
-
-/** One hour in seconds. */
-const ONE_HOUR = 3_600;
-
-/** Cache-Control value for hashed (immutable) assets. */
-export const IMMUTABLE_CACHE = `public, max-age=${ONE_YEAR}, immutable`;
-
-/** Cache-Control value for unhashed static assets. */
-export const STATIC_CACHE = `public, max-age=${ONE_HOUR}, must-revalidate`;
-
 /**
  * Check if a URL path looks like a hashed asset.
  */
@@ -57,25 +53,3 @@ export function isHashedAsset(pathname: string): boolean {
 export function getAssetCacheControl(pathname: string): string {
   return isHashedAsset(pathname) ? IMMUTABLE_CACHE : STATIC_CACHE;
 }
-
-/**
- * Generate a `_headers` file for static asset cache control.
- *
- * The `_headers` file is a platform convention supported by Cloudflare Workers
- * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
- * HTTP response headers.
- *
- * Vite places all hashed chunks under `/assets/` — these get immutable caching.
- * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
- */
-export function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}

package/src/server/build-manifest.ts

@@ -85,6 +85,12 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
+  // Emit <link rel="stylesheet"> tags as a fallback for platforms where
+  // React's Float system (via @vitejs/plugin-rsc preinit with
+  // data-precedence) doesn't handle CSS injection. In practice, Float
+  // deduplicates and these may be dropped. No preload hints — Float
+  // already starts the fetch via preinit(), and redundant preloads
+  // cause "ignored due to unknown as/type" browser warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 
@@ -95,10 +101,10 @@ export function buildCssLinkTags(cssUrls: string[]): string {
  * into 103 Early Hints responses. This avoids platform-specific 103
  * sending code.
  *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
  */
 export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
 }
 
 // ─── Font utilities ──────────────────────────────────────────────────────
@@ -153,10 +159,10 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
  *
  * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
  *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
  */
 export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
 }
 
 // ─── JS chunk utilities ──────────────────────────────────────────────────

package/src/server/coalesce-tick.ts

@@ -0,0 +1,75 @@
+/**
+ * Single-shot `setImmediate` coalescing primitive.
+ *
+ * Multiple synchronous `schedule()` calls within one event-loop tick
+ * result in exactly one `flush` invocation at the end of that tick.
+ * No recursive scheduling, no busy-wait, no polling loop.
+ *
+ * Both `createBufferedTransformStream` (Web) and
+ * `createNodeBufferedTransform` (Node) use this helper so the invariant
+ * — and this comment — live in one place.
+ *
+ * **Not a polling loop.** Uses a single-shot `setImmediate` per flush
+ * cycle — no recursive scheduling, no busy-wait. See design/02
+ * §"No Polling".
+ */
+
+export interface TickCoalescer {
+  /**
+   * Request a flush at the end of the current tick. If a flush is already
+   * scheduled, this is a no-op. Returns the pending promise (or undefined
+   * if the flush already fired and no new one has been scheduled).
+   */
+  schedule(): void;
+
+  /**
+   * The pending flush promise, if any. Callers (e.g. `flush()` in a
+   * TransformStream) can `await` this to wait for the scheduled flush
+   * to complete before closing the stream.
+   */
+  readonly pending: Promise<void> | undefined;
+
+  /**
+   * Cancel any pending scheduled flush and invoke the flush callback
+   * synchronously. Used by Node `Transform.flush()` which needs to
+   * drain the buffer immediately before calling back.
+   */
+  flushSync(): void;
+}
+
+/**
+ * Create a tick coalescer that calls `onFlush` at most once per tick.
+ */
+export function createTickCoalescer(onFlush: () => void): TickCoalescer {
+  let pending: Promise<void> | undefined;
+  let immediateHandle: ReturnType<typeof setImmediate> | null = null;
+
+  function doFlush(): void {
+    immediateHandle = null;
+    pending = undefined;
+    onFlush();
+  }
+
+  return {
+    schedule() {
+      if (immediateHandle !== null) return;
+      pending = new Promise<void>((resolve) => {
+        immediateHandle = setImmediate(() => {
+          doFlush();
+          resolve();
+        });
+      });
+    },
+
+    get pending() {
+      return pending;
+    },
+
+    flushSync() {
+      if (immediateHandle !== null) {
+        clearImmediate(immediateHandle);
+        doFlush();
+      }
+    },
+  };
+}

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }