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

package/src/plugins/static-build.ts

@@ -10,7 +10,8 @@
 
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { mkdir, readdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { dirname, extname, join, resolve, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import type { PluginContext } from '../plugin-context.js';
@@ -21,11 +22,24 @@ import type {
   StaticRedirectEntry,
 } from '../server/static-generator.js';
 import { mergeRscAssetsManifest } from './adapter-build.js';
+import { htmlEscapeJsonString } from '../server/flight-scripts.js';
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * 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 interface RscManifestEntry {
+  url: string;
+  params?: Record<string, string | string[]>;
+}
+
+export type RscManifest = Record<string, RscManifestEntry>;
+
 export interface StaticValidationError {
   type: 'dynamic-api';
   file: string;
@@ -207,12 +221,20 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   }
 
   const staticDir = join(ctx.buildDir, 'static-pages');
+  // Clean stale RSC artifacts from previous builds before generating
+  // new ones. Without this, already-hashed files from a prior build
+  // would get re-hashed and accumulate in the output.
+  await rm(join(staticDir, '_rsc'), { recursive: true, force: true }).catch(() => {});
   await mkdir(staticDir, { recursive: true });
 
   const sitemapConfig = ctx.config.sitemap;
   const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
 
   const contentTypes: Record<string, string> = {};
+  // Collect route params from RSC entries so they can be inlined
+  // into the manifest instead of written as .params.json sidecars.
+  // Keyed by the unhashed /_rsc/*.rsc URL path. TIM-1255.
+  const routeParams: Record<string, Record<string, string | string[]>> = {};
 
   const summary = await generate({
     autoSitemapEnabled,
@@ -235,12 +257,15 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
       await mkdir(dirname(fullPath), { recursive: true });
       await writeFileAtomic(fullPath, entry.body);
 
-      // Write params sidecar for RSC entries with route params.
-      // Static .rsc files don't carry HTTP headers, so the client
-      // fetches this sidecar to populate useSegmentParams(). TIM-1246.
+      // Capture route params for RSC entries. These are inlined into
+      // the RSC manifest (TIM-1255) instead of written as sidecars.
       if (entry.kind === 'rsc' && entry.headers['x-timber-params']) {
-        const paramsPath = fullPath.replace(/\.rsc$/, '.params.json');
-        await writeFileAtomic(paramsPath, entry.headers['x-timber-params']);
+        const rscUrlKey = entry.urlPath === '/' ? '/_rsc/index.rsc' : `/_rsc${entry.urlPath}.rsc`;
+        try {
+          routeParams[rscUrlKey] = JSON.parse(entry.headers['x-timber-params']);
+        } catch {
+          // Malformed params header — skip
+        }
       }
 
       // Track Content-Type for extensionless API routes so adapters
@@ -269,6 +294,22 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
     ctx.staticContentTypes = contentTypes;
   }
 
+  // Hash RSC flight payloads for immutable caching (TIM-1254).
+  // Renames _rsc/*.rsc → _rsc/*-<hash>.rsc and injects a manifest
+  // into each HTML file so the client can resolve hashed URLs.
+  // Skip when client JS is disabled — no SPA navigation, no RSC fetches,
+  // and injecting a <script> tag would violate the no-JS contract.
+  if (!ctx.clientJavascript.disabled) {
+    const rscManifest = await hashRscPayloads(staticDir, routeParams);
+    if (Object.keys(rscManifest).length > 0) {
+      await injectRscManifestIntoHtml(staticDir, rscManifest);
+      ctx.rscManifest = rscManifest;
+      console.log(
+        `[timber] Static generation: hashed ${Object.keys(rscManifest).length} RSC flight payloads`
+      );
+    }
+  }
+
   // Write _redirects file for platform redirect rules (Cloudflare Pages,
   // Netlify, etc.). Format: /from /to status. See TIM-1245.
   if (summary.redirects.length > 0) {
@@ -294,6 +335,120 @@ async function runStaticGeneration(ctx: PluginContext): Promise<StaticGeneration
   return summary;
 }
 
+// ---------------------------------------------------------------------------
+// RSC flight payload hashing (TIM-1254)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a short content hash for immutable caching.
+ * Uses 8 chars of base64url-encoded SHA-256, matching Vite's asset hash style.
+ */
+export function contentHash(data: Buffer | Uint8Array): string {
+  return createHash('sha256').update(data).digest('base64url').slice(0, 8);
+}
+
+/**
+ * Walk a directory recursively and return all file paths.
+ */
+async function walkDir(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await walkDir(full)));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * 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"}, ...}`
+ *
+ * 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 async function hashRscPayloads(
+  staticDir: string,
+  routeParams?: Record<string, Record<string, string | string[]>>
+): Promise<RscManifest> {
+  const rscDir = join(staticDir, '_rsc');
+  const files = await walkDir(rscDir);
+  const manifest: RscManifest = {};
+
+  for (const filePath of files) {
+    if (!filePath.endsWith('.rsc')) continue;
+
+    const content = await readFile(filePath);
+    const hash = contentHash(content);
+    const rel = relative(staticDir, filePath).replace(/\\/g, '/');
+
+    const base = filePath.slice(0, -'.rsc'.length);
+    const hashedPath = `${base}-${hash}.rsc`;
+
+    await rename(filePath, hashedPath);
+
+    const hashedRel = relative(staticDir, hashedPath).replace(/\\/g, '/');
+    const key = `/${rel}`;
+    const entry: RscManifestEntry = { url: `/${hashedRel}` };
+    if (routeParams?.[key]) {
+      entry.params = routeParams[key];
+    }
+    manifest[key] = entry;
+  }
+
+  return manifest;
+}
+
+/**
+ * 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.
+ *
+ * @internal Exported for testing.
+ */
+export async function injectRscManifestIntoHtml(
+  staticDir: string,
+  manifest: RscManifest
+): Promise<void> {
+  const allFiles = await walkDir(staticDir);
+  const htmlFiles = allFiles.filter((f) => f.endsWith('.html'));
+  const escapedJson = htmlEscapeJsonString(JSON.stringify(manifest));
+  const scriptTag = `<script>window.__TIMBER_RSC_MANIFEST__=${escapedJson}</script>`;
+
+  for (const htmlFile of htmlFiles) {
+    let html = await readFile(htmlFile, 'utf-8');
+    // Insert before </head> so it's available before any client JS runs
+    const headClose = html.indexOf('</head>');
+    if (headClose !== -1) {
+      html = html.slice(0, headClose) + scriptTag + html.slice(headClose);
+    } else {
+      // Fallback: prepend to body
+      html = scriptTag + html;
+    }
+    await writeFile(htmlFile, html);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // User-authored _redirects merge (TIM-1249)
 // ---------------------------------------------------------------------------

package/src/routing/manifest-codegen.ts

@@ -31,12 +31,7 @@ const SINGLE_FILE_KEYS = [
 
 // ── Record-shaped conventions ───────────────────────────────────────────
 // Each entry maps to a node property that holds Record<string, RouteFile>.
-const RECORD_FILE_KEYS = [
-  'statusFiles',
-  'jsonStatusFiles',
-  'legacyStatusFiles',
-  'metadataRoutes',
-] as const;
+const RECORD_FILE_KEYS = ['statusFiles', 'jsonStatusFiles', 'metadataRoutes'] as const;
 
 const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
 

package/src/routing/scanner.ts

@@ -29,17 +29,6 @@ import { ENCODED_SEPARATOR_RE, NULL_BYTE_RE } from '../server/canonicalize.js';
  */
 const PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'denied']);
 
-/**
- * Legacy compat status-code files.
- * Maps legacy file name → HTTP status code for the fallback chain.
- * See design/10-error-handling.md §"Fallback Chain".
- */
-const LEGACY_STATUS_FILES: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
@@ -219,19 +208,6 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       continue;
     }
 
-    // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
-    if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
-      if (!node.legacyStatusFiles) {
-        node.legacyStatusFiles = {};
-      }
-      const existing = node.legacyStatusFiles[name];
-      if (existing) {
-        throwDuplicateConvention(name, existing.filePath, fullPath);
-      }
-      node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
-      continue;
-    }
-
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
     // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
     // When both exist for the same base name, dynamic takes precedence.

package/src/routing/types.ts

@@ -14,7 +14,7 @@
  * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
  *
  * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
- * `legacyStatusFiles`, `metadataRoutes`) are plain `Record<string, …>`
+ * `metadataRoutes`) are plain `Record<string, …>`
  * objects rather than `Map`s so that the build-time tree can be
  * serialized into the virtual route manifest with no shape transform.
  *
