@timber-js/app 0.1.0

package/dist/server/action-client.d.ts

@@ -0,0 +1,190 @@
+/**
+ * createActionClient — typed middleware and schema validation for server actions.
+ *
+ * Inspired by next-safe-action. Provides a builder API:
+ *   createActionClient({ middleware }) → .schema(z.object(...)) → .action(fn)
+ *
+ * The resulting action function satisfies both:
+ *   1. Direct call: action(input) → Promise<ActionResult>
+ *   2. React useActionState: (prevState, formData) => Promise<ActionResult>
+ *
+ * See design/08-forms-and-actions.md §"Middleware for Server Actions"
+ */
+/**
+ * Typed error class for server actions. Carries a string code and optional data.
+ * When thrown from middleware or the action body, the action short-circuits and
+ * the client receives `result.serverError`.
+ *
+ * In production, unexpected errors (non-ActionError) return `{ code: 'INTERNAL_ERROR' }`
+ * with no message. In dev, `data.message` is included.
+ */
+export declare class ActionError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly data: Record<string, unknown> | undefined;
+    constructor(code: TCode, data?: Record<string, unknown>);
+}
+/**
+ * Standard Schema v1 interface (subset).
+ * Zod ≥3.24, Valibot ≥1.0, and ArkType all implement this.
+ * See https://github.com/standard-schema/standard-schema
+ *
+ * We use permissive types here to accept all compliant libraries without
+ * requiring exact structural matches on issues/path shapes.
+ */
+interface StandardSchemaV1<Output = unknown> {
+    '~standard': {
+        validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
+type StandardSchemaResult<Output> = {
+    value: Output;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: ReadonlyArray<StandardSchemaIssue>;
+};
+interface StandardSchemaIssue {
+    message: string;
+    path?: ReadonlyArray<PropertyKey | {
+        key: PropertyKey;
+    }>;
+}
+/**
+ * Minimal schema interface — compatible with Zod, Valibot, ArkType, etc.
+ *
+ * Accepts either:
+ * - Standard Schema (preferred): any object with `~standard.validate()`
+ * - Legacy parse interface: objects with `.parse()` / `.safeParse()`
+ *
+ * At runtime, Standard Schema is detected via `~standard` property and
+ * takes priority over the legacy interface.
+ */
+export type ActionSchema<T = unknown> = StandardSchemaV1<T> | LegacyActionSchema<T>;
+/** Legacy schema interface with .parse() / .safeParse(). */
+interface LegacyActionSchema<T = unknown> {
+    'parse'(data: unknown): T;
+    'safeParse'?(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: SchemaError;
+    };
+    '~standard'?: never;
+}
+/** Schema validation error shape (for legacy .safeParse()/.parse() interface). */
+export interface SchemaError {
+    issues?: Array<{
+        path?: Array<string | number>;
+        message: string;
+    }>;
+    flatten?(): {
+        fieldErrors: Record<string, string[]>;
+    };
+}
+/** Flattened validation errors keyed by field name. */
+export type ValidationErrors = Record<string, string[]>;
+/** Middleware function: returns context to merge into the action body's ctx. */
+export type ActionMiddleware<TCtx = Record<string, unknown>> = () => Promise<TCtx> | TCtx;
+/** The result type returned to the client. */
+export type ActionResult<TData = unknown> = {
+    data: TData;
+    validationErrors?: never;
+    serverError?: never;
+    submittedValues?: never;
+} | {
+    data?: never;
+    validationErrors: ValidationErrors;
+    serverError?: never;
+    /** Raw input values on validation failure — for repopulating form fields. */
+    submittedValues?: Record<string, unknown>;
+} | {
+    data?: never;
+    validationErrors?: never;
+    serverError: {
+        code: string;
+        data?: Record<string, unknown>;
+    };
+    submittedValues?: never;
+};
+/** Context passed to the action body. */
+export interface ActionContext<TCtx, TInput> {
+    ctx: TCtx;
+    input: TInput;
+}
+interface ActionClientConfig<TCtx> {
+    middleware?: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[];
+    /** Max file size in bytes. Files exceeding this are rejected with validation errors. */
+    fileSizeLimit?: number;
+}
+/** Intermediate builder returned by createActionClient(). */
+export interface ActionBuilder<TCtx> {
+    /** Declare the input schema. Validation errors are returned typed. */
+    schema<TInput>(schema: ActionSchema<TInput>): ActionBuilderWithSchema<TCtx, TInput>;
+    /** Define the action body without input validation. */
+    action<TData>(fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>): ActionFn<TData>;
+}
+/** Builder after .schema() has been called. */
+export interface ActionBuilderWithSchema<TCtx, TInput> {
+    /** Define the action body with validated input. */
+    action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData>;
+}
+/**
+ * The final action function. Callable two ways:
+ * - Direct: action(input) → Promise<ActionResult<TData>>
+ * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>
+ */
+export type ActionFn<TData> = {
+    (input?: unknown): Promise<ActionResult<TData>>;
+    (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;
+};
+/**
+ * Wrap unexpected errors into a safe server error result.
+ * ActionError → typed result. Other errors → INTERNAL_ERROR (no leak).
+ *
+ * Exported for use by action-handler.ts to catch errors from raw 'use server'
+ * functions that don't use createActionClient.
+ */
+export declare function handleActionError(error: unknown): ActionResult<never>;
+/**
+ * Create a typed action client with middleware and schema validation.
+ *
+ * @example
+ * ```ts
+ * const action = createActionClient({
+ *   middleware: async () => {
+ *     const user = await getUser()
+ *     if (!user) throw new ActionError('UNAUTHORIZED')
+ *     return { user }
+ *   },
+ * })
+ *
+ * export const createTodo = action
+ *   .schema(z.object({ title: z.string().min(1) }))
+ *   .action(async ({ input, ctx }) => {
+ *     await db.todos.create({ ...input, userId: ctx.user.id })
+ *   })
+ * ```
+ */
+export declare function createActionClient<TCtx = Record<string, never>>(config?: ActionClientConfig<TCtx>): ActionBuilder<TCtx>;
+/**
+ * Convenience wrapper for the common case: validate input, run handler.
+ * No middleware needed.
+ *
+ * @example
+ * ```ts
+ * 'use server'
+ * import { validated } from '@timber/app/server'
+ * import { z } from 'zod'
+ *
+ * export const createTodo = validated(
+ *   z.object({ title: z.string().min(1) }),
+ *   async (input) => {
+ *     await db.todos.create(input)
+ *   }
+ * )
+ * ```
+ */
+export declare function validated<TInput, TData>(schema: ActionSchema<TInput>, handler: (input: TInput) => Promise<TData>): ActionFn<TData>;
+export {};
+//# sourceMappingURL=action-client.d.ts.map

package/dist/server/action-client.d.ts.map

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

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

@@ -0,0 +1,48 @@
+/**
+ * Server Action Request Handler — dispatches incoming action POST requests.
+ *
+ * Handles both JS-enabled (RSC) and no-JS (HTML form POST) action submissions.
+ * Wired into the RSC entry to intercept action requests before the render pipeline.
+ *
+ * Flow:
+ * 1. Detect action request (POST with `x-rsc-action` header or form action fields)
+ * 2. CSRF validation
+ * 3. Load and execute the server action
+ * 4. Return RSC stream (with-JS) or 302 redirect (no-JS)
+ *
+ * See design/08-forms-and-actions.md
+ */
+import { type CsrfConfig } from './csrf.js';
+import { type RevalidateRenderer } from './actions.js';
+import { type BodyLimitsConfig } from './body-limits.js';
+import type { FormFlashData } from './form-flash.js';
+/** Configuration for the action handler. */
+export interface ActionDispatchConfig {
+    /** CSRF configuration. */
+    csrf: CsrfConfig;
+    /** Renderer for revalidatePath — produces RSC flight payloads. */
+    revalidateRenderer?: RevalidateRenderer;
+    /** Body size limits (from timber.config.ts). */
+    bodyLimits?: BodyLimitsConfig;
+}
+/**
+ * Check if a request is a server action invocation.
+ *
+ * Two cases:
+ * - With JS: POST with `x-rsc-action` header (client callServer dispatch)
+ * - Without JS: POST with form data containing `$ACTION_REF` or `$ACTION_KEY`
+ *   (React's progressive enhancement hidden fields)
+ */
+export declare function isActionRequest(req: Request): boolean;
+/** Signal from handleFormAction to re-render the page with flash data instead of redirecting. */
+export interface FormRerender {
+    rerender: FormFlashData;
+}
+/**
+ * Handle a server action request.
+ *
+ * Returns a Response, a FormRerender signal (for no-JS validation failure re-render),
+ * or null if this isn't actually an action request (e.g., a regular form POST to an API route).
+ */
+export declare function handleActionRequest(req: Request, config: ActionDispatchConfig): Promise<Response | FormRerender | null>;
+//# sourceMappingURL=action-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action-handler.d.ts","sourceRoot":"","sources":["../../src/server/action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAarD;AAID,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAwCzC"}

package/dist/server/actions.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Server action primitives: revalidatePath, revalidateTag, and the action handler.
+ *
+ * - revalidatePath(path) re-renders the route at that path and returns the RSC
+ *   flight payload for inline reconciliation.
+ * - revalidateTag(tag) invalidates cached shells and 'use cache' entries by tag.
+ *
+ * Both are callable from anywhere on the server — actions, API routes, handlers.
+ *
+ * The action handler processes incoming action requests, validates CSRF,
+ * enforces body limits, executes the action, and returns the response
+ * (with piggybacked RSC payload if revalidatePath was called).
+ *
+ * See design/08-forms-and-actions.md
+ */
+import type { CacheHandler } from '#/cache/index';
+/** Result of rendering a revalidation — element tree before RSC serialization. */
+export interface RevalidationResult {
+    /** React element tree (pre-serialization — passed to renderToReadableStream). */
+    element: unknown;
+    /** Resolved head elements for metadata. */
+    headElements: unknown[];
+}
+/** Renderer function that builds a React element tree for a given path. */
+export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
+/** Per-request revalidation state — tracks revalidatePath/Tag calls within an action. */
+export interface RevalidationState {
+    /** Paths to re-render (populated by revalidatePath calls). */
+    paths: string[];
+    /** Tags to invalidate (populated by revalidateTag calls). */
+    tags: string[];
+}
+/** Options for creating the action handler. */
+export interface ActionHandlerConfig {
+    /** Cache handler for tag invalidation. */
+    cacheHandler?: CacheHandler;
+    /** Renderer for producing RSC payloads during revalidation. */
+    renderer?: RevalidateRenderer;
+}
+/** Result of handling a server action request. */
+export interface ActionHandlerResult {
+    /** The action's return value (serialized). */
+    actionResult: unknown;
+    /** Revalidation result if revalidatePath was called (element tree, not yet serialized). */
+    revalidation?: RevalidationResult;
+    /** Redirect location if a RedirectSignal was thrown during revalidation. */
+    redirectTo?: string;
+    /** Redirect status code. */
+    redirectStatus?: number;
+}
+/**
+ * Set the revalidation state for the current action execution.
+ * @internal — kept for test compatibility; prefer executeAction() which uses ALS.
+ */
+export declare function _setRevalidationState(state: RevalidationState): void;
+/**
+ * Clear the revalidation state after action execution.
+ * @internal — kept for test compatibility.
+ */
+export declare function _clearRevalidationState(): void;
+/**
+ * Re-render the route at `path` and include the RSC flight payload in the
+ * action response. The client reconciles inline — no separate fetch needed.
+ *
+ * Can be called from server actions, API routes, or any server-side context.
+ *
+ * @param path - The path to re-render (e.g. '/dashboard', '/todos').
+ */
+export declare function revalidatePath(path: string): void;
+/**
+ * Invalidate all pre-rendered shells and 'use cache' entries tagged with `tag`.
+ * Does not return a payload — the next request for an invalidated route re-renders fresh.
+ *
+ * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
+ */
+export declare function revalidateTag(tag: string): void;
+/**
+ * Execute a server action and process revalidation.
+ *
+ * 1. Sets up revalidation state
+ * 2. Calls the action function
+ * 3. Processes revalidateTag calls (invalidates cache entries)
+ * 4. Processes revalidatePath calls (re-renders and captures RSC payload)
+ * 5. Returns the action result + optional RSC payload
+ *
+ * @param actionFn - The server action function to execute.
+ * @param args - Arguments to pass to the action.
+ * @param config - Handler configuration (cache handler, renderer).
+ */
+export declare function executeAction(actionFn: (...args: unknown[]) => Promise<unknown>, args: unknown[], config?: ActionHandlerConfig, spanMeta?: {
+    actionFile?: string;
+    actionName?: string;
+}): Promise<ActionHandlerResult>;
+/**
+ * Build an HTTP Response for a no-JS form submission.
+ * Standard POST → 302 redirect pattern.
+ *
+ * @param redirectPath - Where to redirect after the action executes.
+ */
+export declare function buildNoJsResponse(redirectPath: string, status?: number): Response;
+/**
+ * Detect whether the incoming request is an RSC action request (with JS)
+ * or a plain HTML form POST (no JS).
+ *
+ * RSC action requests use Accept: text/x-component or Content-Type: text/x-component.
+ */
+export declare function isRscActionRequest(req: Request): boolean;
+//# sourceMappingURL=actions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/server/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAMlD,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAE/E,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAmBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK/C;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,GAAE,mBAAwB,EAChC,QAAQ,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,mBAAmB,CAAC,CA0D9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,QAAQ,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIxD"}

package/dist/server/asset-headers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Static asset cache header utilities.
+ *
+ * Hashed assets (e.g. /assets/layout-abc123.css) are immutable — the hash
+ * changes when content changes. These get long-lived cache headers:
+ *   Cache-Control: public, max-age=31536000, immutable
+ *
+ * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
+ *   Cache-Control: public, max-age=3600, must-revalidate
+ *
+ * This is applied automatically by the framework for static assets served
+ * from the build output. Page responses are NOT affected — those are
+ * controlled by the developer via middleware.ts or proxy.ts.
+ *
+ * Design docs: 18-build-system.md, 06-caching.md
+ */
+/** Cache-Control value for hashed (immutable) assets. */
+export declare const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+/** Cache-Control value for unhashed static assets. */
+export declare const STATIC_CACHE = "public, max-age=3600, must-revalidate";
+/**
+ * Check if a URL path looks like a hashed asset.
+ */
+export declare function isHashedAsset(pathname: string): boolean;
+/**
+ * Get the appropriate Cache-Control header for a static asset path.
+ *
+ * Returns `immutable` for hashed assets, short-lived for unhashed.
+ */
+export declare function getAssetCacheControl(pathname: string): string;
+/**
+ * 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 declare function generateHeadersFile(): string;
+//# sourceMappingURL=asset-headers.d.ts.map

package/dist/server/asset-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-headers.d.ts","sourceRoot":"","sources":["../../src/server/asset-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH,yDAAyD;AACzD,eAAO,MAAM,eAAe,wCAA2C,CAAC;AAExE,sDAAsD;AACtD,eAAO,MAAM,YAAY,0CAAiD,CAAC;AAE3E;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAU5C"}

package/dist/server/body-limits.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Request body size limits — returns 413 when exceeded.
+ * See design/08-forms-and-actions.md §"FormData Limits"
+ */
+export interface BodyLimitsConfig {
+    limits?: {
+        actionBodySize?: string;
+        uploadBodySize?: string;
+        maxFields?: number;
+    };
+}
+export type BodyLimitResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 411 | 413;
+};
+export type BodyKind = 'action' | 'upload';
+export declare const DEFAULT_LIMITS: {
+    readonly actionBodySize: number;
+    readonly uploadBodySize: number;
+    readonly maxFields: 100;
+};
+/** Parse a human-readable size string ("1mb", "512kb", "1024") into bytes. */
+export declare function parseBodySize(size: string): number;
+/** Check whether a request body exceeds the configured size limit (stateless, no ALS). */
+export declare function enforceBodyLimits(req: Request, kind: BodyKind, config: BodyLimitsConfig): BodyLimitResult;
+/** Check whether a FormData payload exceeds the configured field count limit. */
+export declare function enforceFieldLimit(formData: FormData, config: BodyLimitsConfig): BodyLimitResult;
+//# sourceMappingURL=body-limits.d.ts.map

package/dist/server/body-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-limits.d.ts","sourceRoot":"","sources":["../../src/server/body-limits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAA;CAAE,CAAC;AAE9E,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAM3C,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAIX,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBlD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,gBAAgB,GACvB,eAAe,CAejB;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAM/F"}

package/dist/server/build-manifest.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Build manifest types and utilities for CSS and JS asset tracking.
+ *
+ * The build manifest maps route segment file paths to their output
+ * chunks from Vite's client build. This enables:
+ * - <link rel="stylesheet"> injection in HTML <head>
+ * - <script type="module"> with hashed URLs in production
+ * - <link rel="modulepreload"> for client chunk dependencies
+ * - Link preload headers for Early Hints (103)
+ *
+ * In dev mode, Vite's HMR client handles CSS/JS injection, so the build
+ * manifest is empty. In production, it's populated from Vite's
+ * .vite/manifest.json after the client build.
+ *
+ * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
+ */
+/** A font asset entry in the build manifest. */
+export interface ManifestFontEntry {
+    /** URL path to the font file (e.g. `/_timber/fonts/inter-latin-400-abc123.woff2`). */
+    href: string;
+    /** Font format (e.g. `woff2`). */
+    format: string;
+    /** Crossorigin attribute — always `anonymous` for fonts. */
+    crossOrigin: string;
+}
+/** Build manifest mapping input file paths to output asset URLs. */
+export interface BuildManifest {
+    /** Map from input file path (relative to project root) to output CSS URLs. */
+    css: Record<string, string[]>;
+    /** Map from input file path to output JS chunk URL (hashed filename). */
+    js: Record<string, string>;
+    /** Map from input file path to transitive JS dependency URLs for modulepreload. */
+    modulepreload: Record<string, string[]>;
+    /** Map from input file path to font assets used by that module. */
+    fonts: Record<string, ManifestFontEntry[]>;
+}
+/** Empty build manifest used in dev mode. */
+export declare const EMPTY_BUILD_MANIFEST: BuildManifest;
+/** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */
+interface SegmentWithFiles {
+    layout?: {
+        filePath: string;
+    };
+    page?: {
+        filePath: string;
+    };
+}
+/**
+ * Collect all CSS files needed for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting CSS for each layout and page.
+ * Deduplicates while preserving order (root layout CSS first).
+ */
+export declare function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildManifest): string[];
+/**
+ * Generate <link rel="stylesheet"> tags for CSS URLs.
+ *
+ * Returns an HTML string to prepend to headHtml for injection
+ * via injectHead() before </head>.
+ */
+export declare function buildCssLinkTags(cssUrls: string[]): string;
+/**
+ * Generate a Link header value for CSS preload hints.
+ *
+ * Cloudflare CDN automatically converts Link headers with rel=preload
+ * 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`
+ */
+export declare function buildLinkHeaders(cssUrls: string[]): string;
+/**
+ * Collect all font entries needed for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting fonts for each layout and page.
+ * Deduplicates by href while preserving order.
+ */
+export declare function collectRouteFonts(segments: SegmentWithFiles[], manifest: BuildManifest): ManifestFontEntry[];
+/**
+ * Generate <link rel="preload"> tags for font assets.
+ *
+ * Font preloads use `as=font` and always include `crossorigin` (required
+ * for font preloads even for same-origin resources per the spec).
+ */
+export declare function buildFontPreloadTags(fonts: ManifestFontEntry[]): string;
+/**
+ * Generate Link header values for font preload hints.
+ *
+ * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
+ *
+ * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ */
+export declare function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string;
+/**
+ * Collect JS chunk URLs for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting the JS chunk for each layout
+ * and page. Deduplicates while preserving order.
+ */
+export declare function collectRouteJs(segments: SegmentWithFiles[], manifest: BuildManifest): string[];
+/**
+ * Collect modulepreload URLs for a matched route's segment chain.
+ *
+ * Walks segments root → leaf, collecting transitive JS dependencies
+ * for each layout and page. Deduplicates across segments.
+ */
+export declare function collectRouteModulepreloads(segments: SegmentWithFiles[], manifest: BuildManifest): string[];
+/**
+ * Generate <link rel="modulepreload"> tags for JS dependency URLs.
+ *
+ * Modulepreload hints tell the browser to fetch and parse JS modules
+ * before they're needed, reducing waterfall latency for dynamic imports.
+ */
+export declare function buildModulepreloadTags(urls: string[]): string;
+/**
+ * Generate a <script type="module"> tag for a JS entry point.
+ */
+export declare function buildEntryScriptTag(url: string): string;
+export {};
+//# sourceMappingURL=build-manifest.d.ts.map

package/dist/server/build-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-manifest.d.ts","sourceRoot":"","sources":["../../src/server/build-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;CAC5C;AAED,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB,EAAE,aAKlC,CAAC;AAEF,+EAA+E;AAC/E,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAmB/F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1D;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,QAAQ,EAAE,aAAa,GACtB,iBAAiB,EAAE,CAmBrB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAOvE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAEvE;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAiB9F;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,QAAQ,EAAE,aAAa,GACtB,MAAM,EAAE,CAmBV;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/server/canonicalize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * URL canonicalization — runs once at the request boundary.
+ *
+ * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same
+ * canonical path. No re-decoding occurs at any later stage.
+ *
+ * See design/07-routing.md §"URL Canonicalization & Security"
+ */
+/** Result of canonicalization — either a clean path or a rejection. */
+export type CanonicalizeResult = {
+    ok: true;
+    pathname: string;
+} | {
+    ok: false;
+    status: 400;
+};
+/**
+ * Canonicalize a URL pathname.
+ *
+ * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)
+ * 2. Single percent-decode
+ * 3. Collapse // → /
+ * 4. Resolve .. segments (reject if escaping root)
+ * 5. Strip trailing slash (except root "/")
+ *
+ * @param rawPathname - The raw pathname from the request URL (percent-encoded)
+ * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.
+ */
+export declare function canonicalize(rawPathname: string, stripTrailingSlash?: boolean): CanonicalizeResult;
+//# sourceMappingURL=canonicalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.d.ts","sourceRoot":"","sources":["../../src/server/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAW7F;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,UAAO,GAAG,kBAAkB,CAwD/F"}

package/dist/server/client-module-map.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Client module map — maps client reference IDs to their SSR module loaders.
+ *
+ * When the RSC stream contains a client component reference (from a
+ * "use client" module), the SSR environment needs to resolve it to the
+ * actual component module so it can render the component to HTML.
+ *
+ * The @vitejs/plugin-rsc SSR runtime handles this internally via its
+ * setRequireModule hook — it imports client reference modules from the
+ * SSR environment's module graph. This module provides the configuration
+ * bridge between timber's entry system and the RSC plugin's runtime.
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
+ */
+/**
+ * Client reference metadata used during SSR to resolve client components.
+ *
+ * The RSC plugin tracks these internally via `clientReferenceMetaMap`.
+ * At SSR time, when `createFromReadableStream` encounters a client
+ * reference in the RSC payload, it uses the module map to import the
+ * actual component for server-side HTML rendering.
+ */
+export interface ClientModuleEntry {
+    /** The module ID (Vite-resolved file path) */
+    id: string;
+    /** The export name (e.g., 'default', 'Counter') */
+    name: string;
+    /** Async module loader */
+    load: () => Promise<Record<string, unknown>>;
+}
+/**
+ * Create a client module map for SSR resolution.
+ *
+ * In dev mode, the RSC plugin's SSR runtime (`@vitejs/plugin-rsc/ssr`)
+ * handles client reference resolution automatically via its initialize()
+ * function which sets up `setRequireModule` with dynamic imports through
+ * Vite's dev server. No explicit module map is needed.
+ *
+ * In production builds, the RSC plugin generates a `virtual:vite-rsc/client-references`
+ * module that maps client reference IDs to their chunk imports. The SSR
+ * runtime reads this at startup.
+ *
+ * This function returns an empty map as a placeholder — the actual
+ * resolution is handled by the RSC plugin's runtime internals.
+ */
+export declare function createClientModuleMap(): Record<string, ClientModuleEntry>;
+//# sourceMappingURL=client-module-map.d.ts.map

package/dist/server/client-module-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-module-map.d.ts","sourceRoot":"","sources":["../../src/server/client-module-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAUzE"}