@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/server/safe-load.d.ts

@@ -0,0 +1,39 @@
+/**
+ * loadModule — enriched error context for route manifest .load() failures.
+ *
+ * Wraps the lazy `load()` functions from the route manifest with a
+ * try/catch that re-throws with the file path and original cause.
+ *
+ * Loads the render can do without (status, error and fallback pages) go
+ * through `loadFallbackModule()` in pipeline-helpers.ts instead, which logs
+ * and reports the failure and resolves to `null` — never a bare
+ * `.catch(() => null)`, which skips a broken page silently (TIM-1458).
+ *
+ * See design/spike-TIM-551-dynamic-import-audit.md §"Proposed Wrapping Strategy"
+ */
+/** A manifest file reference with a lazy import function and file path. */
+export interface ManifestLoader {
+    load: () => Promise<unknown>;
+    filePath: string;
+}
+/**
+ * Custom error class for module load failures.
+ *
+ * Preserves the original error as `cause` while providing a
+ * human-readable message with the file path.
+ */
+export declare class ModuleLoadError extends Error {
+    /** The file path that failed to load. */
+    readonly filePath: string;
+    constructor(filePath: string, cause: unknown);
+}
+/**
+ * Load a route manifest module with enriched error context.
+ *
+ * On success: returns the module object (same as `loader.load()`).
+ * On failure: throws `ModuleLoadError` with file path and original cause.
+ *
+ * Error rendering paths that need fallthrough use `loadFallbackModule()`.
+ */
+export declare function loadModule<T = Record<string, unknown>>(loader: ManifestLoader): Promise<T>;
+//# sourceMappingURL=safe-load.d.ts.map

package/dist/server/safe-load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-load.d.ts","sourceRoot":"","sources":["../../src/server/safe-load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YAAY,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAK3C;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAMhG"}

package/dist/server/sensitive-fields.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Sensitive field stripping — removes password/token/CVV-style fields
+ * from form values before they are echoed back to the client as
+ * `submittedValues` for form repopulation.
+ *
+ * Applied to both action paths:
+ *  - With-JS action path: `createActionClient()` in `action-client.ts`
+ *  - No-JS form POST path: `handleFormAction()` in `action-handler.ts`
+ *
+ * Why: on a validation failure, timber echoes submitted form values back so
+ * the user doesn't have to re-type everything. Without filtering, plaintext
+ * passwords / credit-card numbers / TOTP codes would travel through the RSC
+ * stream (with-JS) or land in the HTML as `defaultValue` attributes (no-JS)
+ * — ending up in browser history, proxy logs, disk caches, and the
+ * back-forward cache.
+ *
+ * Safe by default: the built-in deny-list is applied unconditionally unless
+ * the user explicitly opts out via `forms.stripSensitiveFields: false` in
+ * `timber.config.ts` or per-action via `createActionClient({ stripSensitiveFields: false })`.
+ *
+ * See design/08-forms-and-actions.md §"Validation errors"
+ * See design/13-security.md §"Sensitive field stripping"
+ * See TIM-816
+ */
+/**
+ * How to strip sensitive fields from `submittedValues`.
+ *
+ * - `true` / `undefined` — use the built-in deny-list (default, safe).
+ * - `false` — do not strip anything (dev convenience; never do this in prod).
+ * - `string[]` — additional field names to strip, merged with the built-in list.
+ * - `(name) => boolean` — custom predicate, fully replaces the built-in list.
+ *   Return `true` to strip, `false` to keep. The `name` argument is the raw
+ *   (un-normalized) field name as it appeared in the submitted form.
+ */
+export type SensitiveFieldsOption = boolean | readonly string[] | ((name: string) => boolean);
+/**
+ * A resolved predicate: `null` means "don't strip anything" (the option was
+ * explicitly `false`). Otherwise a function from raw field name → boolean.
+ */
+export type ResolvedSensitivePredicate = ((name: string) => boolean) | null;
+/**
+ * Resolve a `SensitiveFieldsOption` into a concrete predicate.
+ * Precedence: per-action > global > built-in default.
+ *
+ * - Per-action `undefined` → fall back to global.
+ * - Global `undefined` → use built-in list.
+ * - Either level set to `false` → disable stripping entirely (returns `null`).
+ * - `true` → built-in list.
+ * - `string[]` → built-in ∪ extras.
+ * - function → custom, replaces the built-in list entirely.
+ */
+export declare function resolveSensitivePredicate(perAction: SensitiveFieldsOption | undefined, global: SensitiveFieldsOption | undefined): ResolvedSensitivePredicate;
+/**
+ * Set the global `forms.stripSensitiveFields` config from `timber.config.ts`.
+ * Called once at startup from `rsc-entry`.
+ */
+export declare function setGlobalSensitiveFieldsConfig(option: SensitiveFieldsOption | undefined): void;
+/** Read the global `forms.stripSensitiveFields` config. */
+export declare function getGlobalSensitiveFieldsConfig(): SensitiveFieldsOption | undefined;
+/**
+ * Walk an object (recursively) and return a copy with every key matching
+ * `predicate` removed. Nested objects like `{ user: { password: '...' } }`
+ * are handled — `user.password` is stripped while other `user.*` fields remain.
+ *
+ * - Arrays are walked element-wise (object entries inside arrays are cleaned).
+ * - Non-plain values (strings, numbers, Files, Dates, etc.) are returned as-is.
+ * - When a stripped key is encountered, it is omitted from the result entirely
+ *   — we do NOT set it to an empty string, because that would overwrite a
+ *   valid `defaultValue` the form author might have set.
+ */
+export declare function stripSensitiveFields<T>(value: T, predicate: ResolvedSensitivePredicate): T;
+/** Reset the "warned once" cache. Exposed for tests. */
+export declare function __resetSensitiveFieldsWarnings(): void;
+//# sourceMappingURL=sensitive-fields.d.ts.map

package/dist/server/sensitive-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-fields.d.ts","sourceRoot":"","sources":["../../src/server/sensitive-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAoF9F;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,qBAAqB,GAAG,SAAS,EAC5C,MAAM,EAAE,qBAAqB,GAAG,SAAS,GACxC,0BAA0B,CAa5B;AAMD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,CAE9F;AAED,2DAA2D;AAC3D,wBAAgB,8BAA8B,IAAI,qBAAqB,GAAG,SAAS,CAElF;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,0BAA0B,GAAG,CAAC,CAoB1F;AAID,wDAAwD;AACxD,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/dist/server/signal-identity.d.ts

@@ -0,0 +1,43 @@
+import type { DenySignal, RedirectSignal } from './primitives.ts';
+export declare const DENY_BRAND: unique symbol;
+export declare const REDIRECT_BRAND: unique symbol;
+declare const SSR_STREAM_ERROR_BRAND: unique symbol;
+/** True for any `DenySignal`, regardless of which module evaluation created it. */
+export declare function isDenySignal(error: unknown): error is DenySignal;
+/** True for any `RedirectSignal`, regardless of which module evaluation created it. */
+export declare function isRedirectSignal(error: unknown): error is RedirectSignal;
+/**
+ * True for any `SsrStreamError`. This one also crosses Vite environments:
+ * it is thrown in SSR and caught in RSC, which are separate module graphs in
+ * the same process — the brand is the only identity the two share.
+ */
+export declare function isSsrStreamError(error: unknown): error is SsrStreamError;
+/**
+ * Returns true if the error is a framework control-flow signal (RedirectSignal
+ * or DenySignal) rather than a genuine application error. Works both for direct
+ * instances (RSC-side) and deserialized digest errors (SSR cross-boundary).
+ *
+ * See also: isFrameworkSignalError() in client/browser-dev.ts (client-only).
+ */
+export declare function isControlFlowSignal(error: unknown): boolean;
+/**
+ * Error thrown when SSR's renderToReadableStream fails due to an error
+ * in the decoded RSC stream (e.g., uncontained slot errors).
+ *
+ * The RSC entry checks for this error type in its catch block. A captured
+ * deny or redirect is rethrown to the pipeline first; with no captured
+ * signal, it renders the error page for the uncontained error.
+ *
+ * Not defined in ssr-entry.ts because ssr-entry.ts imports react-dom/server,
+ * which cannot be loaded in the RSC environment.
+ *
+ * Detect with `isSsrStreamError()` — it is thrown in the SSR environment and
+ * caught in RSC, so `instanceof` never matches. See "Signal branding" above.
+ */
+export declare class SsrStreamError extends Error {
+    readonly [SSR_STREAM_ERROR_BRAND] = true;
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+export {};
+//# sourceMappingURL=signal-identity.d.ts.map

package/dist/server/signal-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-identity.d.ts","sourceRoot":"","sources":["../../src/server/signal-identity.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAqBlE,eAAO,MAAM,UAAU,EAAE,OAAO,MAAyC,CAAC;AAC1E,eAAO,MAAM,cAAc,EAAE,OAAO,MAA6C,CAAC;AAClF,QAAA,MAAM,sBAAsB,EAAE,OAAO,MAAqD,CAAC;AAM3F,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkB3D;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,CAAC,sBAAsB,CAAC,QAAQ;IACzC,SAAkB,KAAK,EAAE,OAAO,CAAC;IAEjC,YAAY,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAI1C;CACF"}

package/dist/server/sitemap-generator.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Auto-generate sitemap.xml from the route tree.
+ *
+ * When enabled via `sitemap: { enabled: true, baseUrl: '...' }` in timber.config.ts,
+ * this module walks the route tree and produces sitemap XML for all discoverable pages.
+ *
+ * Features:
+ * - Collects all static page routes automatically
+ * - Calls `generateStaticSegmentParams()` on dynamic routes to enumerate URLs
+ * - Skips API routes (route.ts), layout-only segments, slots, intercepting routes
+ * - Skips auth-protected routes (access.ts in segment chain) by default
+ * - Automatic pagination: sitemap index when > 50,000 URLs
+ *
+ * See design/16-metadata.md §"Auto-generated Sitemap"
+ */
+import type { SegmentNode } from '../routing/types.ts';
+import type { CoercedParams } from '../shared/param-value.ts';
+/** Configuration for sitemap generation from timber.config.ts. */
+export interface SitemapConfig {
+    /** Must be explicitly true to enable auto-generation. */
+    enabled: boolean;
+    /** Base URL for absolute URLs in the sitemap. Required. e.g., 'https://example.com' */
+    baseUrl: string;
+    /** Default changefreq for all entries. Optional. */
+    defaultChangeFrequency?: string;
+    /** Default priority for all entries (0.0–1.0). Optional. */
+    defaultPriority?: number;
+    /** Include routes protected by access.ts. Default: false. */
+    includeProtected?: boolean;
+}
+/** A single sitemap entry ready for serialization. */
+export interface SitemapEntry {
+    url: string;
+    changeFrequency?: string;
+    priority?: number;
+}
+/**
+ * A route discovered during tree walk that may need async resolution
+ * (dynamic routes with generateStaticSegmentParams).
+ */
+export interface SitemapRoute {
+    /** The URL path pattern (e.g., '/products/[id]'). */
+    urlPath: string;
+    /** Whether this route has dynamic segments that need generateStaticSegmentParams. */
+    isDynamic: boolean;
+    /** Loader for the page module (from route manifest). */
+    pageLoader?: {
+        load: () => Promise<unknown>;
+        filePath: string;
+    };
+}
+/**
+ * Function signature for loading a page module.
+ * Takes the manifest loader and returns the module exports.
+ */
+export type ModuleLoader = (loader: {
+    load: () => Promise<unknown>;
+    filePath: string;
+}) => Promise<Record<string, unknown>>;
+/** Result of sitemap generation. */
+export type SitemapResult = {
+    type: 'single';
+    xml: string;
+} | {
+    type: 'index';
+    indexXml: string;
+    pages: Map<number, string>;
+};
+/** Maximum URLs per sitemap file per the sitemap protocol. */
+export declare const URLS_PER_SITEMAP = 50000;
+/**
+ * Walk the route tree and collect all routes eligible for the sitemap.
+ *
+ * Pure synchronous function — no module loading. Returns routes that may
+ * need async resolution (dynamic routes with generateStaticSegmentParams).
+ *
+ * @param root - The root segment node from the route tree
+ * @param config - Sitemap configuration
+ * @returns Array of sitemap routes to resolve
+ */
+export declare function collectSitemapRoutes(root: SegmentNode, config: SitemapConfig): SitemapRoute[];
+/**
+ * Check if a URL path contains dynamic segments.
+ *
+ * Dynamic segments are enclosed in brackets: [param], [...param], [[...param]]
+ */
+export declare function hasDynamicSegments(urlPath: string): boolean;
+/**
+ * Resolve sitemap routes into concrete URLs.
+ *
+ * For static routes, the URL is derived directly from the path.
+ * For dynamic routes, calls `generateStaticSegmentParams()` from the page module.
+ *
+ * @param routes - Routes collected by collectSitemapRoutes
+ * @param config - Sitemap configuration
+ * @param loadModule - Async function to load a page module by file path
+ * @returns Array of sitemap entries with absolute URLs
+ */
+export declare function resolveSitemapUrls(routes: SitemapRoute[], config: SitemapConfig, loadModule?: ModuleLoader): Promise<SitemapEntry[]>;
+/**
+ * Replace dynamic segments in a URL path with concrete param values.
+ *
+ * Handles:
+ * - `[param]` → single value
+ * - `[...param]` → slash-joined values
+ * - `[[...param]]` → slash-joined values (or empty string if not provided)
+ *
+ * @returns The resolved path, or null if params are missing
+ */
+export declare function resolvePathWithParams(urlPath: string, params: CoercedParams): string | null;
+/**
+ * Generate the complete sitemap result from a route tree.
+ *
+ * Orchestrates tree walking, URL resolution, and XML serialization.
+ * Returns either a single sitemap or a paginated sitemap index.
+ *
+ * @param root - The root segment node from the route tree
+ * @param config - Sitemap configuration
+ * @param loadModule - Optional async function to load page modules (for generateStaticSegmentParams)
+ * @returns The sitemap result (single or index with pages)
+ */
+export declare function generateSitemap(root: SegmentNode, config: SitemapConfig, loadModule?: ModuleLoader): Promise<SitemapResult>;
+/**
+ * Check if the route tree root has a user-authored sitemap metadata route.
+ *
+ * When a user-authored sitemap exists at the root, auto-generation is disabled
+ * to avoid conflicts — the user takes full control.
+ */
+export declare function hasUserSitemap(root: SegmentNode<unknown>): boolean;
+//# sourceMappingURL=sitemap-generator.d.ts.map

package/dist/server/sitemap-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap-generator.d.ts","sourceRoot":"","sources":["../../src/server/sitemap-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAI9D,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE;IAClC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvC,oCAAoC;AACpC,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAIpE,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAIvC;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,GAAG,YAAY,EAAE,CAI7F;AAwDD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,aAAa,EACrB,UAAU,CAAC,EAAE,YAAY,GACxB,OAAO,CAAC,YAAY,EAAE,CAAC,CA+CzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CA2C3F;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,aAAa,EACrB,UAAU,CAAC,EAAE,YAAY,GACxB,OAAO,CAAC,aAAa,CAAC,CA+BxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAGlE"}

package/dist/server/sitemap-handler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Auto-sitemap request handler for the pipeline.
+ *
+ * Creates a handler function that intercepts `/sitemap.xml` and `/sitemap/N.xml`
+ * requests, generating sitemap XML from the route tree on-the-fly.
+ *
+ * This module bridges the pipeline (which doesn't know about route trees)
+ * with the sitemap generator (which doesn't know about HTTP).
+ *
+ * See design/16-metadata.md §"Auto-generated Sitemap"
+ */
+import type { SegmentNode } from '../routing/types.ts';
+/**
+ * Create the auto-sitemap request handler for the pipeline.
+ *
+ * Returns a function that handles `/sitemap.xml` and `/sitemap/N.xml`,
+ * or returns `null` to pass through to regular routing.
+ *
+ * Returns `undefined` if auto-sitemap is not enabled (no overhead in pipeline).
+ */
+export declare function createAutoSitemapHandler(root: SegmentNode, runtimeConfig: Record<string, unknown>): ((pathname: string) => Promise<Response | null>) | undefined;
+//# sourceMappingURL=sitemap-handler.d.ts.map

package/dist/server/sitemap-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap-handler.d.ts","sourceRoot":"","sources":["../../src/server/sitemap-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAKvD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,GAAG,SAAS,CAyH9D"}

package/dist/server/skippable-prefix.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Skippable-prefix computation.
+ *
+ * Determines which layouts can be skipped on a partial navigation by
+ * computing a contiguous prefix of segments whose cached layouts need
+ * not re-render. Extracted from `route-element-builder.ts` to keep it
+ * under the 500-line limit (design/18-build-system.md).
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header".
+ */
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { RouteMatch } from './pipeline.ts';
+import { type ClientStateTree } from './state-tree-diff.ts';
+/**
+ * Compute the set of segment indices whose layouts can be skipped.
+ *
+ * Three sub-rules in order:
+ *   (a) Contiguous prefix via `shouldSkipSegment` — stop at the first
+ *       non-skippable layout.
+ *   (b) If every layout landed in the prefix, remove the innermost one
+ *       as the merge point (the client needs a mounted outlet there).
+ *   (c) Cross-section guard — clear the whole set unless at least one
+ *       non-skipped layout's key is in `clientStateTree`.
+ *
+ * After the prefix is computed, `truncateSkippableForChangedSlots`
+ * removes any segment whose parallel slots changed content.
+ */
+export declare function computeSkippableSet(segments: ManifestSegmentNode[], segmentKeys: string[], layoutBySegment: Map<ManifestSegmentNode, unknown>, clientStateTree: ClientStateTree | null | undefined, match: RouteMatch, req: Request): Set<number>;
+//# sourceMappingURL=skippable-prefix.d.ts.map

package/dist/server/skippable-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skippable-prefix.d.ts","sourceRoot":"","sources":["../../src/server/skippable-prefix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAM/F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,WAAW,EAAE,MAAM,EAAE,EACrB,eAAe,EAAE,GAAG,CAAC,mBAAmB,EAAE,OAAO,CAAC,EAClD,eAAe,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EACnD,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,GACX,GAAG,CAAC,MAAM,CAAC,CAyEb"}

package/dist/server/slot-interception.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Intercepting-route resolution for parallel slots.
+ *
+ * This is the ONLY interception-aware part of the render pipeline. The normal
+ * children path — `tree-match.ts`, `route-matcher.ts` — has none, and must
+ * keep none: teaching the shared walker to match intercepting nodes would make
+ * the *main* route matcher render modals on hard navigation. Interception
+ * therefore lives here, behind one entry point the slot resolver calls when
+ * the pipeline has flagged a soft navigation.
+ *
+ * Split out of `slot-resolver.ts` when the matching rules grew (TIM-1281):
+ * anchoring, sibling priority, and the identity a marker'd directory name
+ * stands for are one subject, and slot resolution proper is another.
+ *
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { SlotMatchResult } from './slot-resolver.ts';
+/**
+ * Find a matching intercepting route in a slot's children for the target pathname.
+ *
+ * When interception is active, the pipeline has already re-matched the source URL.
+ * Here we check the slot's intercepting children (e.g. `(.)photo/[id]`) against
+ * the target pathname to find which intercepting page to render.
+ *
+ * Two things distinguish an intercepting child from an ordinary slot child,
+ * and both used to be handled by hand here (TIM-1281):
+ *
+ * **Where its segment sits in the target.** The marker says how far above the
+ * slot owner the intercepted route lives, which makes the intercepted
+ * segment's index in the target pathname a position rather than something to
+ * search for. The old code scanned the target from the end for a part equal
+ * to the directory name, which found the wrong index whenever a *value*
+ * happened to equal that name (`/gallery/photo/photo`) and could never work
+ * at all for a dynamic intercepted segment.
+ *
+ * The index is derived from `computeInterceptedBase` — a build-time URL
+ * pattern — and NOT from the re-matched source route. That route is matched
+ * from `interceptingPrefix`, which is itself a pattern, so under a dynamic
+ * ancestor its params are literals: re-matching `/docs/[...path]` binds
+ * `path` to `['[...path]']`, and any depth read from it is the pattern's,
+ * not the URL's.
+ *
+ * A pattern part maps 1:1 onto a URL part except for a catch-all, whose
+ * width varies per request; `anchorApplies` documents what that costs.
+ *
+ * **What its segment matches.** `(.)photo` matches the literal `photo`;
+ * `(.)[id]`, `(.)img-[id].png` and `(.)[...rest]` match the way the same
+ * bracket syntax matches anywhere else. Rather than re-classify here, the
+ * node is handed to the shared walker under its `effectiveUrlSegment`
+ * identity, so priority ordering, affix stripping, catch-all collection and
+ * the terminal-leaf rule all come from `tree-match.ts` — which stays
+ * interception-unaware, as it must: teaching it to match intercepting nodes
+ * would make the *main* route matcher render modals on hard navigation.
+ *
+ * **Siblings compete, so they are walked together.** Two interceptors that
+ * anchor at the same URL index — `(.)photo/page.tsx` and `(.)[slug]/page.tsx`
+ * — are both candidates for the same part, exactly like two ordinary
+ * siblings. Matching each in its own tree and returning the first that
+ * succeeded would resolve them in manifest (filesystem) order, so
+ * `/gallery/photo` would render the dynamic modal whenever the dynamic
+ * directory happened to be enumerated first. Grouping by anchor and handing
+ * the whole group to one walk restores static > dynamic > catch-all, and
+ * gives backtracking across siblings for free.
+ *
+ * Groups are tried deepest anchor first, so a `(.)` interception — the most
+ * local one — wins over a `(...)` that reaches the same page from the root.
+ *
+ * The grouping itself is `groupByInterceptedAnchor`, shared with the build so
+ * that what is walked together is what the collision validator checked together
+ * (TIM-1310). Two interceptors of the *same* kind at one anchor — `(.)[a]`
+ * beside `(.)[b]` — would otherwise resolve by manifest order here with nothing
+ * to say so; the validator rejects them, within the limits of a probe search,
+ * because it walks this same group.
+ *
+ * The matched chain carries the real node, not the identity proxy, so tree
+ * paths keep the directory name (`/gallery/@modal/(.)photo/[id]`).
+ */
+export declare function findInterceptingMatch(slotNode: ManifestSegmentNode, targetPathname: string): SlotMatchResult | null;
+//# sourceMappingURL=slot-interception.d.ts.map

package/dist/server/slot-interception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-interception.d.ts","sourceRoot":"","sources":["../../src/server/slot-interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAsD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAgCxB"}

package/dist/server/slot-resolver.d.ts

@@ -15,8 +15,9 @@
  *
  * See design/02-rendering-pipeline.md §"Parallel Slots"
  */
-import type { InterceptionContext, RouteMatch } from './pipeline.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
+import type { InterceptionContext, RouteMatch } from './pipeline.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import { type ClientStateTree } from './state-tree-diff.ts';
 type CreateElementFn = (...args: unknown[]) => React.ReactElement;
 /**
  * Resolve the element for a parallel slot.
@@ -24,11 +25,141 @@ type CreateElementFn = (...args: unknown[]) => React.ReactElement;
  * Finds a matching page in the slot's sub-tree for the current route.
  * Falls back to default.tsx if no match, or null if no default.
  *
- * When a match is found, the element is wrapped with:
- * 1. Error boundaries from each segment in the slot's matched chain
- * 2. Layouts from each segment in the slot's matched chain
- * 3. SlotAccessGate if the slot root has access.ts
+ * When a match is found, the element is wrapped per segment in the slot's
+ * matched chain with (innermost → outermost):
+ * 1. Error boundaries
+ * 2. Layout
+ * 3. SlotAccessGate if the segment has access.ts (gate OUTSIDE the layout,
+ *    so a denied layout never executes — see TIM-1074)
  */
-export declare function resolveSlotElement(slotNode: ManifestSegmentNode, match: RouteMatch, paramsPromise: Promise<Record<string, string | string[]>>, h: CreateElementFn, interception?: InterceptionContext): Promise<React.ReactElement | null>;
+export declare function resolveSlotElement(slotNode: ManifestSegmentNode, match: RouteMatch, h: CreateElementFn, req: Request, interception?: InterceptionContext, parentTreePath?: string): Promise<React.ReactElement | null>;
+/** Result of matching a slot's sub-tree against the current route. */
+export interface SlotMatchResult {
+    /** The page file at the matched leaf. */
+    page: NonNullable<ManifestSegmentNode['page']>;
+    /** The full chain of slot nodes traversed (slot root → … → leaf with page). */
+    chain: ManifestSegmentNode[];
+    /** Params collected from the slot's segment chain (pre-coercion, may differ from main route params). */
+    slotParams: Record<string, string | string[]>;
+}
+/**
+ * Find a matching page in a slot's sub-tree for the current route.
+ *
+ * Returns the matched page AND the full chain of nodes traversed, so the
+ * caller can apply error boundaries and layouts from each intermediate segment.
+ *
+ * Slots don't add URL depth (they're at the same level as their parent).
+ * A slot at segment /parallel with children /parallel/projects means:
+ *   - URL /parallel → slot's own page.tsx
+ *   - URL /parallel/projects → slot's projects/page.tsx
+ *   - URL /parallel/about → no match (use default.tsx)
+ *
+ * We compare the matched route's segment chain against the slot's children
+ * to find the deepest matching page.
+ */
+/**
+ * The index in the matched chain of the segment that owns this slot.
+ *
+ * **By identity**, because `urlPath` cannot answer it. Slots add no URL depth,
+ * so the owner shares the slot's `urlPath` — but so does every route group
+ * above it (`/` for both the root and `(browse)`), and since TIM-1280 so does
+ * an intercepting node on the children path, which sits *below* the owner.
+ * Picking the deepest urlPath match — the rule before this — therefore chose
+ * the intercepting node for a tree like `(browse)/@sidebar/` +
+ * `(browse)/(.)item/[id]/`, slicing one segment too many off the chain and
+ * handing `@sidebar` a shorter URL than it matches against. It would render
+ * its `default.tsx` where a page exists.
+ *
+ * The index must also agree with `slotUrlParts`, which slices the destination
+ * pathname at the same point and already used `indexOf(owner)`. Two derivations
+ * of one index is how they came apart; this is the shared one.
+ *
+ */
+export declare function findSlotOwnerIndex(slotNode: ManifestSegmentNode, segments: ManifestSegmentNode[]): number;
+export interface SlotSkipEntry {
+    slotKey: string;
+    parentSegmentId: string;
+    /**
+     * Whether the slot's components called request accessors (getHeaders,
+     * getSearchParams, cookies) during their last render. Replaces the
+     * unreliable AsyncFunction heuristic — taint-tracked via ALS.
+     */
+    isRequestDependent: boolean;
+    /** Whether the slot's access.ts denied on this render. */
+    denied: boolean;
+    /** Whether the slot was skipped (content not rendered, client keeps cached). */
+    skipped?: boolean;
+    /**
+     * Content key encoding owner parts + slot name + entry file + slot params.
+     * Sent to the client via X-Timber-Segments; the client advertises it back
+     * so the server can decide skips by key membership (TIM-1370).
+     */
+    contentKey: string;
+}
+/**
+ * The destination URL parts a segment's slots match against.
+ *
+ * A slot walks its own sub-tree starting where its owning segment stopped
+ * consuming the URL, so the parts are sliced at the length its ancestors
+ * consumed. Shared by `resolveSlotProps` and `publishSlotSegmentParams` — both
+ * have to slice identically or the two would disagree about which page a slot
+ * matched, and only one of them would be right.
+ *
+ * @internal
+ */
+export declare function slotUrlParts(segment: ManifestSegmentNode, match: RouteMatch, url: string): string[];
+/**
+ * Seed per-slot segment params for a segment whose layout is being SKIPPED.
+ *
+ * `resolveSlotProps` seeds these as part of resolving slot props, but a skipped
+ * layout never gets there — `route-element-builder` continues past it. Its
+ * slots are still mounted on the client, though, so leaving them out of the
+ * published map made `useSegmentParams(slotPath)` fall back to the main route's
+ * record after any navigation that skipped their parent (TIM-1285).
+ *
+ * Only the params are seeded. Nothing renders, no access chain runs — a skipped
+ * layout's slots are unchanged by definition, which is what made it skippable.
+ *
+ * @internal
+ */
+export declare function publishSlotSegmentParams(segment: ManifestSegmentNode, match: RouteMatch, destinationUrl: string, parentTreePath: string | undefined): void;
+/**
+ * Emit slot metadata for a layout whose rendering was SKIPPED.
+ *
+ * Skipped layouts never reach `resolveSlotProps`, but the client rebuilds
+ * its segment tree from each navigation's X-Timber-Segments response. If
+ * skipped slots are absent, the client loses their contentKeys and can't
+ * advertise them on the next navigation — breaking key-based slot skipping.
+ *
+ * This computes contentKey and isRequestDependent for each slot without
+ * rendering anything, using the same derivation as `resolveSlotProps`.
+ */
+export declare function emitSlotInfoForSkippedLayout(segment: ManifestSegmentNode, segmentId: string, match: RouteMatch, destinationUrl: string, slotSkipInfo: SlotSkipEntry[]): void;
+interface ResolveSlotPropsArgs {
+    segment: ManifestSegmentNode;
+    segmentId: string;
+    match: RouteMatch;
+    h: CreateElementFn;
+    interception?: InterceptionContext;
+    parentTreePath: string;
+    /** The request being rendered. Its URL is the slot-matching destination. */
+    req: Request;
+    clientStateTree: ClientStateTree | null;
+    slotSkipInfo: SlotSkipEntry[];
+}
+/**
+ * Resolve all parallel route slots for a layout, wrapping each in a
+ * SegmentOutlet for client-side caching. Slots whose content key matches
+ * one the client advertised are rendered with `skip=true` so the client
+ * keeps its cached content.
+ *
+ * The skip decision is key-based (TIM-1370): the server computes a content
+ * key per slot from the owning segment's URL parts, the slot name, the
+ * matched entry file, and the slot's own params. The client advertises
+ * the keys it has cached; the server checks membership. This replaces
+ * the previous approach of reconstructing the client's state from a
+ * departing URL.
+ */
+export declare function resolveSlotProps({ segment, segmentId, match, h, interception, parentTreePath, req, clientStateTree, slotSkipInfo, }: ResolveSlotPropsArgs): Promise<Record<string, unknown>>;
 export {};
 //# sourceMappingURL=slot-resolver.d.ts.map

package/dist/server/slot-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAElE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,EACzD,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAkKpC"}
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"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"}