@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/plugins/request-dep/analysis.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Per-module syntactic facts for request-dependency analysis.
+ *
+ * This module is deliberately dumb: it records *what the source says*, with no
+ * knowledge of which specifiers or names are interesting. Every judgement —
+ * "is this an accessor", "is this a definition object" — lives in `origin.ts`,
+ * which resolves a binding to the module it actually came from.
+ *
+ * That split is the point. The previous shape asked each module in isolation
+ * "do you import `getSearchParams` from `@timber-js/app/server` and call it",
+ * which any indirection defeats: a barrel re-export, a namespace import, a
+ * factory reached through the app's own `_lib`. Each of those was a separate
+ * hole and each was found separately (TIM-1291). Recording bindings and edges
+ * here, and resolving them across the graph there, closes the family instead of
+ * its members.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+import type { ProgramNode } from '../callsite-ast.ts';
+/**
+ * One module-graph edge introduced by an `import` or `export … from`.
+ *
+ * `imported` is the name as it exists in the *source* module: an export name,
+ * `'default'`, or `'*'` for a namespace/star form.
+ */
+export interface ImportEdge {
+    source: string;
+    imported: string;
+}
+/** The callee of `const x = f()` / `const x = ns.f()`. */
+export type CalleeRef = {
+    kind: 'local';
+    name: string;
+} | {
+    kind: 'member';
+    object: string;
+    property: string;
+};
+export interface ModuleFacts {
+    /** Local name → the edge that bound it (`import { a as b } from 'x'`). */
+    importedBindings: Map<string, ImportEdge>;
+    /** Exported name → edge, for `export { a as b } from 'x'`. */
+    reExports: Map<string, ImportEdge>;
+    /** Sources of anonymous `export * from 'x'`, in source order. */
+    starReExports: string[];
+    /** Exported name → local name, for `export { x }`, `export const x = …`. */
+    localExports: Map<string, string>;
+    /** Local variable name → the callee that produced its value. */
+    factoryCalls: Map<string, CalleeRef>;
+    /** Local names invoked directly: `f()`. */
+    calledLocals: Set<string>;
+    /** `ns.f()` → `ns` → `{ f }`. */
+    calledMembers: Map<string, Set<string>>;
+    /** Base identifier of a `.get()` chain: `x.get()`, `x().get()`, `x.p.get()`. */
+    getterLocals: Set<string>;
+    /** `ns.defs.get()` → `ns` → `{ defs }`. */
+    getterMembers: Map<string, Set<string>>;
+    /** Every name the module *body* mentions — import/export clauses excluded. */
+    referencedLocals: Set<string>;
+    /** Specifier → resolved module id, filled by the plugin via `this.resolve`. */
+    resolvedSources: Map<string, string>;
+    /** Specifiers that failed to resolve — treated as request-dependent. */
+    unresolvedSources: Set<string>;
+}
+/** `export default` has no local name of its own; this stands in for one. */
+export declare const DEFAULT_EXPORT = "default";
+export declare function createModuleFacts(): ModuleFacts;
+/**
+ * Specifiers the origin walk can actually reach, so the plugin resolves those
+ * and not every import in the file.
+ *
+ * A re-export edge is always reachable — a downstream module can ask for any
+ * name it forwards. An `import` edge is reachable through any local name the
+ * module body mentions, or that it re-exports.
+ *
+ * The name set must be **the same one the taint rules consult**. Deriving it
+ * from the call shapes instead (called, `.get()`d, member-called, minted from)
+ * left `read(filters)` — a definition passed as an argument — with its
+ * specifier unresolved, so the origin walk reported it inert and the page read
+ * as request-independent. Two hand-maintained lists of "names that matter" is
+ * one list too many; this is the one, and `referencedLocals` is a superset of
+ * every call shape by construction, since each of them is an identifier the
+ * walk visits. (Codex review round 1 on PR #991.)
+ */
+export declare function usedSources(facts: ModuleFacts): Set<string>;
+/**
+ * True when the module cannot affect any answer, so its facts need not be kept.
+ *
+ * Every judgement bottoms out at a module edge: a call site resolves through
+ * `importedBindings`, a chain link through `reExports` / `starReExports`. A
+ * module with none of those can only ever resolve to `none` — its exports lead
+ * to locals that lead nowhere — which is exactly what a *missing* entry
+ * produces. Dropping it is behaviour-preserving and keeps the dev-time map from
+ * holding an entry for every leaf module in the graph.
+ */
+export declare function contributesNothing(facts: ModuleFacts): boolean;
+/**
+ * Record every binding, module edge, and call shape in one module.
+ *
+ * Names are recorded without scope analysis, so a parameter that shadows an
+ * imported name is credited to the import. That direction is deliberate: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ */
+export declare function analyzeModule(program: ProgramNode): ModuleFacts;
+//# sourceMappingURL=analysis.d.ts.map

package/dist/plugins/request-dep/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,iEAAiE;IACjE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,gEAAgE;IAChE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,2CAA2C;IAC3C,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,iCAAiC;IACjC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,gFAAgF;IAChF,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,8EAA8E;IAC9E,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,+EAA+E;IAC/E,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wEAAwE;IACxE,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAChC;AAED,6EAA6E;AAC7E,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,wBAAgB,iBAAiB,IAAI,WAAW,CAe/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,CAa3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAM9D;AAsRD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAsB/D"}

package/dist/plugins/request-dep/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * timber-request-dep — Static module-graph analysis for request-dependency.
+ *
+ * Replaces runtime ALS-based taint tracking with a build/dev-time computed
+ * map: segment entry file → statically request-dependent?
+ *
+ * A segment/slot is request-dependent iff any module reachable from its
+ * layout/page/default in the RSC module graph (stopping at client-reference
+ * boundaries) reads the request: it calls a request accessor (`getHeaders`,
+ * `getSearchParams`, `cookies`, …) or calls `.get()` on a value minted by
+ * `defineSearchParams` / `defineCookie`.
+ *
+ * "Calls a request accessor" is decided by resolving the call site's binding
+ * back through import and re-export edges (`origin.ts`), not by matching the
+ * calling module's own import declarations. That distinction is the whole
+ * ticket: a barrel, an alias, or a namespace import used to make a page that
+ * reads the query look static, and a static slot is cached and skipped on a
+ * query-only navigation — serving stale content (TIM-1273, TIM-1291).
+ *
+ * This is deterministic, covers children/barrels/node_modules/Suspense-
+ * deferred code, and is computed before any byte is flushed.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../../plugin-context.ts';
+import { type ModuleFacts } from './analysis.ts';
+export type { ModuleFacts } from './analysis.ts';
+export { analyzeModule, usedSources } from './analysis.ts';
+export { createOriginResolver } from './origin.ts';
+export declare function isFrameworkModule(id: string): boolean;
+export interface ReachabilityInput {
+    factsMap: ReadonlyMap<string, ModuleFacts>;
+    getImports: (id: string) => string[];
+    /**
+     * Does the graph this walk runs over contain this module at all?
+     *
+     * Only the entry needs asking. Every other id the walk visits comes out of
+     * `getImports`, which enumerates edges the graph already resolved, so those
+     * are known by construction. The entry comes from outside — the route
+     * manifest's `filePath`, produced by the scanner from the filesystem — and
+     * nothing guarantees it is spelled the way the graph spells it, or that the
+     * module has been pulled through the pipeline yet.
+     */
+    isKnownModule: (id: string) => boolean;
+}
+/**
+ * Walk the module graph from an entry, returning true if any module reachable
+ * from it reads the request.
+ *
+ * Two passes, and the second is a deliberately blunt backstop:
+ *
+ * 1. **Binding origins.** For each reachable module, resolve every call site's
+ *    binding to its origin. This is precise and indifferent to indirection.
+ * 2. **Definition reachability.** A module that calls `.get()` on *something*
+ *    it imported, with a module holding a definition factory reachable behind
+ *    that import, counts too. The origin walk cannot see through a value that
+ *    is computed rather than bound — `getFilterCookie(key).get()`, where the
+ *    helper returns a definition — and this pass can.
+ *
+ * The second pass over-reports by construction, which is the safe direction: a
+ * needlessly request-dependent segment costs a re-render, a wrongly static one
+ * serves stale content.
+ *
+ * An entry the graph does not contain is an edge we failed to walk, not the
+ * absence of one — the same rule an unresolvable specifier gets. Without the
+ * check it reads as an entry with no imports and no facts, and both passes fall
+ * through to `false`: confidently request-INdependent, for a module nothing
+ * ever looked at. In the build that answer is worse than no answer, because it
+ * is written into `requestDep` as a definite `false` and the runtime's own
+ * "absent key → conservative" fallback never fires.
+ */
+export declare function isReachableTaintSource(entryId: string, input: ReachabilityInput): boolean;
+export declare function timberRequestDep(ctx: PluginContext): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/request-dep/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAkD,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjG,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKrD;AAgCD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACrC;;;;;;;;;OASG;IACH,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAgCzF;AAyED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkI3D"}

package/dist/plugins/request-dep/origin.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Binding-origin resolution across the module graph.
+ *
+ * Given a local name at a call site, walk import and re-export edges until the
+ * binding lands somewhere that can be classified: a framework request accessor,
+ * a definition factory, a definition object minted by one, or nothing of
+ * interest. The walk is what makes the analysis indifferent to how the app
+ * organises its own code — a barrel, an alias, a namespace import, and a
+ * re-export chain five hops deep all reach the same origin (TIM-1291).
+ *
+ * The asymmetry that governs every judgement here: over-reporting costs a
+ * re-render, under-reporting serves stale content to a client that cached a
+ * slot whose render varies with the query. So an edge we cannot follow resolves
+ * to `unknown`, and `unknown` counts as request-dependent.
+ *
+ * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
+ */
+import type { ModuleFacts } from './analysis.ts';
+/** Every specifier the classifier recognises without resolving it. */
+export declare const FRAMEWORK_SOURCES: ReadonlySet<string>;
+export type Origin = 
+/** A request accessor: `getSearchParams`, `cookies`, … */
+{
+    kind: 'accessor';
+}
+/** A definition factory: `defineSearchParams`, `defineCookie`. */
+ | {
+    kind: 'factory';
+}
+/** A value minted by a definition factory — `.get()` on it reads the request. */
+ | {
+    kind: 'definition';
+}
+/** A namespace object for a framework module (`import * as h from 'next/headers'`). */
+ | {
+    kind: 'framework-namespace';
+    source: string;
+}
+/** A namespace object for an app module. */
+ | {
+    kind: 'namespace';
+    moduleId: string;
+}
+/** An edge that could not be followed. Treated as request-dependent. */
+ | {
+    kind: 'unknown';
+}
+/** Resolved, and not interesting. */
+ | {
+    kind: 'none';
+};
+export interface OriginResolver {
+    /** Does this module itself read the request? */
+    isTainted(moduleId: string): boolean;
+    /** Does this module hold a definition factory binding? */
+    isDefinitionModule(moduleId: string): boolean;
+    /** Does this module call `.get()` on a binding it imported? */
+    callsGetterOnImport(moduleId: string): boolean;
+}
+export declare function createOriginResolver(factsMap: ReadonlyMap<string, ModuleFacts>): OriginResolver;
+//# sourceMappingURL=origin.d.ts.map

package/dist/plugins/request-dep/origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../../../src/plugins/request-dep/origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAyB,WAAW,EAAE,MAAM,eAAe,CAAC;AAwBxE,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAGhD,CAAC;AAIH,MAAM,MAAM,MAAM;AAChB,0DAA0D;AACxD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE;AACtB,kEAAkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,iFAAiF;GAC/E;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE;AACxB,uFAAuF;GACrF;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACjD,4CAA4C;GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACzC,wEAAwE;GACtE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB,qCAAqC;GACnC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAkCrB,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,0DAA0D;IAC1D,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9C,+DAA+D;IAC/D,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,cAAc,CA0M/F"}

