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

package/src/server/ssr-wrappers.tsx

@@ -8,13 +8,26 @@
  * Radix UI that rely on useId() internally.
  *
  * The client tree (browser-entry.ts) wraps the RSC element with:
- *   NavigationRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *   NavigationRoot → Fragment(TopLoader, ...) →
  *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
  *
  * The SSR tree must produce the same component boundaries. These wrappers
  * are no-op components that render children directly but exist as fiber
  * nodes to match the client's tree depth.
  *
+ * **What actually shifts an id is a fork, not depth.** `useId` derives from
+ * React's tree context, which only changes where a fiber has more than one
+ * child — here, `Fragment(TopLoader, element)`. A single-child wrapper, plain
+ * component or context provider, leaves every id below it unchanged; that is
+ * verified, not assumed. So the client-only wrappers that take exactly one
+ * child — `SegmentUpdateContext.Provider`, and `PayloadRoot` with the params
+ * provider it renders (TIM-1297) — have no mirror here and need none. Mirror a
+ * new wrapper only if it branches.
+ *
+ * `PendingNavigationProvider` and its `SsrPendingProvider` mirror were both
+ * deleted with the dead pending context (TIM-1307). Removing them shifts no
+ * id: it was a single-child provider, the case the rule above covers.
+ *
  * Related issues: facebook/react#24669, radix-ui/primitives#3700
  * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
  */
