@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

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/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';
@@ -464,6 +464,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

@@ -18,6 +18,7 @@ import type { CaptureSummary } from './server/prebuilt-builder';
 import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+import type { RscManifest } from './plugins/static-build.js';
 import type { HoldingServer } from './dev-tools/holding-server.js';
 import type { ProgramNode } from './plugins/callsite-ast.js';
 
@@ -72,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) */
@@ -97,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.
@@ -171,7 +203,7 @@ export interface PluginContext {
    * Populated during static generation, consumed by adapters to set
    * immutable cache headers for `_rsc/` files. See TIM-1254.
    */
-  rscManifest?: Record<string, string>;
+  rscManifest?: RscManifest;
 }
 
 // ── AST parse memo ───────────────────────────────────────────────────────
@@ -257,6 +289,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,

package/src/plugins/fonts.ts

@@ -62,18 +62,21 @@ export {
  */
 export function timberFonts(ctx: PluginContext): Plugin {
   const pipeline = new FontPipeline({ hashOnRegister: !ctx.dev });
-  let resolvedBase = '/';
 
   return {
     name: 'timber-fonts',
 
     /**
-     * Capture Vite's resolved `base` so every font URL the pipeline emits
-     * (@font-face src, manifest hrefs, dev middleware matching) carries
-     * the prefix. Emitted file locations are unaffected — only URLs.
+     * Push Vite's resolved `base` into the pipeline so every font URL it
+     * emits (@font-face src, manifest hrefs, dev middleware matching)
+     * carries the prefix. Emitted file locations are unaffected — only URLs.
+     *
+     * `config.base` is read here rather than `ctx.base`: this plugin is
+     * `enforce: 'pre'`, so its configResolved runs before timber-root-sync
+     * populates `ctx.base`. Every *later* hook reads `ctx.base` — the single
+     * copy (TIM-1261).
      */
     configResolved(config: ResolvedConfig) {
-      resolvedBase = config.base;
       pipeline.setBase(config.base);
 
       // Font binaries are emitted in generateBundle, after Vite's CSS
@@ -188,7 +191,7 @@ export function timberFonts(ctx: PluginContext): Plugin {
               pipeline.attachCachedFiles(font.id, familyCached);
               pipeline.attachFaces(
                 font.id,
-                generateProductionFontFaces(familyCached, font.display, fontUrlPrefix(resolvedBase))
+                generateProductionFontFaces(familyCached, font.display, fontUrlPrefix(ctx.base))
               );
             }
           } catch (e) {
@@ -211,7 +214,7 @@ export function timberFonts(ctx: PluginContext): Plugin {
      * this middleware.
      */
     configureServer(server: ViteDevServer) {
-      installFontDevMiddleware(server, pipeline, resolvedBase);
+      installFontDevMiddleware(server, pipeline, ctx.base);
     },
 
     /**
@@ -292,7 +295,7 @@ export function timberFonts(ctx: PluginContext): Plugin {
         (msg) => this.warn(msg)
       );
       if (!ctx.buildManifest) return;
-      writeFontManifest(pipeline, ctx.buildManifest, resolvedBase);
+      writeFontManifest(pipeline, ctx.buildManifest, ctx.base);
     },
   };
 }