package/dist/plugins/routing.d.ts

@@ -8,6 +8,6 @@
  * Design docs: 18-build-system.md §"Virtual Modules", 07-routing.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.ts';
 export declare function timberRouting(ctx: PluginContext): Plugin;
 //# sourceMappingURL=routing.d.ts.map

package/dist/plugins/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAWlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA2DhD,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2GxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAYlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoD1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwRxD"}

package/dist/plugins/server-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAyH7C"}
+{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AA4CnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}

package/dist/plugins/shims.d.ts

@@ -5,15 +5,39 @@
  * shim implementations. This enables Next.js-compatible libraries
  * (nuqs, next-intl, etc.) to work unmodified.
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * This plugin also remaps ALL @timber-js/app/* subpath imports to src/ in
+ * server environments (RSC + SSR). This is required because dist/ chunks
+ * are pre-built and miss Vite's RSC transforms (e.g. createContext from
+ * 'react' doesn't exist in RSC's React build). It also ensures a single
+ * module instance for shared mutable state. See SUBPATH_SRC_MAP and TIM-568.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.ts';
+/**
+ * Map from @timber-js/app/<subpath> to relative src/ file paths.
+ *
+ * Used by the catch-all resolveId rule to remap subpath imports to src/
+ * in server environments. When adding a new subpath export to package.json,
+ * add it here too — tests/shims-drift.test.ts enumerates package.json
+ * exports and fails if an entry is missing. See TIM-568.
+ *
+ * Exported for the drift test.
+ */
+export declare const SUBPATH_SRC_MAP: Record<string, string>;
+/**
+ * Runtime value exports of @timber-js/app/server, stubbed in the client
+ * (browser) environment so a stray client-side import fails with a clear
+ * call-time error instead of a confusing bundler error.
+ *
+ * Must stay in sync with the actual runtime exports of server/index.ts —
+ * tests/shims-drift.test.ts compares this list against
+ * Object.keys(import('../server/index.ts')) and fails on drift.
+ * Type-only exports (DenyOptions, AccessContext, …) are erased at runtime
+ * and must NOT appear here.
+ */
+export declare const SERVER_STUB_EXPORTS: readonly string[];
 /**
  * Create the timber-shims Vite plugin.
  *

package/dist/plugins/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiDhD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA4JvD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsB1D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBlD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA6BhD,CAAC;AA2CF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAoOvD"}

package/dist/plugins/static-build.d.ts

@@ -2,47 +2,243 @@
  * timber-static-build — Vite sub-plugin for static output mode.
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
- * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
- * 3. Coordinates build-time rendering of all pages
+ * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
+ * 2. After the build, renders all routes to static HTML + RSC flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { StaticPageEntry, StaticRedirectEntry } from '../server/static-generator.ts';
+import type { RscManifest } from '../shared/rsc-manifest.ts';
+import { type FsIdentity } from '../adapters/fs-identity.ts';
+/**
+ * A single entry in the RSC manifest injected into static HTML.
+ * Maps an unhashed `/_rsc/*.rsc` path to its hashed URL, with
+ * optional route params inlined to avoid a sidecar fetch.
+ */
+export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.ts';
 export interface StaticValidationError {
-    type: 'dynamic-api' | 'nojs-directive';
+    type: 'dynamic-api';
     file: string;
     message: string;
     line?: number;
 }
