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

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/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

@@ -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',
       ];

package/src/plugin-context.ts

@@ -248,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

package/src/plugins/routing.ts

@@ -9,21 +9,12 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
-import { generateRouteMap } from '../routing/codegen.js';
-import {
-  buildDirToRouteMap,
-  writeSegmentTypes,
-  type SegmentInfo,
-} from '../routing/segment-codegen.js';
+import { buildDirToRouteMap, type SegmentInfo } from '../routing/segment-codegen.js';
+import { writeRouteCodegen, flushCodegenWrites } from '../routing/codegen-write.js';
 import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
-import {
-  generateManifestModule,
-  generateSearchParamsRegistryModule,
-  generateSchemaModule,
-} from '../routing/manifest-codegen.js';
+import { generateManifestModule, generateSchemaModule } from '../routing/manifest-codegen.js';
 import {
   lintConventions,
   checkAppDirExists,
@@ -34,21 +25,6 @@ import type { PluginContext } from '../plugin-context.js';
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 
-// TIM-830: Search-params registry virtual module.
-//
-// Statically imports the `searchParams` named export from every page
-// that exports one, and registers each definition into the shared
-// search-params registry keyed by the un-interpolated route pattern
-// (e.g. '/products/[id]'). This lets `<Link>` serialize flat
-// `Partial<T>` values at runtime without callers importing the
-// definition at the call site.
-//
-// The imports are STATIC (`import { searchParams as r0 } from '...'`)
-// so Vite/Rolldown tree-shakes each page's component body out of the
-// registry chunk — only the `searchParams` named export is pulled in.
-const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
-const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
-
 // TIM-931: Schema virtual module.
 //
 // When app/schema.ts exists, this module imports it and resolves the
@@ -69,112 +45,26 @@ const SEGMENT_PREFIX = '\0$segment:';
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|schema|\d{3}|[45]xx|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
  *
  * Hooks: resolveId, load, buildStart, configureServer
  */
-/** Absolute path to the generated route map declaration file. */
-const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
-
-/**
- * Content of the timber-env.d.ts file written to the project root.
- *
- * Uses a triple-slash reference so TypeScript auto-discovers the generated
- * route map without the user needing to edit tsconfig.json — same pattern
- * as Next.js's next-env.d.ts.
- *
- * Also references `vite/client` so side-effect imports like
- * `import './globals.css'` type-check without ts(2882), and so
- * `import.meta.env`, `import.meta.hot`, `import.meta.glob`, asset
- * imports (`*.png`, `*.svg`, …), CSS modules, and `?url`/`?raw`/
- * `?inline` query variants all resolve without the user editing
- * tsconfig.json themselves. Next.js's next-env.d.ts plays the same
- * role via `next/types/global`.
- *
- * `vite` is a peer dep of `@timber-js/app`, so the reference always
- * resolves in a correctly-installed project.
- */
-const TIMBER_ENV_DTS = [
-  '// This file is auto-generated by timber.js. Do not edit.',
-  '// It ensures TypeScript picks up the generated route types and',
-  '// Vite-provided ambient types (CSS, assets, import.meta.env, HMR).',
-  '/* eslint-disable @typescript-eslint/triple-slash-reference */',
-  '/// <reference path=".timber/timber-routes.d.ts" />',
-  '/// <reference types="vite/client" />',
-  '',
-].join('\n');
-
-/**
- * Codegen writes that have been started but have not yet landed on disk.
- *
- * `writeCodegen` is deliberately unawaited on the hot path, which leaves a
- * caller no way to know the files exist yet. Anything that tears down the
- * project root — a build process exiting, a test removing its temp root —
- * then races the writes: `rmSync` empties a directory that a pending `mkdir`
- * immediately recreates, and the removal fails with ENOTEMPTY.
- *
- * Every started write registers here and deregisters when it settles, so
- * `flushCodegenWrites()` can await them instead of guessing at a delay.
- */
-const pendingCodegenWrites = new Set<Promise<void>>();
-
-/**
- * Resolve once every codegen write started so far has landed on disk.
- *
- * Safe to call at any time and from anywhere — writes are tracked per process,
- * not per plugin instance, so a caller does not need a handle on the plugin
- * that started them. Never rejects: individual write failures are already
- * swallowed and logged by `writeCodegen`.
- */
-export async function flushCodegenWrites(): Promise<void> {
-  // Loop rather than a single Promise.all: a write started while we were
-  // awaiting would otherwise be missed, and the set would still be non-empty
-  // on return.
-  //
-  // Each round drops what it awaited rather than trusting the per-write
-  // `finally` to have run, so the two removal paths are independent — a
-  // deregistration that stopped firing would leak memory in dev, but it can
-  // never turn this into a spin.
-  while (pendingCodegenWrites.size > 0) {
-    const inFlight = [...pendingCodegenWrites];
-    await Promise.all(inFlight);
-    for (const write of inFlight) pendingCodegenWrites.delete(write);
-  }
-}
-
 /**
  * Write the generated route map and the timber-env.d.ts reference file.
  *
- * Not awaited by callers, to avoid blocking the hot path — use
- * `flushCodegenWrites()` to wait for the writes to land.
- * Errors are swallowed; a missing .d.ts is a developer UX issue, not a runtime failure.
+ * Not awaited, to avoid blocking the hot path — use `flushCodegenWrites()` to
+ * wait for the writes to land. Failures are logged, not thrown: a missing .d.ts
+ * is a developer UX issue in dev/build, not a runtime failure. (`timber check`
+ * calls `writeRouteCodegen` directly and does treat a failure as fatal.)
  */
 function writeCodegen(ctx: PluginContext): void {
   if (!ctx.routeTree) return;
-  const timberDir = join(ctx.root, '.timber');
-  const content = generateRouteMap(ctx.routeTree, { appDir: ctx.appDir, outputDir: timberDir });
-  const routesPath = join(ctx.root, CODEGEN_OUTPUT);
-  const envPath = join(ctx.root, 'timber-env.d.ts');
-  const done = mkdir(timberDir, { recursive: true })
-    .then(() =>
-      Promise.all([
-        writeFile(routesPath, content, 'utf-8'),
-        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
-        writeSegmentTypes(ctx.routeTree!, ctx.appDir, ctx.root),
-      ])
-    )
-    .then(() => undefined)
-    .catch((err) => {
-      // Non-fatal — types are a dev convenience, but log so issues are visible
-      console.warn('[timber] Failed to write codegen output:', err);
-    });
-
-  pendingCodegenWrites.add(done);
-  // `done` has a catch attached, so it never rejects and this stays quiet.
-  void done.finally(() => pendingCodegenWrites.delete(done));
+  void writeRouteCodegen(ctx.routeTree, ctx.appDir, ctx.root).catch((err) => {
+    console.warn('[timber] Failed to write codegen output:', err);
+  });
 }
 
 export function timberRouting(ctx: PluginContext): Plugin {
@@ -204,10 +94,26 @@ export function timberRouting(ctx: PluginContext): Plugin {
     }
 
     ctx.timer.start('route-scan');
-    ctx.routeTree = scanRoutes(ctx.appDir, {
+    const tree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
     });
     ctx.timer.end('route-scan');
+
+    // Lint conventions (empty app, missing methods, missing root layout).
+    // Runs on the scanned tree *before* it is published: error-level findings
+    // are proven-fatal misconfigurations — the app cannot render at all — so
+    // the tree must not reach codegen, the manifest, or a live dev server's
+    // module graph. Fail loudly rather than let the developer discover it as
+    // an unattributed React error on an unrelated page (TIM-1329). Never
+    // deduplicated against `warnedFiles`: an error must not be downgraded to
+    // silence by an earlier scan in the same process.
+    const conventionWarnings = lintConventions(tree, ctx.appDir);
+    const fatal = conventionWarnings.filter((w) => w.level === 'error');
+    if (fatal.length > 0) {
+      throw new Error(formatConventionWarnings(fatal, { color: false }));
+    }
+
+    ctx.routeTree = tree;
     dirToRoute = buildDirToRouteMap(ctx.routeTree, ctx.appDir);
     writeCodegen(ctx);
 
@@ -216,8 +122,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
     // See design/41-global-params.md §Auto-Scaffolding
     warnSchemaValidation(ctx);
 
-    // Lint conventions (empty app, missing methods, missing root layout)
-    const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
     const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
     if (newConventionWarnings.length > 0) {
       for (const w of newConventionWarnings) warnedFiles.add(w.id);
@@ -250,14 +154,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_ID;
       }
 
-      // TIM-830: Search-params registry virtual module
-      if (
-        cleanId === SEARCH_PARAMS_REGISTRY_ID ||
-        cleanId.endsWith(`/${SEARCH_PARAMS_REGISTRY_ID}`)
-      ) {
-        return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
-      }
-
       // TIM-931: Schema virtual module
       if (cleanId === SCHEMA_ID || cleanId.endsWith(`/${SCHEMA_ID}`)) {
         return RESOLVED_SCHEMA_ID;
@@ -297,13 +193,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return generateManifestModule(ctx.routeTree!, ctx.root);
       }
 
-      if (id === RESOLVED_SEARCH_PARAMS_REGISTRY_ID) {
-        if (!ctx.routeTree) {
-          rescan();
-        }
-        return generateSearchParamsRegistryModule(ctx.routeTree!);
-      }
-
       if (id === RESOLVED_SCHEMA_ID) {
         return generateSchemaModule(ctx.appDir);
       }
@@ -362,6 +251,59 @@ export function timberRouting(ctx: PluginContext): Plugin {
       /** Snapshot of the last generated manifest, used to detect structural changes. */
       let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
 
+      /**
+       * Rescan without letting a rejected route tree kill the dev server.
+       *
+       * `rescan()` throws on hard misconfigurations — duplicate conventions,
+       * route collisions, a status file that is not a client component. Those
+       * throws are correct at startup and in `vite build`, but here they run
+       * inside a chokidar listener, where an exception is an unhandled
+       * rejection that takes the process down mid-edit. Report and keep the
+       * last good tree so the server stays up and the fix is one save away.
+       *
+       * Returns false when the scan failed, so callers skip the manifest
+       * regeneration that would otherwise publish a stale tree as fresh.
+       */
+      /**
+       * True while the last rescan is still failing.
+       *
+       * Recovery has to force a reload even when the manifest is byte-identical.
+       * Adding a missing `'use client'` back to a status file changes no route
+       * metadata, so the content-change path would send nothing and leave the
+       * error overlay on screen over a page that is now fine.
+       */
+      let scanFailed = false;
+
+      const rescanSafely = (): boolean => {
+        try {
+          rescan();
+          if (scanFailed) {
+            scanFailed = false;
+            // Force the reload: see `scanFailed`.
+            lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+            invalidateManifest(devServer);
+          }
+          return true;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(
+            `[timber] Route scan failed — keeping previous routes.\n${message}\n`
+          );
+          scanFailed = true;
+
+          // The terminal is not the only surface that needs this. Keeping the
+          // previous tree keeps the *server* alive, but it does not un-edit the
+          // file: Vite still re-transforms it, so the very next render hits the
+          // failure this scan just diagnosed — and the browser's version of it
+          // names nothing. Put the diagnosis where the developer is looking.
+          devServer.hot.send({
+            type: 'error',
+            err: { message, stack: '', plugin: 'timber-routing' },
+          });
+          return false;
+        }
+      };
+
       /**
        * Handle a route-significant file being added or removed.
        * Always triggers a full-reload since the route tree structure changed.
@@ -370,7 +312,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        rescan();
+        if (!rescanSafely()) return;
         lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         invalidateManifest(devServer);
       };
@@ -387,7 +329,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        rescan();
+        if (!rescanSafely()) return;
         const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         if (newManifest !== lastManifest) {
           lastManifest = newManifest;
@@ -449,11 +391,7 @@ function invalidateManifest(server: ViteDevServer): void {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    for (const virtualId of [
-      RESOLVED_VIRTUAL_ID,
-      RESOLVED_SEARCH_PARAMS_REGISTRY_ID,
-      RESOLVED_SCHEMA_ID,
-    ]) {
+    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SCHEMA_ID]) {
       const mod = env.moduleGraph.getModuleById(virtualId);
       if (mod) {
         env.moduleGraph.invalidateModule(mod);

package/src/plugins/shims.ts

@@ -55,7 +55,6 @@ export const SUBPATH_SRC_MAP: Record<string, string> = {
   'cookies': 'cookies/index.ts',
   'params': 'params/index.ts',
   'search-params': 'search-params/index.ts',
-  'segment-params': 'segment-params/index.ts',
 
   'cache/stores/memory': 'cache/stores/memory.ts',
   'cache/stores/redis': 'cache/stores/redis.ts',