@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/client/use-query-states.ts

@@ -11,14 +11,14 @@
 'use client';
 
 import { useQueryStates as nuqsUseQueryStates } from 'nuqs';
-import type { SingleParser } from 'nuqs';
+import type { MultiParser } from 'nuqs';
 import type {
   SearchParamCodec,
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
 } from '../search-params/define.js';
-import { getSearchParamsDefinition } from '../search-params/registry.js';
+import { parseTotal } from '../search-params/parse-total.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 
@@ -50,32 +50,80 @@ function unwrapNuqsValue(value: unknown): unknown {
 }
 
 /**
- * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
+ * Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.
  *
  * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
  * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
  *
- * The defaultValue is computed eagerly. Codecs are documented to return a
- * default rather than throw, but a throwing codec must not crash every
- * component that mounts the hook — treat its default as undefined and let
- * its error surface from server-side parse() instead.
+ * The defaultValue is computed eagerly, through `parseTotal` — the same
+ * entry point server-side `parse()` uses, so the hook and the server agree
+ * on what an absent param means (a bare nuqs parser answers `null`, not
+ * `undefined`; TIM-1350). Codecs are documented to return a default rather
+ * than throw, but a throwing codec must not crash every component that
+ * mounts the hook — treat its default as undefined and let its error
+ * surface from server-side parse() instead.
+ *
+ * A `null` absent-value is NOT registered as the nuqs default. nuqs
+ * already represents an absent key as `null`, so the hook reads the same
+ * value either way — but registering it makes `clearOnDefault` fire on
+ * `setParams({ q: null })` and delete the key before the bridged
+ * `serialize` runs. For a codec that encodes `null` as a real query value
+ * (`serialize(null) === 'none'`), that silently disagrees with
+ * `buildSearchParams({ q: null })`, which writes it. Same reasoning as
+ * `getDefaultSerialized` on the server: a codec with no value for an
+ * absent param has no default to register.
  */
