@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/src/server/children-interception.ts

@@ -0,0 +1,115 @@
+/**
+ * Children-path interception — the sibling layout swap (TIM-1280).
+ *
+ * The second shape interception has. An intercepting directory that is a
+ * direct child of an ordinary segment or route group renders *in place of*
+ * `children` for that directory's own layout chain:
+ *
+ * ```
+ * app/(landing)/layout.tsx
+ * app/(landing)/[artistSlug]/[year]/[month]/[day]/page.tsx      ← hard nav
+ * app/(browse)/layout.tsx
+ * app/(browse)/(...)[artistSlug]/[year]/[month]/[day]/page.tsx  ← soft nav from (browse)
+ * ```
+ *
+ * There is no overlay, no slot, and no `default.tsx`. Nothing is re-matched
+ * either — and that is the point. The modal shape re-matches
+ * `interceptingPrefix`, a URL, and route groups contribute nothing to a URL,
+ * so an owner like `app/(browse)/` serializes to "/" and re-matching it
+ * resolves through whichever group owns the canonical page. This resolver
+ * addresses the owner by **tree path** instead, which never collapses.
+ *
+ * The result is an ordinary `RouteMatch` whose chain runs
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. Every
+ * consumer downstream — `tree-builder.ts`, the element builder, access gates,
+ * middleware — sees a segment chain and needs to know nothing about
+ * interception. That is why this feature adds no rendering path: the chain
+ * *is* the feature.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+
+import type { RouteMatch } from './pipeline.js';
+import { collectMiddlewareChain, type ManifestSegmentNode } from './route-matcher.js';
+import { findInterceptingMatch } from './slot-interception.js';
+import { treePathNames } from '../routing/segment-keys.js';
+
+/**
+ * Resolve a children-path interception to a complete route match.
+ *
+ * `interceptingScope` is the rewrite's own build-time field — the tree path of
+ * the directory that owns the interception. The pipeline has already
+ * established that the client's rendered tree passes through it; this
+ * translates it into the chain to render.
+ *
+ * Returns null when the scope names no directory in this manifest, or when no
+ * intercepting child of that directory matches the target. Both are fail-safe:
+ * the caller keeps the canonical target match, so the page the user gets is
+ * the one a hard navigation would have produced.
+ */
+export type InterceptedRouteMatcher = (
+  targetPathname: string,
+  interceptingScope: string
+) => RouteMatch | null;
+
+/** Build a children-path interception resolver over a runtime manifest. */
+export function createInterceptedRouteMatcher(root: ManifestSegmentNode): InterceptedRouteMatcher {
+  return (targetPathname, interceptingScope) => {
+    const ancestors = findChainByTreePath(root, interceptingScope);
+    if (!ancestors) return null;
+
+    const owner = ancestors[ancestors.length - 1];
+    // The same resolver the slot path uses. It takes an arbitrary node, buckets
+    // its intercepting children by the URL index their marker anchors them to,
+    // and walks each bucket with the shared tree walker — so marker depth,
+    // static-before-dynamic sibling ordering and catch-all handling are one
+    // implementation across both shapes rather than two that must agree.
+    const result = findInterceptingMatch(owner, targetPathname);
+    if (!result) return null;
+
+    // `result.chain` is [owner, interceptingNode, …descendants]; splice the
+    // owner's own ancestry in front of it to get a root-anchored chain.
+    const segments = [...ancestors, ...result.chain.slice(1)];
+
+    return {
+      segments,
+      // Every segment above the intercepting node is static or a route group —
+      // `validateInterceptionPlacement` rejects a dynamic one at build time,
+      // precisely because the intercepted URL carries no value to bind it
+      // with. So the intercepting subtree's params are the whole record.
+      segmentParams: result.slotParams,
+      middlewareChain: collectMiddlewareChain(segments),
+    };
+  };
+}
+
+/**
+ * Find the chain from the root to the segment with this tree path.
+ *
+ * Tree paths are `computeSegmentTreePaths` — the directory path with slots
+ * elided — so this walks `children` only, which is also exactly the set of
+ * positions a children-path interception can own: an intercepting directory
+ * inside a slot subtree is rejected at build time unless it is a direct slot
+ * child, and that shape is the modal one.
+ *
+ * Sibling directories cannot share a name, so a tree path names at most one
+ * node and the walk needs no tie-break. This is the property `urlPath` and
+ * `computeSegmentKeys` both lack — see the note on `computeSegmentTreePaths`.
+ */
+function findChainByTreePath(
+  root: ManifestSegmentNode,
+  treePath: string
+): ManifestSegmentNode[] | null {
+  const names = treePathNames(treePath);
+  const chain: ManifestSegmentNode[] = [root];
+  let node = root;
+
+  for (const name of names) {
+    const next = node.children.find((child) => child.segmentName === name);
+    if (!next) return null;
+    chain.push(next);
+    node = next;
+  }
+
+  return chain;
+}

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

@@ -7,6 +7,14 @@
 // this module is only used on Node.js/Bun.
 //
 // See design/25-production-deployments.md.
+//
+// This module is also emitted standalone as `_compress.mjs` by
+// `adapters/compress-module.ts`, which strips types but does not bundle. Its
+// imports must therefore be interpolated there — a new import that is not
+// fails the build with an explanatory error rather than resolving to nothing
+// on the deployed server.
+
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -21,7 +29,7 @@ export const COMPRESSIBLE_TYPES = new Set([
   'text/plain',
   'text/xml',
   'text/javascript',
-  'text/x-component',
+  RSC_CONTENT_TYPE,
   'application/json',
   'application/javascript',
   'application/xml',
@@ -160,15 +168,42 @@ 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, pipeline } 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);
+
+  // pipeline() instead of bare pipe(): pipe() does not forward source errors,
+  // so an erroring body (streaming route handler, dropped upstream fetch)
+  // would emit an unhandled 'error' event and crash the process. pipeline()
+  // destroys gzip on source error — the returned web stream rejects — and
+  // tears down nodeInput when the consumer cancels the web stream, which
+  // cancels the source body via fromWeb. The error reaches the consumer
+  // through the web stream; the callback only marks it handled at the Node
+  // layer.
+  pipeline(nodeInput, gzip, () => {});
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }