@timber-js/app 0.1.0

package/dist/server/primitives.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Render-phase signal thrown by `deny()`. Caught by the framework to produce
+ * the correct HTTP status code (segment context) or graceful degradation (slot context).
+ */
+export declare class DenySignal extends Error {
+    readonly status: number;
+    readonly data: unknown;
+    constructor(status: number, data?: unknown);
+    /**
+     * Extract the file that called deny() from the stack trace.
+     * Returns a short path (e.g. "app/auth/access.ts") or undefined if
+     * the stack can't be parsed. Dev-only — used for dev log output.
+     */
+    get sourceFile(): string | undefined;
+}
+/**
+ * Universal denial primitive. Throws a `DenySignal` that the framework catches.
+ *
+ * - In segment context (outside Suspense): produces HTTP status code
+ * - In slot context: graceful degradation → denied.tsx → default.tsx → null
+ * - Inside Suspense (hold window): promoted to pre-flush behavior
+ * - Inside Suspense (after flush): error boundary + noindex meta
+ *
+ * @param status - Any 4xx HTTP status code. Defaults to 403.
+ * @param data - Optional data passed as `dangerouslyPassData` prop to status-code files.
+ */
+export declare function deny(status?: number, data?: unknown): never;
+/**
+ * Convenience alias for `deny(404)`.
+ *
+ * Provided for Next.js API compatibility — libraries and user code that
+ * call `notFound()` from `next/navigation` get the same behavior as
+ * `deny(404)` in timber.
+ */
+export declare function notFound(): never;
+/**
+ * Next.js redirect type discriminator.
+ *
+ * Provided for API compatibility with libraries that import `RedirectType`
+ * from `next/navigation`. In timber, `redirect()` always uses `replace`
+ * semantics (no history entry for the redirect itself).
+ */
+export declare const RedirectType: {
+    readonly push: "push";
+    readonly replace: "replace";
+};
+/**
+ * Render-phase signal thrown by `redirect()` and `redirectExternal()`.
+ * Caught by the framework to produce a 3xx response or client-side navigation.
+ */
+export declare class RedirectSignal extends Error {
+    readonly location: string;
+    readonly status: number;
+    constructor(location: string, status: number);
+}
+/**
+ * Redirect to a relative path. Rejects absolute and protocol-relative URLs.
+ * Use `redirectExternal()` for external redirects with an allow-list.
+ *
+ * @param path - Relative path (e.g. '/login', 'settings', '/login?returnTo=/dash')
+ * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ */
+export declare function redirect(path: string, status?: number): never;
+/**
+ * Permanent redirect to a relative path. Shorthand for `redirect(path, 308)`.
+ *
+ * Uses 308 (Permanent Redirect) which preserves the HTTP method — the browser
+ * will replay POST requests to the new location. This matches Next.js behavior.
+ *
+ * @param path - Relative path (e.g. '/new-page', '/dashboard')
+ */
+export declare function permanentRedirect(path: string): never;
+/**
+ * Redirect to an external URL. The hostname must be in the provided allow-list.
+ *
+ * @param url - Absolute URL to redirect to.
+ * @param allowList - Array of allowed hostnames (e.g. ['example.com', 'auth.example.com']).
+ * @param status - HTTP redirect status code (3xx). Defaults to 302.
+ */
+export declare function redirectExternal(url: string, allowList: string[], status?: number): never;
+/**
+ * Typed digest that crosses the RSC → client boundary.
+ * The `code` identifies the error class; `data` carries JSON-serializable context.
+ */
+export interface RenderErrorDigest<TCode extends string = string, TData = unknown> {
+    code: TCode;
+    data: TData;
+}
+/**
+ * Typed throw for render-phase errors that carry structured context to error boundaries.
+ *
+ * The `digest` (code + data) is serialized into the RSC stream separately from the
+ * Error instance — only the digest crosses the RSC → client boundary.
+ *
+ * @example
+ * ```ts
+ * throw new RenderError('PRODUCT_NOT_FOUND', {
+ *   title: 'Product not found',
+ *   resourceId: params.id,
+ * })
+ * ```
+ */
+export declare class RenderError<TCode extends string = string, TData = unknown> extends Error {
+    readonly code: TCode;
+    readonly digest: RenderErrorDigest<TCode, TData>;
+    readonly status: number;
+    constructor(code: TCode, data: TData, options?: {
+        status?: number;
+    });
+}
+/** Minimal interface for adapters that support background work. */
+export interface WaitUntilAdapter {
+    waitUntil?(promise: Promise<unknown>): void;
+}
+/**
+ * Register a promise to be kept alive after the response is sent.
+ * Maps to `ctx.waitUntil()` on Cloudflare Workers and similar platforms.
+ *
+ * If the adapter does not support `waitUntil`, a warning is logged once
+ * and the promise is left to resolve (or reject) without being tracked.
+ *
+ * @param promise - The background work to keep alive.
+ * @param adapter - The platform adapter (injected by the framework at runtime).
+ */
+export declare function waitUntil(promise: Promise<unknown>, adapter: WaitUntilAdapter): void;
+/**
+ * Reset the waitUntil warning state. Exported for testing only.
+ * @internal
+ */
+export declare function _resetWaitUntilWarning(): void;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/server/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/server/primitives.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAO1C;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAqBnC;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,MAAY,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,KAAK,CAQhE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAEhC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAIX;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAKD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,MAAY,GAAG,KAAK,CAoB9F;AAID;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,GAAG,OAAO;IAC/E,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,GAAG,OAAO,CAAE,SAAQ,KAAK;IACpF,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAYpE;AAID,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAapF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/server/proxy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Proxy runner — executes app/proxy.ts before route matching.
+ *
+ * Supports two forms:
+ * - Function: (req, next) => Promise<Response>
+ * - Array: middleware functions composed left-to-right
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware"
+ */
+/** Signature for a single proxy middleware function. */
+export type ProxyFn = (req: Request, next: () => Promise<Response>) => Response | Promise<Response>;
+/** The proxy.ts default export — either a function or an array of functions. */
+export type ProxyExport = ProxyFn | ProxyFn[];
+/**
+ * Run the proxy pipeline.
+ *
+ * @param proxyExport - The default export from proxy.ts (function or array)
+ * @param req - The incoming request
+ * @param next - The continuation that proceeds to route matching and rendering
+ * @returns The final response
+ */
+export declare function runProxy(proxyExport: ProxyExport, req: Request, next: () => Promise<Response>): Promise<Response>;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/server/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/server/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wDAAwD;AACxD,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEpG,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,EAAE,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,WAAW,EACxB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAcnB"}