-export interface StaticOptions {
-    clientJavascriptDisabled: boolean;
-}
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
  */
 export declare function detectDynamicApis(code: string, fileId: string): StaticValidationError[];
 /**
- * Detect 'use client' and 'use server' directives using AST-based parsing.
- * When client JavaScript is disabled, both are hard build errors — no React
- * runtime or server actions are allowed in the output.
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * Both sides are base-prefixed (TIM-1274). `from` is matched by the host
+ * against the request path and `to` is served to the browser as a `Location`,
+ * so both are deployed-URL space while `StaticRedirectEntry` carries route
+ * space — under `base: '/repo/'`, a rule `/old /new 301` would match nothing
+ * and, if it did, would send the browser off the deployment.
+ *
+ * An off-origin `to` is left alone: `redirectExternal()` produces an absolute
+ * URL, and a protocol-relative one addresses another host too. Neither is a
+ * path on this deployment, so neither takes the prefix.
+ *
+ * @param base Normalized deployment base (see `shared/base-path.ts`).
+ * @internal Exported for testing.
+ */
+export declare function generateRedirectsFile(redirects: StaticRedirectEntry[], base: string): string;
+/**
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about/index.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
+ *
+ * The RSC shape mirrors the HTML shape for the reason the HTML shape has it:
+ * a route gets a directory and the artifact is the `index` inside it, so the
+ * mapping is injective. See `shared/rsc-payload-path.ts` (TIM-1266).
+ */
+export declare function staticOutputPath(entry: StaticPageEntry): string;
+/**
+ * Records which entry claimed each output path and reports second claims.
+ *
+ * Two entries landing on one path is not a rendering failure — both render
+ * fine — so nothing downstream notices. The file is written twice, the second
+ * write wins, and the deployment serves one route's bytes at another route's
+ * URL with the same content type and the same shape (TIM-1266).
+ *
+ * The naming rules are injective by construction (a route path is a directory
+ * and the artifact is the `index` inside it), so a collision here means either
+ * two entries were enumerated for one URL or a route reached a path the
+ * framework reserves for itself (`404.html`). Both are build errors: there is
+ * no correct file to write.
+ *
+ * Two entries can also be unwritable together without claiming the same
+ * string: one wants a file where the other wants a directory (`about` from an
+ * API route, `about/index.html` from a page). The filesystem does refuse that
+ * one — `EISDIR` on the rename, `ENOTDIR` on the mkdir, depending on which
+ * lands second — but an errno names a path, and in the rename case the path
+ * it names is `about.tmp`. Reported here instead, so the message says which
+ * two routes.
+ *
+ * Collisions are **collected, not thrown**. `onEntry` runs inside the
+ * generator, whose RSC branch treats a throw as "this payload is unavailable,
+ * SPA navigation falls back to a full load" and swallows it — which for a
+ * collision is the wrong end state, since the two payloads are still
+ * ambiguous. The caller raises them once generation is done.
+ *
+ * @internal Exported for testing.
+ */
+export declare class StaticOutputPaths {
+    private readonly claimed;
+    /** Every ancestor directory of a claimed path, mapped to its claimant. */
+    private readonly directories;
+    private readonly collisions;
+    /**
+     * @param identity How the output filesystem decides two paths name one
+     *   file, from `detectFsIdentity`. The guard predicts whether two writes
+     *   land on one file, which is a property of the filesystem — so it is
+     *   asked, not assumed. Folding unconditionally would reject `/Foo` beside
+     *   `/foo` on Linux, where both are perfectly servable files.
+     */
+    private readonly identity;
+    constructor(identity?: FsIdentity);
+    /** The identity under which the filesystem will compare this path. */
+    private key;
+    /**
+     * Claim `relPath` for `entry`. Returns false when the path cannot be
+     * written alongside an earlier claim, in which case the caller must not
+     * write the file — the losing entry is recorded and the build fails at
+     * the end.
+     */
+    claim(relPath: string, entry: StaticPageEntry): boolean;
+    /** Throw if any two entries could not both be written. */
+    assertNoCollisions(): void;
+}
+/**
+ * Writes generated entries into the static output directory, one file per
+ * entry, refusing any write that would land on a path another entry holds.
+ *
+ * @internal Exported for testing.
+ */
+export declare class StaticSiteWriter {
+    /** Content-Type per URL path for extensionless API routes (TIM-1241). */
+    readonly contentTypes: Record<string, string>;
+    private readonly paths;
+    private readonly staticDir;
+    constructor(staticDir: string, identity?: FsIdentity);
+    write(entry: StaticPageEntry): Promise<void>;
+    /** Throw if any two entries could not both be written. */
+    assertNoCollisions(): void;
+}
+/**
+ * Remove artifacts a generation pass produces only *conditionally*, so none
+ * of them can survive from an earlier build into this one.
+ *
+ * Pages are not in this set: every page is rewritten each pass, and a page
+ * whose route was deleted is a different problem (a stale file nothing links
+ * to) from the one here.
+ *
+ * - `_rsc/` because the files are content-hashed. Left in place, a previous
+ *   build's already-hashed payload gets hashed again and accumulates.
+ * - `_redirects` because it is written only when this pass found redirects.
+ *   A build whose redirects were removed would otherwise ship the previous
+ *   build's rules — and would break the merge exemption in
+ *   `shared/static-platform-files.ts`, which lets the pre-rendered copy
+ *   overwrite `public/_redirects` on the grounds that it *contains* it. That
+ *   holds only for a file the current pass produced (TIM-1266).
+ *
+ * @internal Exported for testing.
+ */
+export declare function cleanConditionalArtifacts(staticDir: string): Promise<void>;
+/**
+ * Run `fn` with `MessageChannel` instrumented, then stop every channel opened
+ * while it ran from holding the process open.
+ *
+ * Static generation is the only build pass that renders **HTML** in the build
+ * process: it imports the built app bundle and drives the full SSR pipeline
+ * through it. React's scheduler opens a `MessageChannel` at module scope in
+ * that bundle (`scheduler`'s DOM build) and never closes it, and a ref'd
+ * `MessagePort` keeps Node's event loop alive on its own — so `timber build`
+ * finished the site, printed its summary, and then hung forever. Server-mode
+ * builds are unaffected because nothing there renders through react-dom.
+ *
+ * `unref()` is the whole fix: it leaves the port working and only drops the
+ * "keep the process alive" property. It is applied **after** `fn` resolves, so
+ * a render in flight can never be cut short by the process exiting under it —
+ * an unref'd port would let Node exit while the scheduler still had a
+ * continuation queued, which is a silently truncated page rather than a hang.
+ *
+ * Nothing renders after this pass. If that ever changes, the release has to
+ * move to the end of whatever renders last.
+ *
+ * @internal Exported for testing.
+ */
+export declare function withSchedulerPortsReleased<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Warn when Vite's `base` is document-relative (`'./'`) in static mode.
+ *
+ * Payload URLs are addressed from the deployment root plus the base prefix.
+ * A relative base gives no prefix to compute (see shared/base-path.ts), so
+ * `/_rsc/about.rsc` is requested at the domain root — correct only when the
+ * site is served from there. The build still succeeds: relative bases work
+ * fine for assets, and for a root-served site nothing is wrong. The warning
+ * exists so a sub-path deployment does not silently degrade to a hard
+ * navigation on every link.
+ *
+ * Skipped when client JS is disabled — there is no SPA navigation and no
+ * payload fetch to mis-address.
+ *
+ * @internal Exported for testing.
+ */
+export declare function warnUnusableBase(ctx: PluginContext): void;
+/**
+ * Compute a short content hash for immutable caching.
+ * Uses 8 chars of base64url-encoded SHA-256, matching Vite's asset hash style.
+ */
+export declare function contentHash(data: Buffer | Uint8Array): string;
+/**
+ * Hash all RSC flight payloads in `_rsc/`, rename them with content
+ * hashes, and build a manifest with optional inlined route params.
+ *
+ * Before: `_rsc/index.rsc`, `_rsc/about.rsc`
+ * After:  `_rsc/index-B7YxEKdN.rsc`, `_rsc/about-C8ZzFLfO.rsc`
+ *
+ * The manifest maps the original `_rsc/` URL to an entry object:
+ * `{"/_rsc/index.rsc":{"url":"/_rsc/index-B7YxEKdN.rsc"}, ...}`
+ *
+ * Keys and URLs are **route-space**: root-relative, never carrying Vite's
+ * `base`. The client applies the base once, at fetch time
+ * (`client/rsc-fetch.ts` → `toStaticRscUrl`), so the generated site stays
+ * relocatable and the base has exactly one expression at runtime rather
+ * than two that must agree. See TIM-1261.
+ *
+ * Route params (from `routeParams`) are inlined into the manifest
+ * entry, eliminating the need for .params.json sidecar files. TIM-1255.
+ *
+ * Injected into HTML as:
+ * `<script>window.__TIMBER_RSC_MANIFEST__={...}</script>`
+ *
+ * @internal Exported for testing.
+ */
+export declare function hashRscPayloads(staticDir: string): Promise<RscManifest>;
+/**
+ * Inject the RSC manifest into all HTML files as a `<script>` tag
+ * before `</head>`. This lets the client resolve hashed RSC URLs
+ * without an extra network request.
  *
- * When client JavaScript is enabled, these are allowed (client components
- * hydrate, server actions get extracted to API endpoints).
+ * @internal Exported for testing.
  */