-function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {
-  let defaultValue: unknown;
+function bridgeCodec<T>(codec: SearchParamCodec<T>): MultiParser<T> & { defaultValue: T } {
+  let absent: unknown;
   try {
-    defaultValue = codec.parse(undefined);
+    absent = parseTotal(codec, undefined);
   } catch {
-    defaultValue = undefined;
+    absent = undefined;
   }
-  return {
-    parse: (v: string) => wrapNuqsValue(codec.parse(v)),
+
+  const parser = {
+    // `multi`, so nuqs reads the key with `searchParams.getAll()` and hands
+    // us EVERY value. A single parser reads `.get()` — the first value only
+    // — which is not the domain a timber codec is defined over. The server
+    // parses `?tags=a&tags=b` as `['a','b']`; a single parser made the hook
+    // answer `['a']` for the same URL, under a declared `string[]` that
+    // admitted no such disagreement (TIM-1352). Scalar codecs are unaffected:
+    // they receive the array and take `value[0]`, exactly as they do on the
+    // server, so first-value-wins is preserved through the same code path
+    // rather than through nuqs's reader.
+    //
+    // nuqs never calls this with an empty array — `isAbsentFromUrl` treats
+    // `[]` as absent and answers `defaultValue` directly — which is what
+    // keeps the absent case agreeing with the server's `undefined`.
+    //
+    // Reading every value is only half of it: the values must arrive in the
+    // SAME SHAPE the server would have produced, or the divergence just
+    // moves. `normalizeRaw` (search-params/define.ts) collapses a
+    // single-valued key to a bare string and keeps an array only for a
+    // repeated one, so this mirrors that rule exactly. Handing a codec
+    // `['3']` where the server hands it `'3'` breaks every codec whose
+    // `parse` is written for the scalar case — which is most hand-written
+    // ones, contract or no contract.
+    type: 'multi' as const,
+    // Through parseTotal, not codec.parse. nuqs's own `.withDefault(d)`
+    // overrides ONLY `parseServerSide`, so `parseAsInteger.withDefault(1)`
+    // on `?page=abc` returned 1 from the server and null from the hook —
+    // a divergence the declared non-nullable `number` did not admit.
+    parse: (v: readonly string[]) =>
+      wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),
     serialize: (v: unknown) => {
       const value = unwrapNuqsValue(v);
       // Delegate null to the codec — some codecs encode null as a real
       // query value. undefined has no encoding; nuqs requires a string.
-      return value === undefined ? '' : (codec.serialize(value as T) ?? '');
+      //
+      // ONE element, always. A multi parser may return several — nuqs
+      // appends one key per entry — but `Codec.serialize` returns a single
+      // string by construction, so timber cannot emit repeated keys here
+      // any more than `buildSearchParams` can. Widening that protocol is
+      // TIM-1353. Wrapping the same string keeps the URL the hook writes
+      // byte-identical to the one `buildSearchParams` writes.
+      return [value === undefined ? '' : (codec.serialize(value as T) ?? '')];
     },
-    defaultValue: wrapNuqsValue(defaultValue),
     eq: (a: unknown, b: unknown) => {
       if (a === b) return true;
       try {
@@ -86,7 +134,26 @@ function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { default
         return false;
       }
     },
-  } as SingleParser<T> & { defaultValue: T };
+  } as MultiParser<T> & { defaultValue: T };
+
+  if (absent !== null) parser.defaultValue = wrapNuqsValue(absent) as T;
+  return parser;
+}
+
+/**
+ * Collect `withUrlKey` aliases off a codec map.
+ *
+ * `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map
+ * alone is enough to reconstruct the aliases — `defineSearchParams` builds its
+ * own `urlKeys` from exactly this property.
+ */
+function deriveUrlKeys(codecs: Record<string, SearchParamCodec<unknown>>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const key of Object.keys(codecs)) {
+    const alias = codecs[key]?.urlKey;
+    if (alias) result[key] = alias;
+  }
+  return result;
 }
 
 /**
@@ -95,12 +162,12 @@ function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { default
 function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
   [K in keyof T]: SearchParamCodec<T[K]>;
 }) {
-  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};
+  const result: Record<string, MultiParser<unknown> & { defaultValue: unknown }> = {};
   for (const key of Object.keys(codecs)) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     result[key] = bridgeCodec(codecs[key as keyof T]) as any;
   }
-  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };
+  return result as { [K in keyof T]: MultiParser<T[K]> & { defaultValue: T[K] } };
 }
 
 // ─── Hook ─────────────────────────────────────────────────────────
@@ -113,7 +180,7 @@ function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
  *
  * Usage:
  * ```ts
- * // Via a SearchParamsDefinition
+ * // Via a SearchParamsDefinition imported from the route's params.ts
  * const [params, setParams] = definition.useQueryStates()
  *
  * // Standalone with inline codecs
@@ -121,30 +188,18 @@ function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
  *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
  * })
  * ```
+ *
+ * There is deliberately no route-string form (`useQueryStates('/products')`).
+ * Importing the definition from `params.ts` is the documented way to reach
+ * another route's codecs — it needs no runtime registry lookup and so has no
+ * "not registered yet" failure mode. See design/23-search-params.md
+ * §"Client Access".
  */
 export function useQueryStates<T extends Record<string, unknown>>(
-  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,
+  codecs: { [K in keyof T]: SearchParamCodec<T[K]> },
   _options?: QueryStatesOptions,
   urlKeys?: Readonly<Record<string, string>>
 ): [T, SetParams<T>] {
-  // Route-string overload: resolve codecs from the registry
-  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
-  let resolvedUrlKeys = urlKeys;
-  if (typeof codecsOrRoute === 'string') {
-    const definition = getSearchParamsDefinition(codecsOrRoute);
-    if (!definition) {
-      throw new Error(
-        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +
-          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +
-          `For cross-route usage, import the definition explicitly.`
-      );
-    }
-    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };
-    resolvedUrlKeys = definition.urlKeys;
-  } else {
-    codecs = codecsOrRoute;
-  }
-
   const bridged = bridgeCodecs(codecs);
 
   // Forward hook-level options (shallow, scroll, history) to nuqs.