package/dist/server/request-context.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Request Context — per-request ALS store for headers() and cookies().
+ *
+ * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage
+ * instance, public accessor functions that throw outside request scope,
+ * and a framework-internal `runWithRequestContext()` to establish scope.
+ *
+ * See design/04-authorization.md §"AccessContext does not include cookies or headers"
+ * and design/11-platform.md §"AsyncLocalStorage".
+ * See design/29-cookies.md for cookie mutation semantics.
+ */
+import type { Routes } from '#/index.js';
+/**
+ * Configure the cookie signing secrets.
+ *
+ * Called by the framework during server initialization with values from
+ * `cookies.secret` or `cookies.secrets` in timber.config.ts.
+ *
+ * The first secret (index 0) is used for signing new cookies.
+ * All secrets are tried for verification (supports key rotation).
+ */
+export declare function setCookieSecrets(secrets: string[]): void;
+/**
+ * Returns a read-only view of the current request's headers.
+ *
+ * Available in middleware, access checks, server components, and server actions.
+ * Throws if called outside a request context (security principle #2: no global fallback).
+ */
+export declare function headers(): ReadonlyHeaders;
+/**
+ * Returns a cookie accessor for the current request.
+ *
+ * Available in middleware, access checks, server components, and server actions.
+ * Throws if called outside a request context (security principle #2: no global fallback).
+ *
+ * Read methods (.get, .has, .getAll) are always available and reflect
+ * read-your-own-writes from .set() calls in the same request.
+ *
+ * Mutation methods (.set, .delete, .clear) are only available in mutable
+ * contexts (middleware.ts, server actions, route.ts handlers). Calling them
+ * in read-only contexts (access.ts, server components) throws.
+ *
+ * See design/29-cookies.md
+ */
+export declare function cookies(): RequestCookies;
+/**
+ * Returns a Promise resolving to the current request's search params.
+ *
+ * In `page.tsx`, `middleware.ts`, and `access.ts` the framework pre-parses the
+ * route's `search-params.ts` definition and the Promise resolves to the typed
+ * object. In all other server component contexts it resolves to raw
+ * `URLSearchParams`.
+ *
+ * Returned as a Promise to match the `params` prop convention and to allow
+ * future partial pre-rendering support where param resolution may be deferred.
+ *
+ * Throws if called outside a request context.
+ */
+export declare function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>;
+export declare function searchParams(): Promise<URLSearchParams | Record<string, unknown>>;
+/**
+ * Replace the search params Promise for the current request with one that
+ * resolves to the typed parsed result from the route's search-params.ts.
+ * Called by the framework before rendering the page — not for app code.
+ */
+export declare function setParsedSearchParams(parsed: Record<string, unknown>): void;
+/**
+ * Read-only Headers interface. The standard Headers class is mutable;
+ * this type narrows it to read-only methods. The underlying object is
+ * still a Headers instance, but user code should not mutate it.
+ */
+export type ReadonlyHeaders = Pick<Headers, 'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator>;
+/** Options for setting a cookie. See design/29-cookies.md. */
+export interface CookieOptions {
+    /** Domain scope. Default: omitted (current domain only). */
+    domain?: string;
+    /** URL path scope. Default: '/'. */
+    path?: string;
+    /** Expiration date. Mutually exclusive with maxAge. */
+    expires?: Date;
+    /** Max age in seconds. Mutually exclusive with expires. */
+    maxAge?: number;
+    /** Prevent client-side JS access. Default: true. */
+    httpOnly?: boolean;
+    /** Only send over HTTPS. Default: true. */
+    secure?: boolean;
+    /** Cross-site request policy. Default: 'lax'. */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */
+    partitioned?: boolean;
+    /**
+     * Sign the cookie value with HMAC-SHA256 for integrity verification.
+     * Requires `cookies.secret` or `cookies.secrets` in timber.config.ts.
+     * See design/29-cookies.md §"Signed Cookies".
+     */
+    signed?: boolean;
+}
+/**
+ * Cookie accessor returned by `cookies()`.
+ *
+ * Read methods are always available. Mutation methods throw in read-only
+ * contexts (access.ts, server components).
+ */
+export interface RequestCookies {
+    /** Get a cookie value by name. Returns undefined if not present. */
+    get(name: string): string | undefined;
+    /** Check if a cookie exists. */
+    has(name: string): boolean;
+    /** Get all cookies as an array of { name, value } pairs. */
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Number of cookies. */
+    readonly size: number;
+    /**
+     * Get a signed cookie value, verifying its HMAC-SHA256 signature.
+     * Returns undefined if the cookie is missing, the signature is invalid,
+     * or no secrets are configured. Never throws.
+     *
+     * See design/29-cookies.md §"Signed Cookies"
+     */
+    getSigned(name: string): string | undefined;
+    /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
+    set(name: string, value: string, options?: CookieOptions): void;
+    /** Delete a cookie. Only available in mutable contexts. */
+    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+    /** Delete all cookies. Only available in mutable contexts. */
+    clear(): void;
+    /** Serialize cookies as a Cookie header string. */
+    toString(): string;
+}
+/**
+ * Run a callback within a request context. Used by the pipeline to establish
+ * per-request ALS scope so that `headers()` and `cookies()` work.
+ *
+ * @param req - The incoming Request object.
+ * @param fn - The function to run within the request context.
+ */
+export declare function runWithRequestContext<T>(req: Request, fn: () => T): T;
+/**
+ * Enable cookie mutation for the current context. Called by the framework
+ * when entering middleware.ts, server actions, or route.ts handlers.
+ *
+ * See design/29-cookies.md §"Context Tracking"
+ */
+export declare function setMutableCookieContext(mutable: boolean): void;
+/**
+ * Mark the response as flushed (headers committed). After this point,
+ * cookie mutations log a warning instead of throwing.
+ *
+ * See design/29-cookies.md §"Streaming Constraint: Post-Flush Cookie Warning"
+ */
+export declare function markResponseFlushed(): void;
+/**
+ * Collect all Set-Cookie headers from the cookie jar.
+ * Called by the framework at flush time to apply cookies to the response.
+ *
+ * Returns an array of serialized Set-Cookie header values.
+ */
+export declare function getSetCookieHeaders(): string[];
+/**
+ * Apply middleware-injected request headers to the current request context.
+ *
+ * Called by the pipeline after middleware.ts runs. Merges overlay headers
+ * on top of the original request headers so downstream code (access.ts,
+ * server components, server actions) sees them via `headers()`.
+ *
+ * The original request headers are never mutated — a new frozen Headers
+ * object is created with the overlay applied on top.
+ *
+ * See design/07-routing.md §"Request Header Injection"
+ */
+export declare function applyRequestHeaderOverlay(overlay: Headers): void;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/server/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}