@@ -25,11 +38,13 @@ import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 /**
  * SSR equivalent of NavigationRoot.
  *
- * On the client, NavigationRoot uses useState and standalone startTransition, rendering:
- *   PendingNavigationProvider(Fragment(TopLoader, element))
+ * On the client, NavigationRoot uses useState and standalone startTransition,
+ * rendering `Fragment(TopLoader, element)` — or the element alone when the top
+ * loader is disabled.
  *
- * This SSR version matches the component boundary depth without client
- * hooks. It renders SsrPendingProvider → Fragment(SsrTopLoader, children).
+ * The Fragment is the part that matters: it forks, so it advances React's tree
+ * context. Both sides must agree on whether it is there, which is why
+ * `hasTopLoader` is threaded in from the same config the client reads.
  */
 function SsrNavigationRoot({
   children,
@@ -39,20 +54,8 @@ function SsrNavigationRoot({
   hasTopLoader: boolean;
 }): ReactNode {
   if (hasTopLoader) {
-    return createElement(
-      SsrPendingProvider,
-      null,
-      createElement(Fragment, null, createElement(SsrTopLoader, null), children)
-    );
+    return createElement(Fragment, null, createElement(SsrTopLoader, null), children);
   }
-  return createElement(SsrPendingProvider, null, children);
-}
-
-/**
- * SSR equivalent of PendingNavigationProvider.
- * Matches the context.Provider component boundary on the client.
- */
-function SsrPendingProvider({ children }: { children: ReactNode }): ReactNode {
   return children as ReactNode;
 }
 
@@ -98,21 +101,19 @@ function SsrNuqsWrapper({
  *
  * Client tree (browser-entry.ts):
  *   NavigationRoot
- *     → PendingNavigationProvider
- *       → Fragment(TopLoader, element)
- *         → TimberNuqsAdapter
- *           → NuqsAdapterProvider (from createAdapterProvider)
- *             → NavigationProvider
- *               → [RSC element]
+ *     → Fragment(TopLoader, element)
+ *       → TimberNuqsAdapter
+ *         → NuqsAdapterProvider (from createAdapterProvider)
+ *           → NavigationProvider
+ *             → [RSC element]
  *
  * SSR tree (this function):
  *   SsrNavigationRoot
- *     → SsrPendingProvider
- *       → Fragment(SsrTopLoader, element)
- *         → SsrNuqsWrapper
- *           → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
- *             → SsrNavigationProvider
- *               → [RSC element]
+ *     → Fragment(SsrTopLoader, element)
+ *       → SsrNuqsWrapper
+ *         → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *           → SsrNavigationProvider
+ *             → [RSC element]
  *
  * @param element - The decoded RSC element
  * @param searchParams - Request search params for nuqs SSR adapter
@@ -126,7 +127,7 @@ export function wrapSsrElement(
   // Build inside-out to match the client's createElement chain:
   //   NavigationProvider(TimberNuqsAdapter(element))
   //   → passed as initial to NavigationRoot
-  //   → NavigationRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
+  //   → NavigationRoot renders Fragment(TopLoader, initial)
 
   // 1. Innermost: NavigationProvider equivalent
   const withNav = createElement(SsrNavigationProvider, null, element);
@@ -135,7 +136,7 @@ export function wrapSsrElement(
   // eslint-disable-next-line react/no-children-prop -- createElement API
   const withNuqs = createElement(SsrNuqsWrapper, { searchParams, children: withNav });
 
-  // 3. Outermost: NavigationRoot equivalent (PendingNavigationProvider + TopLoader)
+  // 3. Outermost: NavigationRoot equivalent (the TopLoader fork)
   // eslint-disable-next-line react/no-children-prop -- createElement API
   return createElement(SsrNavigationRoot, { hasTopLoader, children: withNuqs });
 }

package/src/server/state-tree-diff.ts

@@ -18,64 +18,17 @@ import { swallow } from './logger.js';
 import { matchUrlParts } from './tree-match.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 
-// ─── Segment Key Computation ─────────────────────────────────────
-
-/**
- * Segment node shape expected by computeSegmentKeys.
- * Matches the relevant fields from ManifestSegmentNode without
- * importing it (avoids circular deps from routing → server).
- */
-interface SegmentKeyInput {
-  urlPath: string;
-  segmentName?: string;
-  segmentType?: string;
-}
-
-/**
- * Compute state-tree keys for a segment chain.
- *
- * Non-group segments use their urlPath as-is. Route groups accumulate
- * ancestor group names to produce globally unique keys:
- *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
- *
- * This is the single source of truth for segment keys — used by the
- * element builder (skip decisions, SegmentOutlet props), segment info
- * (X-Timber-Segments header), and the client cache/state tree.
- */
-export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
-  const keys: string[] = [];
-  let prevKey = '';
-
-  for (const segment of segments) {
-    if (segment.segmentType === 'group') {
-      const base = prevKey === '/' ? '' : prevKey;
-      const key = `${base}/${segment.segmentName}`;
-      keys.push(key);
-      prevKey = key;
-    } else {
-      keys.push(segment.urlPath);
-      prevKey = segment.urlPath;
-    }
-  }
-
-  return keys;
-}
-
-/**
- * Compute a unique key for a parallel route slot.
- * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
- */
-export function computeSlotKey(parentSegmentId: string, slotName: string): string {
-  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
-  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
-  return `${prefix}/${name}`;
-}
-
 // ─── State Tree Parsing ──────────────────────────────────────────
 
 /** Parsed client state tree with segment paths and optional slot paths. */
 export interface ClientStateTree extends Set<string> {
   slots?: Set<string> | null;
+  /**
+   * `app/` directory paths of the segments currently mounted on the client.
+   * Read only by interception scoping — never by the skip decisions.
+   * See design/07-routing.md §"Intercepting Routes" (TIM-1282).
+   */
+  treePaths?: Set<string> | null;
 }
 
 /**
@@ -93,14 +46,20 @@ export function parseClientStateTree(req: Request): ClientStateTree | null {
   if (!header) return null;
 
   try {
-    const parsed = JSON.parse(header) as { segments?: unknown; slots?: unknown };
+    const parsed = JSON.parse(header) as {
+      segments?: unknown;
+      slots?: unknown;
+      treePaths?: unknown;
+    };
     const hasSegments = Array.isArray(parsed.segments) && parsed.segments.length > 0;
     const hasSlots = Array.isArray(parsed.slots) && parsed.slots.length > 0;
-    if (!hasSegments && !hasSlots) {
+    const hasTreePaths = Array.isArray(parsed.treePaths) && parsed.treePaths.length > 0;
+    if (!hasSegments && !hasSlots && !hasTreePaths) {
       return null;
     }
     const result = new Set(hasSegments ? (parsed.segments as string[]) : []) as ClientStateTree;
     result.slots = hasSlots ? new Set(parsed.slots as string[]) : null;
+    result.treePaths = hasTreePaths ? new Set(parsed.treePaths as string[]) : null;
     return result;
   } catch (err) {
     swallow(err, 'malformed X-Timber-State-Tree header');

package/src/server/static-generator.ts

@@ -23,6 +23,12 @@ import type { ManifestRoot, ManifestSegmentNode, ManifestFile } from './route-ma
 import { hasDynamicSegments, hasUserSitemap, resolvePathWithParams } from './sitemap-generator.js';
 import { loadModule } from './safe-load.js';
 import { METADATA_ROUTE_CONVENTIONS, resolveServePathForFile } from './metadata-routes.js';
+import {
+  NOT_FOUND_ENTRY_PATH,
+  NOT_FOUND_PROBE_PATH,
+  resolveNotFoundPage,
+  type NotFoundProbe,
+} from './static-not-found.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -70,6 +76,12 @@ export interface StaticGenerationSummary {
   errors: StaticGenerationError[];
   /** Redirects from middleware/proxy that need platform redirect rules. */
   redirects: StaticRedirectEntry[];
+  /**
+   * Non-fatal problems the build should surface. Unlike `errors`, these do not
+   * fail the build — they name a degraded outcome the developer can act on
+   * (e.g. the not-found probe answering with something other than a 404).
+   */
+  warnings: string[];
 }
 
 export interface StaticGenerationOptions {
@@ -211,7 +223,22 @@ export async function enumerateStaticUrls(
 
   await walk(root);
   urls.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-  return { urls, errors };
+
+  // Drop repeats of the same (path, kind). `generateStaticSegmentParams` is
+  // an application function returning whatever a CMS query gave it, and a
+  // repeated combo asks for the same page twice — identical bytes to the same
+  // file, so it is waste rather than ambiguity. Removing it here keeps the
+  // output-path collision check (TIM-1266) meaning what it says: two
+  // *different* routes competing for one file.
+  const seen = new Set<string>();
+  const unique = urls.filter(({ urlPath, kind }) => {
+    const key = `${kind}:${urlPath}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  return { urls: unique, errors };
 }
 
 /**
@@ -401,7 +428,18 @@ export async function generateStaticSite(
 ): Promise<StaticGenerationSummary> {
   const log = options.log ?? ((msg: string) => console.log(msg));
   const timeoutMs = options.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
-  const summary: StaticGenerationSummary = { rendered: 0, errors: [], redirects: [] };
+  const summary: StaticGenerationSummary = {
+    rendered: 0,
+    errors: [],
+    redirects: [],
+    warnings: [],
+  };
+  // Warnings are recorded and logged from one place so the summary the build
+  // reports and the line the developer reads can never describe different sets.
+  const warn = (message: string) => {
+    summary.warnings.push(message);
+    log(`[timber] Static generation: ${message}`);
+  };
 
   log('[timber] Static generation: enumerating routes…');
 
@@ -548,34 +586,34 @@ export async function generateStaticSite(
     }
   }
 
-  // Render 404.html — the app's not-found page for unmatched URLs.
-  // Static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve this
-  // automatically when no matching file exists.
-  // Uses /_timber/__not_found as the probe path: _timber/ is the framework's
-  // reserved prefix and __not_found is a private segment (double underscore),
-  // so user routes (including catch-all [..slug]) cannot claim this path.
+  // Write 404.html. Always — the classification of what to write, and what
+  // to tell the developer about it, lives in static-not-found.ts.
+  let probe: NotFoundProbe;
   try {
-    const notFoundResponse = await renderUrl(
-      handler,
-      '/_timber/__not_found',
-      'text/html',
-      timeoutMs
-    );
-    if (notFoundResponse.status === 404 && notFoundResponse.body.byteLength > 0) {
-      await options.onEntry({
-        urlPath: '/_timber_not_found',
-        status: notFoundResponse.status,
-        headers: headersToRecord(notFoundResponse.headers),
-        body: notFoundResponse.body,
-        contentType: notFoundResponse.headers.get('content-type') ?? 'text/html',
-        kind: 'html',
-      });
-      log('[timber] Static generation: rendered 404.html');
-    }
-  } catch {
-    log('[timber] Static generation: 404 page render failed — skipping 404.html');
+    const response = await renderUrl(handler, NOT_FOUND_PROBE_PATH, 'text/html', timeoutMs);
+    probe = {
+      kind: 'response',
+      status: response.status,
+      body: response.body,
+      headers: headersToRecord(response.headers),
+      contentType: response.headers.get('content-type') ?? 'text/html',
+    };
+  } catch (error) {
+    probe = { kind: 'threw', error };
   }
 
+  const notFound = resolveNotFoundPage(probe, manifest.root);
+  if (notFound.warning) warn(notFound.warning);
+  await options.onEntry({
+    urlPath: NOT_FOUND_ENTRY_PATH,
+    status: 404,
+    headers: notFound.headers,
+    body: notFound.body,
+    contentType: notFound.contentType,
+    kind: 'html',
+  });
+  log(notFound.logLine);
+
   // Discover and render paginated sub-sitemaps. If /sitemap.xml was an
   // index (contains /sitemap/N.xml references), render each sub-sitemap.
   if (options.autoSitemapEnabled && !hasUserSitemap(manifest.root)) {

package/src/server/static-not-found.ts

@@ -0,0 +1,134 @@
+/**
+ * 404.html generation for static builds.
+ *
+ * `404.html` is written unconditionally (design/11-platform.md item 7). When
+ * the not-found probe does not produce a usable page, the framework default
+ * status page is written instead and the reason is reported as a warning —
+ * a static deploy that silently shipped no 404 page fell back to the host's
+ * generic one, and nothing in the build output said so (TIM-1258).
+ *
+ * The classification lives here, apart from the generation orchestration, so
+ * it can be exercised directly: every branch is a different diagnosis handed
+ * to a developer, and a wrong one sends them to the wrong file.
+ */
+
+import { resolveStatusFile } from './status-code-resolver.js';
+import { DEFAULT_STATUS_PAGE_CONTENT_TYPE, defaultStatusPageHtml } from './default-status-page.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+/**
+ * The probe path. `_timber/` is the framework's reserved prefix and
+ * `__not_found` is a private segment (double underscore), so user routes —
+ * including a catch-all `[...slug]` — cannot claim it.
+ */
+export const NOT_FOUND_PROBE_PATH = '/_timber/__not_found';
+
+/** URL path the static build maps to `404.html`. See plugins/static-build.ts. */
+export const NOT_FOUND_ENTRY_PATH = '/_timber_not_found';
+
+/** What the probe produced: a response, or the failure that replaced one. */
+export type NotFoundProbe =
+  | {
+      kind: 'response';
+      status: number;
+      body: Uint8Array;
+      headers: Record<string, string>;
+      contentType: string;
+    }
+  | { kind: 'threw'; error: unknown };
+
+export interface NotFoundResult {
+  /** Body to write as `404.html` — never empty. */
+  body: Uint8Array;
+  headers: Record<string, string>;
+  contentType: string;
+  /** Non-fatal problem to report, or null when the app rendered its own page. */
+  warning: string | null;
+  /** Build log line. Names *which* page was written. */
+  logLine: string;
+}
+
+/**
+ * Whether the not-found chain has anything to render for this root.
+ *
+ * Asks the resolver rather than inspecting file names: `renderNoMatchPage`
+ * builds its chain from the root segment alone and resolves through exactly
+ * these two calls, so this cannot drift from what the request path does. A
+ * hand-rolled key check gets it wrong — a root that declares only `500.tsx`
+ * has status files but nothing a 404 can select.
+ */
+function rootDeclaresNotFoundPage(root: ManifestSegmentNode): boolean {
+  return (
+    resolveStatusFile(404, [root], 'component') !== null ||
+    resolveStatusFile(404, [root], 'json') !== null
+  );
+}
+
+/** The framework default page, as a `404.html` payload. */
+function frameworkDefault(warning: string): NotFoundResult {
+  return {
+    body: new TextEncoder().encode(defaultStatusPageHtml(404)),
+    headers: { 'content-type': DEFAULT_STATUS_PAGE_CONTENT_TYPE },
+    contentType: DEFAULT_STATUS_PAGE_CONTENT_TYPE,
+    warning,
+    // Say which page was written — "rendered" would claim the app produced it.
+    logLine: '[timber] Static generation: wrote the framework default 404.html',
+  };
+}
+
+/**
+ * Decide what to write as `404.html`, and what to tell the developer.
+ *
+ * @param probe  What requesting {@link NOT_FOUND_PROBE_PATH} produced.
+ * @param root   Root segment of the route manifest — the only thing that can
+ *               distinguish an absent not-found page from a broken one.
+ */
+export function resolveNotFoundPage(
+  probe: NotFoundProbe,
+  root: ManifestSegmentNode
+): NotFoundResult {
+  if (probe.kind === 'threw') {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    return frameworkDefault(
+      `the not-found page failed to render — writing the framework default 404.html. ${message}`
+    );
+  }
+
+  if (probe.status !== 404) {
+    return frameworkDefault(
+      `the not-found probe ${NOT_FOUND_PROBE_PATH} answered ${probe.status}, not 404 — ` +
+        `writing the framework default 404.html instead. A catch-all route or middleware is ` +
+        `claiming unmatched URLs.`
+    );
+  }
+
+  // The pipeline produced nothing, or produced the framework default itself.
+  // Compared by identity against the same builder rather than by a proxy like
+  // "the body is empty", which the default page invalidated.
+  const isDefault =
+    probe.body.byteLength === 0 ||
+    new TextDecoder().decode(probe.body) === defaultStatusPageHtml(404);
+
+  if (isDefault) {
+    // Which of the two it is cannot be read off the response: the deny chain
+    // answers "no status file" and "the status file threw" with the same
+    // bytes. Telling a developer whose 404.tsx just crashed to "add
+    // app/404.tsx" sends them to a file that already exists and buries the
+    // real failure, which the chain logged on its way past.
+    return frameworkDefault(
+      rootDeclaresNotFoundPage(root)
+        ? `the app's not-found page did not render — writing the framework default 404.html. ` +
+            `A root status file exists but produced no page; see the render error logged above.`
+        : `the app has no not-found page — writing the framework default 404.html. ` +
+            `Add app/404.tsx (or 4xx.tsx / error.tsx) to control it.`
+    );
+  }
+
+  return {
+    body: probe.body,
+    headers: probe.headers,
+    contentType: probe.contentType,
+    warning: null,
+    logLine: '[timber] Static generation: rendered 404.html',
+  };
+}

package/src/shared/als-slots.ts

@@ -0,0 +1,72 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+
+interface AlsSlot<T> {
+  /** Register the server-side getter. Called once at module-init time. */
+  set(fn: () => T): void;
+  /** Read through to the registered getter, or throw the client-side message. */
+  get(): T;
+}
+
+function createAlsSlot<T>(message: string): AlsSlot<T> {
+  let fn: (() => T) | undefined;
+  return {
+    set(next) {
+      fn = next;
+    },
+    get() {
+      if (!fn) throw new Error(message);
+      return fn();
+    },
+  };
+}
+
+const searchParamsSlot = createAlsSlot<URLSearchParams>(
+  '[timber] searchParams.get() is only available on the server. ' +
+    'Use searchParams.useQueryStates() on the client.'
+);
+
+const segmentParamsSlot = createAlsSlot<Record<string, string | string[]>>(
+  '[timber] segmentParams.get() is only available on the server. ' +
+    'Use segmentParams.useSegmentParams() on the client.'
+);
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSearchParamsFn = searchParamsSlot.set;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export const getSearchParamsFromAls = searchParamsSlot.get;
+
+/** @internal Called from `server/request-context.ts` at module init. */
+export const _setGetSegmentParamsFn = segmentParamsSlot.set;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export const getSegmentParamsFromAls = segmentParamsSlot.get;

package/src/shared/base-path.ts

@@ -0,0 +1,80 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+
+/** `https://cdn.example.com/`, `//cdn.example.com/` — a base pointing off-origin. */
+function isAbsoluteUrlBase(base: string): boolean {
+  return base.startsWith('//') || /^[a-z][a-z0-9+.-]*:\/\//i.test(base);
+}
+
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export function isRelativeBase(base: string | undefined): boolean {
+  if (!base) return false;
+  return !base.startsWith('/') && !isAbsoluteUrlBase(base);
+}
+
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export function normalizeBasePath(base: string | undefined): string {
+  if (!base) return '/';
+  if (isAbsoluteUrlBase(base) || isRelativeBase(base)) return '/';
+  return base.endsWith('/') ? base : `${base}/`;
+}
+
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function stripBasePath(base: string, pathname: string): string {
+  if (base === '/') return pathname;
+  const withoutTrailingSlash = base.slice(0, -1);
+  if (pathname === withoutTrailingSlash) return '/';
+  if (!pathname.startsWith(base)) return pathname;
+  return pathname.slice(withoutTrailingSlash.length);
+}
+
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export function withBasePath(base: string, path: string): string {
+  if (base === '/') return path;
+  return path.startsWith('/') ? base.slice(0, -1) + path : `${base}${path}`;
+}