@@ -110,8 +110,6 @@ export interface SegmentNode<TFile = RouteFile> {
   jsonStatusFiles?: Record<string, TFile>;
   /** denied.tsx — slot-only denial rendering */
   denied?: TFile;
-  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-  legacyStatusFiles?: Record<string, TFile>;
 
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
   metadataRoutes?: Record<string, TFile>;

package/src/server/deny-boundary.ts

@@ -36,7 +36,6 @@ import type { SerializableError } from '../client/error-reconstituter.js';
 import { requestContextAls } from './als-registry.js';
 import { DenySignal } from './primitives.js';
 import { loadModule } from './safe-load.js';
-import { LEGACY_FILE_TO_STATUS } from './status-code-resolver.js';
 import { withSpan } from './tracing.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
@@ -50,12 +49,11 @@ export interface DenyPageEntry {
   /** The component to render (server or client — both work). */
   component: (...args: unknown[]) => unknown;
   /**
-   * How the entry matched: a status-code file (404.tsx/4xx.tsx), a legacy
-   * compat file (not-found.tsx/forbidden.tsx/unauthorized.tsx), or the
+   * How the entry matched: a status-code file (404.tsx/4xx.tsx) or the
    * error.tsx catch-all. error.tsx entries render with their documented
    * { error, digest, reset } contract, not bare deny props. See TIM-1081.
    */
-  kind: 'status' | 'legacy' | 'error';
+  kind: 'status' | 'error';
   /** MDX files are server components — rendered with plain props, never ErrorReconstituter. */
   isMdx: boolean;
 }
@@ -69,9 +67,7 @@ export interface DenyPageEntry {
  * status-code file components in fallback order:
  * 1. Specific status files (403.tsx, 404.tsx) — exact match
  * 2. Category catch-alls (4xx.tsx) — matches any 4xx
- * 3. Legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
- *    unauthorized.tsx → 401) — exact match
- * 4. error.tsx — catches everything
+ * 3. error.tsx — catches everything
  *
  * Each segment is checked in this order. The chain is ordered so the
  * FIRST match wins at catch time. This mirrors resolveStatusFile's 4xx
@@ -127,29 +123,7 @@ export async function buildDenyPageChain(
     }
   }
 