package/dist/server/route-element-builder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Route Element Builder — constructs a React element tree from a matched route.
+ *
+ * Extracted from rsc-entry.ts to enable reuse by the revalidation renderer
+ * (which needs the element tree without RSC serialization) and to keep
+ * rsc-entry.ts under the 500-line limit.
+ *
+ * This module handles:
+ * 1. Loading page/layout components from the segment chain
+ * 2. Running access.ts checks (DenySignal/RedirectSignal propagate to caller)
+ * 3. Resolving metadata (static object or async function, both exported as `metadata`)
+ * 4. Building the React element tree (page → error boundaries → access gates → layouts)
+ * 5. Resolving parallel slots
+ *
+ * See design/02-rendering-pipeline.md, design/04-authorization.md
+ */
+import type { RouteMatch } from './pipeline.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
+import type { InterceptionContext } from './pipeline.js';
+/** Head element for client-side metadata updates. */
+export interface HeadElement {
+    tag: string;
+    content?: string;
+    attrs?: Record<string, string | null>;
+}
+/** Layout entry with component and segment. */
+export interface LayoutComponentEntry {
+    component: (...args: unknown[]) => unknown;
+    segment: ManifestSegmentNode;
+}
+/** Result of building a route element tree. */
+export interface RouteElementResult {
+    /** The React element tree (page wrapped in layouts, access gates, error boundaries). */
+    element: React.ReactElement;
+    /** Resolved head elements for metadata. */
+    headElements: HeadElement[];
+    /** Layout components loaded along the segment chain. */
+    layoutComponents: LayoutComponentEntry[];
+    /** Segments from the route match. */
+    segments: ManifestSegmentNode[];
+    /** Max deferSuspenseFor hold window across all segments. */
+    deferSuspenseFor: number;
+}
+/**
+ * Wraps a DenySignal or RedirectSignal with the layout components loaded
+ * so far, enabling the caller to render deny pages inside the layout shell.
+ */
+export declare class RouteSignalWithContext extends Error {
+    readonly signal: DenySignal | RedirectSignal;
+    readonly layoutComponents: LayoutComponentEntry[];
+    readonly segments: ManifestSegmentNode[];
+    constructor(signal: DenySignal | RedirectSignal, layoutComponents: LayoutComponentEntry[], segments: ManifestSegmentNode[]);
+}
+/**
+ * Build a React element tree from a matched route.
+ *
+ * Loads modules, runs access checks, resolves metadata, and constructs
+ * the element tree. DenySignal and RedirectSignal propagate to the caller
+ * for HTTP-level handling.
+ *
+ * Does NOT serialize to RSC Flight — the caller decides whether to render
+ * to a stream or use the element directly (e.g., for action revalidation).
+ */
+export declare function buildRouteElement(req: Request, match: RouteMatch, interception?: InterceptionContext): Promise<RouteElementResult>;
+//# sourceMappingURL=route-element-builder.d.ts.map

package/dist/server/route-element-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAyS7B"}

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

@@ -0,0 +1,35 @@
+/**
+ * Route handler for route.ts API endpoints.
+ *
+ * route.ts files export named HTTP method handlers (GET, POST, etc.).
+ * They share the same pipeline (proxy → match → middleware → access → handler)
+ * but don't render React trees.
+ *
+ * See design/07-routing.md §"route.ts — API Endpoints"
+ */
+import type { RouteContext } from './types.js';
+/** HTTP methods that route.ts can export as named handlers. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** A single route handler function — one-arg signature. */
+export type RouteHandler = (ctx: RouteContext) => Response | Promise<Response>;
+/** A route.ts module — named exports for each supported HTTP method. */
+export type RouteModule = {
+    [K in HttpMethod]?: RouteHandler;
+};
+/**
+ * Resolve the full list of allowed methods for a route module.
+ *
+ * Includes:
+ * - All explicitly exported methods
+ * - HEAD (implicit when GET is exported)
+ * - OPTIONS (always implicit)
+ */
+export declare function resolveAllowedMethods(mod: RouteModule): HttpMethod[];
+/**
+ * Handle an incoming request against a route.ts module.
+ *
+ * Dispatches to the named method handler, auto-generates 405/OPTIONS,
+ * and merges response headers from ctx.headers.
+ */
+export declare function handleRouteRequest(mod: RouteModule, ctx: RouteContext): Promise<Response>;
+//# sourceMappingURL=route-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route-handler.d.ts","sourceRoot":"","sources":["../../src/server/route-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG;KACvB,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,YAAY;CACjC,CAAC;AAOF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAyBpE;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyC/F"}

package/dist/server/route-matcher.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Route matcher — resolves a canonical pathname to a RouteMatch.
+ *
+ * Walks the manifest segment tree to find the best matching route.
+ * Priority: static > dynamic > catch-all > optional-catch-all.
+ * Groups are transparent (don't add URL depth).
+ *
+ * See design/07-routing.md §"Request Lifecycle"
+ */
+import type { RouteMatch } from './pipeline.js';
+import { type MetadataRouteType } from './metadata-routes.js';
+/** A file reference in the manifest (lazy import + path). */
+interface ManifestFile {
+    load: () => Promise<unknown>;
+    filePath: string;
+}
+/** A segment node as it appears in the virtual:timber-route-manifest module. */
+export interface ManifestSegmentNode {
+    segmentName: string;
+    segmentType: 'static' | 'dynamic' | 'catch-all' | 'optional-catch-all' | 'group' | 'slot' | 'intercepting';
+    urlPath: string;
+    paramName?: string;
+    /** For intercepting segments: the marker used, e.g. "(.)". */
+    interceptionMarker?: '(.)' | '(..)' | '(...)' | '(..)(..)';
+    /** For intercepting segments: the segment name after stripping the marker. */
+    interceptedSegmentName?: string;
+    page?: ManifestFile;
+    layout?: ManifestFile;
+    middleware?: ManifestFile;
+    access?: ManifestFile;
+    route?: ManifestFile;
+    error?: ManifestFile;
+    default?: ManifestFile;
+    denied?: ManifestFile;
+    searchParams?: ManifestFile;
+    statusFiles?: Record<string, ManifestFile>;
+    jsonStatusFiles?: Record<string, ManifestFile>;
+    legacyStatusFiles?: Record<string, ManifestFile>;
+    prerender?: ManifestFile;
+    /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
+    metadataRoutes?: Record<string, ManifestFile>;
+    children: ManifestSegmentNode[];
+    slots: Record<string, ManifestSegmentNode>;
+}
+/** The manifest shape from virtual:timber-route-manifest. */
+export interface ManifestRoot {
+    root: ManifestSegmentNode;
+    proxy?: ManifestFile;
+}
+/**
+ * Create a route matcher function from a manifest.
+ *
+ * The returned function takes a canonical pathname and returns a RouteMatch
+ * or null if no route matches.
+ */
+export declare function createRouteMatcher(manifest: ManifestRoot): (pathname: string) => RouteMatch | null;
+/** Result of matching a metadata route. */
+export interface MetadataRouteMatch {
+    /** The metadata route type (sitemap, robots, icon, etc.) */
+    type: MetadataRouteType;
+    /** Content-Type header for the response. */
+    contentType: string;
+    /** The manifest file reference for the handler module. */
+    file: ManifestFile;
+    /** The matched segment (for context/params if needed). */
+    segment: ManifestSegmentNode;
+}
+/**
+ * Create a metadata route matcher from a manifest.
+ *
+ * Walks the segment tree and builds a map from serve paths to handler modules.
+ * Metadata routes are matched by exact pathname (e.g., /sitemap.xml, /blog/sitemap.xml).
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+export declare function createMetadataRouteMatcher(manifest: ManifestRoot): (pathname: string) => MetadataRouteMatch | null;
+export {};
+//# sourceMappingURL=route-matcher.d.ts.map

package/dist/server/route-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../../src/server/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAM9B,6DAA6D;AAC7D,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EACP,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAC3D,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE9C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC5C;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAEzC;AAsKD,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,IAAI,EAAE,iBAAiB,CAAC;IACxB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,CAMjD"}

package/dist/server/rsc-entry/api-handler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * RSC API Route Handler — handles route.ts requests (non-React).
+ *
+ * Runs access.ts standalone for all segments in the chain (no React render
+ * pass, no AccessGate component). Then dispatches to the route handler.
+ * See design/04-authorization.md §"Auth in API Routes".
+ */
+import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { RouteMatch } from '#/server/pipeline.js';
+export declare function handleApiRoute(req: Request, match: RouteMatch, segments: ManifestSegmentNode[], responseHeaders: Headers): Promise<Response>;
+//# sourceMappingURL=api-handler.d.ts.map

package/dist/server/rsc-entry/api-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-handler.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/api-handler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAMvD,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,QAAQ,CAAC,CAyDnB"}

package/dist/server/rsc-entry/error-renderer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RSC Error & No-Match Renderers — handles error pages and 404s.
+ *
+ * Renders error.tsx / status files and 404 pages through the RSC → SSR pipeline.
+ */
+import type { RouteMatch } from '#/server/pipeline.js';
+import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import type { LayoutEntry } from '#/server/deny-renderer.js';
+/**
+ * Render an error page for unhandled throws or RenderError outside Suspense.
+ *
+ * Walks the segment chain from leaf to root looking for:
+ *   1. Specific status file (e.g. 503.tsx) matching the error's status
+ *   2. 5xx.tsx category catch-all
+ *   3. error.tsx
+ *
+ * Renders the found component with { error, digest, reset } props
+ * wrapped in layouts, with the correct HTTP status code.
+ */
+export declare function renderErrorPage(error: unknown, status: number, segments: ManifestSegmentNode[], layoutComponents: LayoutEntry[], req: Request, match: RouteMatch, responseHeaders: Headers, clientBootstrap: ClientBootstrapConfig): Promise<Response>;
+/**
+ * Render a 404 page for URLs that don't match any route.
+ *
+ * Uses the root segment's 404.tsx (or 4xx.tsx / error.tsx fallback)
+ * wrapped in the root layout, via the same renderDenyPage path
+ * used for in-route deny() calls.
+ */
+export declare function renderNoMatchPage(req: Request, rootSegment: ManifestSegmentNode, responseHeaders: Headers, clientBootstrap: ClientBootstrapConfig): Promise<Response>;
+//# sourceMappingURL=error-renderer.d.ts.map

package/dist/server/rsc-entry/error-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-renderer.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/error-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAK7D;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAAC,QAAQ,CAAC,CA6FnB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,mBAAmB,EAChC,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAAC,QAAQ,CAAC,CA6BnB"}