@@ -155,7 +210,15 @@ export function useQueryStates<T extends Record<string, unknown>>(
   if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;
   if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;
   if (_options?.history !== undefined) nuqsOptions.history = _options.history;
-  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {
+  // `withUrlKey` attaches the alias to the codec itself — that is the design's
+  // "URL keys travel with codecs" principle — so the aliases are derivable
+  // here and must be, for the inline codec-map form: nobody passes `urlKeys`
+  // on that path, and without this an aliased bundle silently read and wrote
+  // the property name instead of the alias. `bindUseQueryStates` still passes
+  // the definition's precomputed map, which wins on conflict; it is built from
+  // these same codecs, so the two agree by construction rather than by luck.
+  const resolvedUrlKeys = { ...deriveUrlKeys(codecs), ...urlKeys };
+  if (Object.keys(resolvedUrlKeys).length > 0) {
     nuqsOptions.urlKeys = resolvedUrlKeys;
   }
 

package/src/client/use-router.ts

@@ -14,7 +14,7 @@
  * In timber, navigation calls reactRoot.render() which is a root-level
  * render — startTransition has no effect on root renders.
  *
- * Navigation state (params, pathname) is delivered atomically via
+ * Navigation state (pathname, search) is delivered atomically via
  * NavigationContext embedded in the element tree passed to
  * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
  *

package/src/client/use-segment-params.ts

@@ -18,11 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: On the client, useParams() reads from NavigationContext
- * which is updated atomically with the RSC tree render. This replaces
- * the previous useSyncExternalStore approach that suffered from a
- * timing gap between tree render and store notification — causing
- * preserved layout components to briefly show stale active state.
+ * Reactivity: On the client, useParams() reads from ParamsContext, published
+ * by the one provider the client renders above the merge point
+ * (`PayloadRoot`). Params update atomically with the tree because they travel
+ * on the same payload root — there is no separate channel that could be
+ * seeded a render early or late (TIM-1294, TIM-1297).
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -32,8 +32,15 @@
 
 import type { Routes } from '../index.js';
 import { getSsrData } from './ssr-data.js';
-import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
-import { useNavigationContext } from './navigation-context.js';
+import {
+  currentParams,
+  currentSlotParams,
+  _setCurrentParams,
+  _setCurrentSlotParams,
+  paramsListeners,
+} from './state.js';
+import { resolveSegmentParams, type SlotParamsRecord } from '../shared/slot-params.js';
+import { useParamsContext } from './params-context.js';
 
 // ---------------------------------------------------------------------------
 // Module-level subscribe/notify pattern — kept for backward compat and tests
@@ -81,6 +88,18 @@ export function setCurrentParams(params: Record<string, string | string[]>): voi
   _setCurrentParams(params);
 }
 
+/**
+ * Set the per-slot params snapshot in the module-level store.
+ *
+ * Paired with `setCurrentParams`: the router calls both on every navigation,
+ * including with `null` when a response carries no slot params, so a slot's
+ * params from the *previous* route cannot be read on the next one. Fill and
+ * serve are paired; so are fill and clear. See TIM-1285.
+ */
+export function setCurrentSlotParams(slotParams: SlotParamsRecord | null): void {
+  _setCurrentSlotParams(slotParams);
+}
+
 /**
  * Notify all legacy subscribers that params have changed.
  *
@@ -105,9 +124,9 @@ export function notifyParamsListeners(): void {
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
- * On the client, reads from NavigationContext (provided by
- * NavigationProvider in renderRoot). This ensures params update
- * atomically with the RSC tree — no timing gap.
+ * On the client, reads from ParamsContext, published by `PayloadRoot` above
+ * everything the navigation renders. Params update atomically with the RSC
+ * tree — no timing gap.
  *
  * During SSR, reads from the ALS-backed SSR data context to ensure
  * per-request isolation across concurrent requests with streaming Suspense.
@@ -123,15 +142,17 @@ export function useSegmentParams<R extends keyof Routes>(
   segmentPath: R
 ): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;
 export function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;
-export function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {
-  // Try reading from NavigationContext (client-side, inside React tree).
-  // During SSR, no NavigationProvider is mounted, so this returns null.
-  // When called outside a React component, useContext throws — caught below.
+export function useSegmentParams(segmentPath?: string): Record<string, string | string[]> {
+  // Try the client-owned provider first. It sits above everything a navigation
+  // renders, so any component on the page — initial document, full navigation,
+  // or a layout the server skipped — has one above it. Absent during SSR,
+  // where the ALS path below is the answer. When called outside a React
+  // component, useContext throws — caught below.
   try {
     // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
-    const navContext = useNavigationContext();
-    if (navContext !== null) {
-      return navContext.params;
+    const paramsContext = useParamsContext();
+    if (paramsContext !== null) {
+      return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
     }
   } catch {
     // No React dispatcher available (called outside a component).
@@ -140,5 +161,7 @@ export function useSegmentParams(_segmentPath?: string): Record<string, string |
 
   // SSR path: read from ALS-backed SSR data context.
   // Falls back to module-level currentParams for tests.
-  return getSsrData()?.params ?? currentParams;
+  const ssrData = getSsrData();
+  if (ssrData) return resolveSegmentParams(ssrData.params, ssrData.slotParams, segmentPath);
+  return resolveSegmentParams(currentParams, currentSlotParams, segmentPath);
 }

package/src/cookies/define-cookie.ts

@@ -147,7 +147,12 @@ function deleteClientCookie(name: string, options?: ClientCookieOptions): void {
 // ─── Standard Schema Auto-Detection ───────────────────────────────────────
 
 function resolveCodec<T>(codecOrSchema: CookieCodec<T> | StandardSchemaV1<T>): CookieCodec<T> {
-  return resolveCodecOrSchema('codec', codecOrSchema, 'search') as CookieCodec<T>;
+  // 'cookie', not 'search': a cookie carries one string per name, so the
+  // repeated-key array shape the search bridge tolerates does not exist
+  // here — and `serialize` returning `null` means DELETE for a cookie
+  // where it means "omit the key" for a search param. See
+  // schema-bridge.ts §fromCookieSchema.
+  return resolveCodecOrSchema('codec', codecOrSchema, 'cookie') as CookieCodec<T>;
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────

package/src/index.ts

@@ -31,7 +31,7 @@ import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
 import { timberServerBundle } from './plugins/server-bundle';
 import { timberCacheTransform } from './plugins/cache';
-import { timberRequestDep } from './plugins/request-dep';
+import { timberRequestDep } from './plugins/request-dep/index.js';
 import { timberPrebuilt } from './plugins/prebuilt';
 import { timberPrerenderSugar } from './plugins/prerender-sugar';
 import { timberCloudflareWasm } from './plugins/cloudflare-wasm';
@@ -42,7 +42,7 @@ import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server
 import { createHoldingServer } from './dev-tools/holding-server.js';
 import { resolveStartPort, startDevServerPort } from './server/port-resolution.js';
 import type { TimberUserConfig } from './config-types.js';
-import type { PluginContext } from './plugin-context.js';
+import type { PluginContext, TimberPluginApi } from './plugin-context.js';
 import {
   createPluginContext,
   loadTimberConfigFile,
@@ -69,7 +69,10 @@ export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from '.
  *
  * Each key is a route path pattern. Values have:
  *   segmentParams: shape of URL segment params (e.g. { id: string })
- *   searchParams: parsed type from search-params.ts, or {} if none
+ *
+ * There is no `searchParams` member: since TIM-1343 the framework does not
+ * scan for search-param definitions, so it has nothing to type them with. A
+ * definition carries its own type to call sites through an ordinary import.
  *
  * This interface is empty by default and populated via codegen.
  * See design/09-typescript.md §"Typed Routes".
@@ -245,6 +248,21 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   // config() hook must NOT return a `plugins` field (Vite ignores it).
   const rootSync: Plugin = {
     name: 'timber-root-sync',
+
+    // The plugin context, published for out-of-band callers that need the
+    // *resolved* configuration rather than a second reading of the files it
+    // came from. `timber check` is the one today: it runs Vite's
+    // `resolveConfig()` and reads root, appDir, and pageExtensions from here,
+    // so it scans exactly the tree `timber build` builds — including config
+    // passed inline as `timber({ ... })`, which lives only in this closure and
+    // is invisible to anything that re-reads `timber.config.ts`. See
+    // `cli-check.ts` and design/11-platform.md §`timber check`.
+    //
+    // Valid from `configResolved` onward; `appDir` and `root` are unset before
+    // that, which is why the reader runs a full `resolveConfig()` rather than
+    // just loading the config file.
+    api: { getContext: () => ctx } satisfies TimberPluginApi,
+
     async config(userConfig, { command, isPreview }) {
       // ── Load timber.config.ts from the correct root ───────────────
       // Vite's `config` hook fires before `configResolved`. The user's
@@ -388,7 +406,6 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         '@timber-js/app/cookies',
         '@timber-js/app/cache',
         '@timber-js/app/search-params',
-        '@timber-js/app/segment-params',
         '@timber-js/app/params',
         '@timber-js/app/codec',
       ];
@@ -464,6 +481,10 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       ctx.root = resolved.root;
       ctx.appDir = resolveAppDir(resolved.root, ctx.config.appDir);
       ctx.dev = resolved.command === 'serve';
+      // Vite's resolved base — the deployment path prefix. Captured once
+      // here so every sub-plugin that emits a URL (assets, fonts, RSC
+      // payloads) reads the same value. See TIM-1261.
+      ctx.base = resolved.base;
 
       // Register all timber config file candidates as Vite config file
       // dependencies so Vite's built-in restart-on-change handles them

package/src/plugin-context.ts

@@ -73,6 +73,21 @@ export interface PluginContext {
   root: string;
   /** Whether the dev server is running (set by timber-root-sync in configResolved) */
   dev: boolean;
+  /**
+   * Vite's resolved `base` (set by timber-root-sync in configResolved).
+   * Always has a trailing slash; `'/'` unless the app is deployed under a
+   * sub-path. Every URL the framework emits — assets, fonts, RSC payloads —
+   * carries this prefix. This is the single copy: sub-plugins read it here
+   * rather than capturing `config.base` in their own configResolved.
+   *
+   * **Availability:** written by timber-root-sync, which has no `enforce`, so
+   * it is populated from `buildStart`/`load`/`generateBundle`/`configureServer`
+   * onward — but NOT during the `configResolved` of an `enforce: 'pre'`
+   * plugin, which Vite runs first. A pre plugin that needs the base inside
+   * its own `configResolved` must read `config.base` there (timber-fonts
+   * does). See TIM-1261.
+   */
+  base: string;
   /** CSS build manifest (populated by adapter after client build, null in dev) */
   buildManifest: BuildManifest | null;
   /** Per-build deployment ID for version skew detection (null in dev) */
@@ -98,6 +113,22 @@ export interface PluginContext {
    * populate per-route modulepreload entries from clientReferenceDeps.
    */
   routeClientRefKeys?: Map<string, Set<string>>;
+  /**
+   * Static request-dependency verdict per segment entry file, keyed by the
+   * absolute `filePath` the route scanner produced. Computed once by
+   * `timber-request-dep`'s RSC `buildEnd` and serialized into
+   * `buildManifest.requestDep` by `timber-build-manifest` (build only — dev
+   * answers the same question through the `Symbol.for('timber:request-dep')`
+   * bridge instead).
+   *
+   * `undefined` and `{}` are different states and the difference is the whole
+   * of TIM-1300: an empty object means the analysis ran and found no segments,
+   * `undefined` means it never ran, and the runtime cannot tell them apart —
+   * every key is absent either way, so every segment falls to the conservative
+   * `true` and nothing is ever skipped. The build fails loudly on `undefined`
+   * rather than shipping that silently.
+   */
+  requestDepMap?: Record<string, boolean>;
   /**
    * Maps absolute module IDs of client references in non-facade RSC
    * chunks to the absolute paths of their consuming facade modules.
@@ -217,6 +248,32 @@ export class ParseMemo {
 
 // ── App directory resolution ──────────────────────────────────────────────
 
+// ── Plugin API (Vite `plugin.api`) ────────────────────────────────────────
+
+/**
+ * What `timber-root-sync` publishes on its Vite `plugin.api`.
+ *
+ * The single supported way to read timber's *resolved* configuration from
+ * outside the plugin pipeline. Re-reading `timber.config.ts` is not equivalent:
+ * config passed inline as `timber({ ... })` in `vite.config.ts` exists only in
+ * the plugin's closure, and `root`/`appDir` are resolved against Vite's root
+ * rather than the caller's cwd.
+ */
+export interface TimberPluginApi {
+  /** The live plugin context. Fully populated from `configResolved` onward. */
+  getContext(): PluginContext;
+}
+
+/** Narrow an unknown Vite `plugin.api` to timber's. */
+export function isTimberPluginApi(api: unknown): api is TimberPluginApi {
+  return (
+    typeof api === 'object' &&
+    api !== null &&
+    'getContext' in api &&
+    typeof api.getContext === 'function'
+  );
+}
+
 /**
  * Resolve the app directory. Checks (in order):
  * 1. Explicit `configAppDir` from timber.config.ts
@@ -258,6 +315,7 @@ export function createPluginContext(config?: TimberUserConfig, root?: string): P
     appDir: join(projectRoot, 'app'),
     root: projectRoot,
     dev: false,
+    base: '/',
     buildManifest: null,
     deploymentId: null,
     timer: createStartupTimer(),

package/src/plugins/adapter-build.ts

@@ -21,6 +21,7 @@ import type { PluginContext } from '../plugin-context.js';
 import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
 import type { BuildManifest } from '../server/build-manifest.js';
 import { swallow } from '../server/logger.js';
+import { normalizeBasePath } from '../shared/base-path.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -85,6 +86,9 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
 
         const adapterConfig: TimberConfig = {
           root: ctx.root,
+          // Normalized once here, not in each adapter: the platform files
+          // adapters write address deployed-URL space (TIM-1274).
+          base: normalizeBasePath(ctx.base),
           output: ctx.config.output ?? 'server',
           clientJavascriptDisabled: ctx.clientJavascript.disabled,
           manifestInit,

package/src/plugins/build-manifest.ts

@@ -20,7 +20,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import type { Plugin, ResolvedConfig } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
-import type { BuildManifest } from '../server/build-manifest.js';
+import { EMPTY_BUILD_MANIFEST, type BuildManifest } from '../server/build-manifest.js';
 import type { SegmentNode, RouteFile } from '../routing/types.js';
 import { isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
@@ -335,14 +335,12 @@ function walkModuleImports(
  * Hooks: configResolved, resolveId, load, generateBundle (client and RSC envs)
  */
 export function timberBuildManifest(ctx: PluginContext): Plugin {
-  let resolvedBase = '/';
   let isDev = false;
 
   return {
     name: 'timber-build-manifest',
 
     configResolved(config: ResolvedConfig) {
-      resolvedBase = config.base;
       isDev = config.command === 'serve';
 
       // Generate a per-build deployment ID early so virtual:timber-config
@@ -373,13 +371,18 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     load(id: string) {
       if (id !== RESOLVED_VIRTUAL_ID) return null;
 
+      // Serialized, not restated: an empty manifest is described once, in
+      // server/build-manifest.ts. Both branches below emitted their own object
+      // literal and had already drifted apart — see EMPTY_BUILD_MANIFEST.
+      const empty = JSON.stringify(EMPTY_BUILD_MANIFEST);
+
       // In dev mode, return empty manifest — Vite HMR handles CSS.
       if (isDev) {
         return [
           '// Auto-generated build manifest — do not edit.',
           '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
           '',
-          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
+          `const manifest = ${empty};`,
           '',
           'export default manifest;',
         ].join('\n');
@@ -389,11 +392,17 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       // The adapter writes a _timber-manifest-init.js that sets this global
       // before the RSC handler imports this module. ESM evaluation order
       // guarantees the global is set by the time this code runs.
+      //
+      // The literal is only reached when the global is unset — an app built
+      // with no adapter, which writes no init module. It is NOT the map the
+      // build computed; that lives in _timber-manifest-init.js (TIM-1300).
       return [
         '// Auto-generated build manifest — do not edit.',
         '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
+        '// The object below is only the fallback for when that global is unset —',
+        '// the real manifest, including the requestDep map, is in that init module.',
         '',
-        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {}, requestDep: {} };',
+        `const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? ${empty};`,
         '',
         'export default manifest;',
       ].join('\n');
@@ -436,21 +445,33 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       }
 
       if (envName === 'client') {
-        ctx.buildManifest = buildManifestFromBundle(bundle, resolvedBase, ctx.root);
+        ctx.buildManifest = buildManifestFromBundle(bundle, ctx.base, ctx.root);
 
         // Compute cache-busting hashes for metadata route files
         if (ctx.routeTree) {
           ctx.buildManifest.metadataRouteHashes = computeMetadataRouteHashes(ctx.routeTree.root);
         }
 
-        // Attach static request-dependency map from the request-dep plugin.
-        // Computed in the RSC buildEnd hook and stored on ctx.
-        const requestDepMap = (ctx as unknown as Record<string, unknown>).requestDepMap as
-          | Record<string, boolean>
-          | undefined;
-        if (requestDepMap) {
-          ctx.buildManifest.requestDep = requestDepMap;
+        // Attach the static request-dependency map from the request-dep
+        // plugin, computed in the RSC `buildEnd` hook. The RSC environment is
+        // built before the client one, so the field is populated by now.
+        //
+        // Absent means the RSC `buildEnd` never ran — a broken plugin pipeline,
+        // not an app without segments, which produces `{}`. Serializing that as
+        // an empty map is indistinguishable at runtime from an analysis that
+        // found nothing (`server/request-dep.ts` answers `true` for any absent
+        // key either way), so every segment and slot silently stops being a
+        // skip candidate and slot caching is off with nothing to show for it.
+        // Fail the build instead (TIM-1300).
+        if (ctx.requestDepMap === undefined) {
+          throw new Error(
+            '[timber] Build manifest: the request-dependency map was never computed. ' +
+              "The RSC environment's buildEnd hook did not run before the client build, " +
+              'so no segment or slot could be skipped on client navigation. This is a ' +
+              'plugin pipeline bug — timber-request-dep must run in the rsc environment.'
+          );
         }
+        ctx.buildManifest.requestDep = ctx.requestDepMap;
 
         // When client JavaScript is disabled, strip JS chunks from the bundle
         // so Rollup never writes them to disk. CSS assets are preserved —

package/src/plugins/entries.ts

@@ -136,6 +136,10 @@ function generateConfigModule(ctx: PluginContext): string {
     csrf: ctx.config.csrf ?? true,
     allowedOrigins: ctx.config.allowedOrigins,
     clientJavascript: ctx.clientJavascript,
+    // Vite's resolved `base` — the deployment path prefix. The client needs
+    // it to address pre-generated RSC payloads in static mode, which live
+    // below the base like every other emitted file (TIM-1261).
+    base: ctx.base,
     dev: ctx.dev ?? false,
     slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
     slowRequestMs: ctx.config.slowRequestMs ?? 3000,