-  // Pass 2: legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
-  // unauthorized.tsx → 401). Lower priority than status files (a root
-  // 4xx.tsx beats a leaf not-found.tsx) but higher than error.tsx — the
-  // same ordering as resolveStatusFile's resolve4xx. See TIM-1081.
-  for (let i = startIndex; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-    for (const [name, status] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      const file = segment.legacyStatusFiles[name];
-      if (!file) continue;
-      const mod = await loadModule(file).catch(() => null);
-      if (mod?.default) {
-        chain.push({
-          status,
-          component: mod.default as (...args: unknown[]) => unknown,
-          kind: 'legacy',
-          isMdx: isMdxFilePath(file.filePath),
-        });
-      }
-    }
-  }
-
-  // Pass 3: error.tsx files — lowest priority catch-all.
+  // Pass 2: error.tsx files — lowest priority catch-all.
   // Only added AFTER all status and legacy files so they never shadow a
   // more specific file from an ancestor segment.
   for (let i = startIndex; i >= 0; i--) {
@@ -202,7 +176,7 @@ export function renderMatchingDenyPage(
  * Build the element for a matched deny chain entry with the props contract
  * the file's convention documents:
  *
- * - Status-code and legacy files: { status, dangerouslyPassData }
+ * - Status-code files: { status, dangerouslyPassData }
  * - error.tsx (TSX): { error, digest, reset } via ErrorReconstituter, plus
  *   { status, dangerouslyPassData } for dual-shape implementations. Without
  *   the Error prop, any error.tsx written per the docs (reading

package/src/server/deny-renderer.ts

@@ -76,13 +76,13 @@ function isApiRoute(segments: ReadonlyArray<ManifestSegmentNode>): boolean {
 function buildDenyElement(
   deny: DenySignal,
   component: (...args: unknown[]) => unknown,
-  resolutionKind: 'exact' | 'category' | 'legacy' | 'error',
+  resolutionKind: 'exact' | 'category' | 'error',
   filePath: string
 ): React.ReactElement {
   const entry: DenyPageEntry = {
     status: deny.status,
     component,
-    kind: resolutionKind === 'error' ? 'error' : resolutionKind === 'legacy' ? 'legacy' : 'status',
+    kind: resolutionKind === 'error' ? 'error' : 'status',
     isMdx: isMdxFilePath(filePath),
   };
   return renderDenyEntry(entry, deny.status, deny.data);

package/src/server/pipeline-outcome.ts

@@ -132,7 +132,7 @@ export async function outcomeToResponse(
           `[timber] DenySignal(${outcome.signal.status}) from ${outcome.phase} phase — ` +
             `no renderDenyFallback configured, returning bare ${outcome.signal.status} response\n` +
             `  Request: ${ctx.method} ${ctx.path}\n` +
-            `  Add a not-found.tsx or error.tsx to render a custom deny page.`
+            `  Add a status-code file (e.g. 404.tsx) or error.tsx to render a custom deny page.`
         );
       }
       return new Response(null, { status: outcome.signal.status, headers });

package/src/server/prebuilt-builder.ts

@@ -235,13 +235,7 @@ async function enumerateCombos(
 ): Promise<ParamCombo[] | null> {
   if (!hasDynamicSegments(route.urlPath)) return [{}];
 
-  let generateFn = pageModule.generateStaticSegmentParams;
-  if (typeof generateFn !== 'function' && typeof pageModule.generateStaticParams === 'function') {
-    generateFn = pageModule.generateStaticParams;
-    log(
-      `[timber] ${route.page.filePath}: generateStaticParams is deprecated — rename to generateStaticSegmentParams`
-    );
-  }
+  const generateFn = pageModule.generateStaticSegmentParams;
   if (typeof generateFn !== 'function') {
     log(
       `[timber] cache.component: route ${route.urlPath} has prebuilt components but no ` +

package/src/server/primitives.ts

@@ -201,15 +201,6 @@ export function deny(statusOrOptions?: number | DenyOptions, data?: JsonSerializ
   throw new DenySignal(status, resolvedData);
 }
 
-/**
- * @deprecated Use `deny(404)` instead.
- * Kept for internal use by the Next.js shim layer.
- * @internal
- */
-export function notFound(): never {
-  deny(404);
-}
-
 // Single source of truth shared with the client next/navigation shim —
 // see shared/redirect-type.ts.
 export { RedirectType } from '../shared/redirect-type.js';
@@ -334,15 +325,6 @@ export function redirect(path: string, statusOrOptions?: number | RedirectOption
   throw new RedirectSignal(resolvedPath, status);
 }
 
-/**
- * @deprecated Use `redirect(path, { permanent: true })` instead.
- * Kept for internal use by the Next.js shim layer.
- * @internal
- */
-export function permanentRedirect(path: string, options?: Omit<RedirectOptions, 'status'>): never {
-  redirect(path, { permanent: true, ...options });
-}
-
 /**
  * Redirect to an external URL. The origin must be in the provided allow-list.
  *

package/src/server/rsc-entry/render-route.ts

@@ -115,10 +115,10 @@ export async function renderRoute(
       buildManifest.metadataRouteHashes
     );
   } catch (error) {
-    // Param coercion failed — render the custom 404 page (status files / not-found).
+    // Param coercion failed — render the custom 404 page via status files.
     // Previously returned a bare Response(null, { status: 404 }) which bypassed
-    // custom not-found pages. Now routes through renderNoMatchPage so apps with
-    // 404.tsx / not-found status files render their custom page.
+    // custom 404 pages. Now routes through renderNoMatchPage so apps with
+    // 404.tsx render their custom page.
     if (error instanceof ParamCoercionError) {
       return renderNoMatchPage(req, rootSegment, responseHeaders, clientBootstrap);
     }

package/src/server/sitemap-generator.ts

@@ -187,13 +187,7 @@ export async function resolveSitemapUrls(
       // Dynamic route — try to call generateStaticSegmentParams
       try {
         const mod = await loadModule(route.pageLoader);
-        let generateFn = mod.generateStaticSegmentParams;
-        if (typeof generateFn !== 'function' && typeof mod.generateStaticParams === 'function') {
-          generateFn = mod.generateStaticParams;
-          console.warn(
-            `[timber] ${route.pageLoader.filePath}: generateStaticParams is deprecated — rename to generateStaticSegmentParams`
-          );
-        }
+        const generateFn = mod.generateStaticSegmentParams;
         if (typeof generateFn !== 'function') {
           // No generateStaticSegmentParams export — skip this dynamic route
           continue;

package/src/server/static-generator.ts

@@ -227,15 +227,7 @@ async function expandDynamicRoute(
 ): Promise<string[] | null> {
   const mod = await loadModuleWithTimeout(page, timeoutMs);
 
-  let generateFn = mod.generateStaticSegmentParams;
-  if (typeof generateFn !== 'function' && typeof mod.generateStaticParams === 'function') {
-    generateFn = mod.generateStaticParams;
-    log(
-      `[timber] ${page.filePath}: generateStaticParams is deprecated — ` +
-        `rename to generateStaticSegmentParams`
-    );
-  }
-
+  const generateFn = mod.generateStaticSegmentParams;
   if (typeof generateFn !== 'function') return null;
 
   const combos = (await (generateFn as () => Promise<unknown>)()) as Record<
@@ -284,15 +276,7 @@ async function expandDynamicApiRoute(
 ): Promise<string[] | null> {
   const mod = await loadModuleWithTimeout(route, timeoutMs);
 
-  let generateFn = mod.generateStaticSegmentParams;
-  if (typeof generateFn !== 'function' && typeof mod.generateStaticParams === 'function') {
-    generateFn = mod.generateStaticParams;
-    log(
-      `[timber] ${route.filePath}: generateStaticParams is deprecated — ` +
-        `rename to generateStaticSegmentParams`
-    );
-  }
-
+  const generateFn = mod.generateStaticSegmentParams;
   if (typeof generateFn !== 'function') return null;
 
   const combos = (await (generateFn as () => Promise<unknown>)()) as Record<

package/src/server/status-code-resolver.ts

@@ -19,9 +19,8 @@
  *
  * **Component chain (4xx):**
  *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- *   Pass 4 — framework default (returns null)
+ *   Pass 2 — error.tsx (leaf → root)
+ *   Pass 3 — framework default (returns null)
  *
  * **JSON chain (4xx and 5xx):**
  *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
@@ -40,7 +39,6 @@ import type { SegmentNode } from '../routing/types.js';
 export type StatusFileKind =
   | 'exact' // e.g. 403.tsx matched status 403
   | 'category' // e.g. 4xx.tsx matched status 403
-  | 'legacy' // e.g. not-found.tsx matched status 404
   | 'error'; // error.tsx as last resort
 
 /** Response format family for status-code resolution. */
@@ -71,24 +69,6 @@ export interface SlotDeniedResolution<TFile> {
   kind: SlotDeniedKind;
 }
 
-// ─── Legacy Compat Mapping ───────────────────────────────────────────────────
-
-/**
- * Maps legacy file convention names to their corresponding HTTP status codes.
- * Only used in the 4xx component fallback chain. Exported so the in-tree
- * deny chain (deny-boundary.ts) uses the same mapping — see TIM-1081.
- */
-export const LEGACY_FILE_TO_STATUS: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
-/** Reverse index: status code → legacy file name. Built once at module load. */
-const STATUS_TO_LEGACY_FILE: Record<number, string> = Object.fromEntries(
-  Object.entries(LEGACY_FILE_TO_STATUS).map(([name, status]) => [status, name])
-);
-
 // ─── Lookup Helpers ──────────────────────────────────────────────────────
 
 /**
@@ -113,23 +93,6 @@ function lookupInGroup<TFile>(
   return null;
 }
 
-/**
- * Look up the legacy convention file (`not-found.tsx` / `forbidden.tsx` /
- * `unauthorized.tsx`) for `status` on a single segment. Returns null if
- * `status` has no legacy mapping or the file isn't present.
- */
-function lookupLegacy<TFile>(
-  group: Record<string, TFile> | undefined,
-  status: number,
-  segmentIndex: number
-): StatusFileResolution<TFile> | null {
-  if (!group) return null;
-  const name = STATUS_TO_LEGACY_FILE[status];
-  if (!name) return null;
-  const file = group[name];
-  return file ? { file, status, kind: 'legacy', segmentIndex } : null;
-}
-
 // ─── Resolver ────────────────────────────────────────────────────────────────
 
 /**
@@ -155,7 +118,7 @@ export function resolveStatusFile<TFile>(
 }
 
 /**
- * 4xx component fallback chain — three separate full passes leaf→root.
+ * 4xx component fallback chain — two separate full passes leaf→root.
  *
  * The passes must be separate (not interleaved per-segment) so that a
  * root-level `404.tsx` beats a leaf-level `error.tsx`. The 5xx chain
@@ -164,8 +127,7 @@ export function resolveStatusFile<TFile>(
  * separately.
  *
  *   Pass 1 — {status}.tsx → 4xx.tsx           (statusFiles)
- *   Pass 2 — not-found / forbidden / unauthorized (legacyStatusFiles)
- *   Pass 3 — error.tsx                         (error)
+ *   Pass 2 — error.tsx                         (error)
  */
 function resolve4xx<TFile>(
   status: number,
@@ -178,11 +140,6 @@ function resolve4xx<TFile>(
     if (r) return r;
   }
 
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const r = lookupLegacy(segments[i].legacyStatusFiles, status, i);
-    if (r) return r;
-  }
-
   for (let i = segments.length - 1; i >= 0; i--) {
     const errorFile = segments[i].error;
     if (errorFile) {

package/src/shims/navigation-client.ts

@@ -2,15 +2,15 @@
  * Shim: next/navigation (client environment only)
  *
  * Re-exports the client-side hooks from timber's client API, and implements
- * client-render `redirect()` / `permanentRedirect()` / `notFound()` without
- * pulling server/primitives.ts into the browser bundle.
+ * client-render `redirect()` without pulling server/primitives.ts into the
+ * browser bundle.
  *
- * Next.js supports calling redirect()/notFound() during client component
- * render. timber matches that by throwing a plain Error carrying the same
- * JSON digest the server pipeline attaches to RedirectSignal/DenySignal.
- * TimberErrorBoundary recognizes the digest and converts it to an SPA
- * navigation (redirect) or a status-code fallback (notFound), and
- * browser-dev's isFrameworkSignalError() keeps it out of the dev overlay.
+ * Next.js supports calling redirect() during client component render.
+ * timber matches that by throwing a plain Error carrying the same JSON
+ * digest the server pipeline attaches to RedirectSignal. TimberErrorBoundary
+ * recognizes the digest and converts it to an SPA navigation (replace
+ * semantics), and browser-dev's isFrameworkSignalError() keeps it out of
+ * the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
  * where the real server primitives produce proper HTTP responses.
@@ -59,21 +59,3 @@ export function redirect(path: string, _type?: RedirectTypeValue): never {
   assertRelativeRedirectPath(path);
   throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 302 });
 }
-
-/**
- * Client-render permanent redirect. On the client there is no HTTP status —
- * this behaves identically to redirect() apart from the digest's status.
- */
-export function permanentRedirect(path: string, _type?: RedirectTypeValue): never {
-  assertRelativeRedirectPath(path);
-  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 308 });
-}
-
-/**
- * Client-render notFound. Throws a deny-digest error (status 404) that the
- * nearest matching TimberErrorBoundary renders as the 404 fallback. The
- * message matches DenySignal's so digest-less fallback parsing still works.
- */
-export function notFound(): never {
-  throwSignal('Access denied with status 404', { type: 'deny', status: 404, data: null });
-}

package/src/shims/navigation.ts

@@ -21,7 +21,3 @@ export {
 
 // Functions (server-side)
 export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';
-
-// Next.js compat aliases — these are not part of timber's primary API.
-// They exist so that libraries importing from 'next/navigation' still work.
-export { permanentRedirect, notFound } from '../server/primitives.js';