-export declare function detectDirectives(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
+export declare function injectRscManifestIntoHtml(staticDir: string, manifest: RscManifest): Promise<void>;
 /**
- * Run all static mode validations on a source file.
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
  *
- * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
- * - Directive detection ('use client', 'use server') — only when client JS is disabled
+ * @internal Exported for testing.
  */
-export declare function validateStaticMode(code: string, fileId: string, options: StaticOptions): StaticValidationError[];
+export declare function readUserRedirects(root: string): Promise<string | null>;
 /**
  * Create the timber-static-build Vite plugin.
  *
@@ -50,6 +246,7 @@ export declare function validateStaticMode(code: string, fileId: string, options
  *
  * Hooks:
  * - transform: Validates source files for static mode violations
+ * - buildApp (post): Renders all routes to static HTML after the build
  */
 export declare function timberStaticBuild(ctx: PluginContext): Plugin;
 //# sourceMappingURL=static-build.d.ts.map

package/dist/plugins/static-build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static-build.d.ts","sourceRoot":"","sources":["../../src/plugins/static-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAiBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA2BvF;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,qBAAqB,EAAE,CA8BzB;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,qBAAqB,EAAE,CAOzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0C5D"}
+{"version":3,"file":"static-build.d.ts","sourceRoot":"","sources":["../../src/plugins/static-build.ts"],"names":[],"mappings":"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"}

package/dist/routing/codegen-shared.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared codegen helpers — import-path computation and codec chain type
+ * builders.
+ *
+ * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+ * helpers without a cyclic import.
+ */
+import type { ParamEntry } from './codegen-types.ts';
+/**
+ * Compute a relative import specifier for a codec/page file, stripping
+ * the .ts/.tsx extension and resolving against the codegen output dir.
+ */
+export declare function codecImportPath(codecFilePath: string, importBase: string | undefined): string;
+/**
+ * Build a TypeScript type expression for a single param using the global
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
+ *
+ * Uses `infer` to extract the codec value rather than direct indexing
+ * because TypeScript doesn't narrow index validity inside a conditional
+ * type's true branch — `typeof schema.segmentParams[K]` produces TS2538
+ * even when the condition proves K is a valid key. In .d.ts files that
+ * error is suppressed and the type silently becomes `any`.
+ */
+export declare function buildSchemaParamType(p: ParamEntry, fallback?: string): string;
+//# sourceMappingURL=codegen-shared.d.ts.map

package/dist/routing/codegen-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen-shared.d.ts","sourceRoot":"","sources":["../../src/routing/codegen-shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E"}