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

package/src/routing/export-detect.ts

@@ -20,7 +20,13 @@ interface AstNode {
     exportKind?: string;
   }>;
   id?: { name: string };
-  declarations?: Array<{ id?: { name: string } }>;
+  declarations?: Array<{ id?: { name: string }; init?: AstNode }>;
+  /** Set on re-exports: `export { X } from './y'`. Absent on local exports. */
+  source?: { value?: string } | null;
+  /** Set on runtime-transparent wrappers: `X as T`, `X satisfies T`, `(X)`, `X!`. */
+  expression?: AstNode;
+  /** Set on `Identifier` nodes. */
+  name?: string;
 }
 
 interface ProgramNode {
@@ -71,19 +77,41 @@ function collectNamedExports(program: ProgramNode): Set<string> {
   return names;
 }
 
+/**
+ * The specifier exporting a *runtime* default from this statement, if any.
+ *
+ * Type-only exports erase, so they are not default exports at runtime — and
+ * TypeScript spells that two ways, on two different nodes: `export type { X as
+ * default }` marks the **statement**, `export { type X as default }` marks the
+ * **specifier**. Both have to be checked, or a type alias reads as a component:
+ * a status file whose only default is a type has nothing for the error boundary
+ * to receive (the renderer's `mod?.default` skips it), so treating it as one
+ * would fail a build over a file that cannot break anything.
+ *
+ * One implementation because two callers must agree on what "has a default
+ * export" means: `hasDefaultExport` decides whether to warn that a page has
+ * none, and `fileDefaultExportIsLocalValue` decides whether to fail the build.
+ */
+function defaultSpecifier(stmt: AstNode): NonNullable<AstNode['specifiers']>[number] | null {
+  if (stmt.type !== 'ExportNamedDeclaration' || !stmt.specifiers) return null;
+  if (stmt.exportKind === 'type') return null;
+  for (const spec of stmt.specifiers) {
+    if (spec.exportKind === 'type') continue;
+    if (spec.exported?.name === 'default') return spec;
+  }
+  return null;
+}
+
 /**
  * Check whether a program has a default export.
  * Handles: `export default ...`, `export { X as default }`,
- * `export { default } from '...'`.
+ * `export { default } from '...'`. Type-only defaults do not count —
+ * see `defaultSpecifier`.
  */
 function hasDefaultExport(program: ProgramNode): boolean {
   for (const stmt of program.body) {
     if (stmt.type === 'ExportDefaultDeclaration') return true;
-    if (stmt.type === 'ExportNamedDeclaration' && stmt.specifiers) {
-      for (const spec of stmt.specifiers) {
-        if (spec.exported?.name === 'default') return true;
-      }
-    }
+    if (defaultSpecifier(stmt)) return true;
   }
   return false;
 }
@@ -152,6 +180,122 @@ export function fileHasDefaultExport(filePath: string): boolean {
   }
 }
 
+/** Node types whose value is unambiguously constructed by this module. */
+const FUNCTION_LIKE = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'ClassDeclaration',
+  'ClassExpression',
+]);
+
+/**
+ * Expression wrappers that erase at runtime and so cannot change where a value
+ * was constructed: `X as T`, `X satisfies T`, `<T>X`, `X!`, `X<T>`, `(X)`.
+ */
+const TRANSPARENT_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'TSInstantiationExpression',
+  'ParenthesizedExpression',
+]);
+
+/**
+ * Strip runtime-transparent wrappers so the node underneath can be classified.
+ *
+ * Without this, `(() => <h1 />) satisfies React.FC` reads as a
+ * `TSSatisfiesExpression` rather than the arrow function it compiles to, and a
+ * provably-local component is misread as one whose origin cannot be
+ * determined — turning a build error into a warning.
+ */
+function unwrapTransparent(node: AstNode): AstNode {
+  let current = node;
+  while (TRANSPARENT_WRAPPERS.has(current.type) && current.expression) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/**
+ * Whether `name` is bound at module top level to a function or class written
+ * in this file. An imported binding can never match: imports are
+ * `ImportDeclaration` specifiers, not function/class/variable declarations,
+ * and a module-level name cannot be both.
+ */
+function bindsLocalFunction(program: ProgramNode, name: string): boolean {
+  for (const stmt of program.body) {
+    // `export function X() {}` binds X locally too — unwrap the export.
+    const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt;
+    if (!decl) continue;
+    if (
+      (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') &&
+      decl.id?.name === name
+    ) {
+      return true;
+    }
+    if (decl.type === 'VariableDeclaration') {
+      for (const d of decl.declarations ?? []) {
+        if (d.id?.name === name && d.init && FUNCTION_LIKE.has(unwrapTransparent(d.init).type)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether the default export is *provably* a value constructed by this module:
+ * `export default function/class/() => {}`, or a name bound to a function or
+ * class declared here — whether it leaves via `export default Name` or
+ * `export { Name as default }`. Both spellings are the same fact about where
+ * the value was built, so both must answer the same way.
+ *
+ * This is the sound half of "is this a server component?". A file with no
+ * `'use client'` directive whose default export is built here is a server
+ * component, full stop. Everything else — `export { default } from
+ * './client-thing'`, `export default Imported`, `export default memo(X)`,
+ * an unparseable file — returns false, because the exported value may have
+ * been minted in a module that *does* carry the directive. Callers must not
+ * infer "server component" from a missing directive alone.
+ */
+export function fileDefaultExportIsLocalValue(filePath: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const source = readFileCached(filePath);
+    const program = tryParse(source);
+    if (!program) return false;
+    for (const stmt of program.body) {
+      if (stmt.type === 'ExportDefaultDeclaration') {
+        const decl = stmt.declaration && unwrapTransparent(stmt.declaration);
+        if (!decl) return false;
+        if (FUNCTION_LIKE.has(decl.type)) return true;
+        if (decl.type === 'Identifier' && decl.name) {
+          return bindsLocalFunction(program, decl.name);
+        }
+        return false;
+      }
+
+      // `export { Name as default }` — the same default export by another
+      // spelling. `hasDefaultExport` already counts it, so an analysis that
+      // skipped it here would let the exact defect this powers slip through
+      // as a warning.
+      const spec = defaultSpecifier(stmt);
+      if (spec) {
+        // `export { X as default } from './client-thing'` re-exports another
+        // module's value — the directive governing it lives over there.
+        if (stmt.source) return false;
+        return spec.local?.name ? bindsLocalFunction(program, spec.local.name) : false;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if a file has any `export * from '...'` declarations.
  * Returns false if the file doesn't exist or can't be parsed.

package/src/routing/link-codegen.ts

@@ -24,13 +24,24 @@
  */
 
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import {
-  buildCodecChainType,
-  buildSchemaParamType,
-  formatSearchParamsType,
-} from './codegen-shared.js';
+import { buildSchemaParamType } from './codegen-shared.js';
 import { classifyUrlSegment } from './segment-classify.js';
 
+/**
+ * The `searchParams` prop type, emitted identically on every Link variant
+ * — per-route pattern, resolved template, and catch-all.
+ *
+ * TIM-1343: there is no per-route narrowing any more. `params.ts` is gone,
+ * so codegen has no definition to read a `SearchParamsDefinition<T>` from.
+ * Type safety moved to the value's construction site instead: callers write
+ * `definition.buildSearchParams({ ... })`, which checks `Partial<T>` there
+ * and returns a query STRING — the only shape that survives the RSC Flight
+ * boundary. A plain record is the uncodec'd escape hatch. See `client/link.tsx` §"searchParams prop shapes".
+ *
+ * Declared once so the three emission sites cannot drift apart.
+ */
+export const SEARCH_PARAMS_PROP_TYPE = 'string | Record<string, unknown>';
+
 /** Shared Link base-props type literal used in every emitted call signature. */
 export const LINK_BASE_PROPS_TYPE =
   "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
@@ -71,23 +82,18 @@ export function buildResolvedPattern(route: RouteEntry): string | null {
  * (convenience — values are stringified at runtime). Catch-all and
  * optional catch-all remain `string[]` / `string[] | undefined`.
  *
- * When the segment's params chain (TIM-834) declares a typed codec, the
- * inferred type from the codec wins via a nested conditional.
+ * With a global schema, the schema codec's inferred type wins. Without
+ * one, a URL segment is a raw string (widened to string | number for
+ * Link convenience) — per-segment codec chains were deleted in TIM-1342.
  */
-export function formatLinkParamsType(
-  params: ParamEntry[],
-  importBase?: string,
-  hasSchema?: boolean
-): string {
+export function formatLinkParamsType(params: ParamEntry[], hasSchema?: boolean): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
     const fallback = p.type === 'string' ? 'string | number' : p.type;
-    const codecType = hasSchema
-      ? buildSchemaParamType(p, fallback)
-      : buildCodecChainType(p, importBase, fallback);
+    const codecType = hasSchema ? buildSchemaParamType(p, fallback) : fallback;
     return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
@@ -109,15 +115,7 @@ export function formatLinkCatchAllOverloads(): string[] {
   const lines: string[] = [];
   const baseProps = LINK_BASE_PROPS_TYPE;
 
-  // TIM-830: the catch-all signatures accept EITHER the legacy
-  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
-  // values object. External/computed hrefs can't be looked up in the
-  // runtime registry, so the wrapped form is still the reliable path;
-  // the flat form is kept permissive for callers migrating from typed-
-  // route hrefs to computed strings. `resolveHref` discriminates at
-  // runtime via the presence of a `definition` key.
-  const catchAllSearchParams =
-    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
+  const catchAllSearchParams = SEARCH_PARAMS_PROP_TYPE;
 
   // ExternalHref inlined here rather than referenced as an exported
   // alias so the generated .d.ts stands alone without source imports.
@@ -207,11 +205,7 @@ export function formatLinkCatchAllOverloads(): string[] {
  * so the resolved-template-vs-pattern ordering reduces to placing the
  * pattern variant before the resolved-template variant inside the union.
  */
-export function formatTypedLinkOverloads(
-  routes: RouteEntry[],
-  importBase?: string,
-  hasSchema?: boolean
-): string[] {
+export function formatTypedLinkOverloads(routes: RouteEntry[], hasSchema?: boolean): string[] {
   const lines: string[] = [];
   const baseProps = LINK_BASE_PROPS_TYPE;
 
@@ -234,52 +228,25 @@ export function formatTypedLinkOverloads(
     // segmentParams. `Record<string, unknown>` keeps generic spreads
     // compiling and gives a readable error if a non-object is passed.
     const paramsProp = hasDynamicParams
-      ? `segmentParams: ${formatLinkParamsType(route.params, importBase, hasSchema)}`
+      ? `segmentParams: ${formatLinkParamsType(route.params, hasSchema)}`
       : 'segmentParams?: Record<string, unknown>';
 
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : null;
-    // TIM-830: pattern href uses the FLAT `Partial<T>` shape — the
-    // runtime registry is keyed by the un-interpolated pattern.
-    //
-    // TIM-833: when the route has NO searchParams definition, use
-    // `Record<string, unknown>` (open shape) instead of
-    // `Record<string, never>` so generic `LinkProps`-spreading wrappers
-    // compile. The trade-off vs the original TIM-835 strict shape is
-    // that excess searchParams keys on a no-def route no longer raise
-    // a type error — but those keys are runtime no-ops anyway, and
-    // wrapper compatibility is the more common pain point. Routes WITH
-    // a searchParams definition still get strict `Partial<T>` typing.
-    const patternSearchParamsProp = searchParamsType
-      ? `searchParams?: Partial<${searchParamsType}>`
-      : 'searchParams?: Record<string, unknown>';
+    // TIM-1343: searchParams is no longer typed per-route. There is no
+    // convention file to read a definition from, so codegen has nothing to
+    // narrow with — the value is either a URLSearchParams built by
+    // `definition.buildSearchParams()` (which type-checks its own
+    // `Partial<T>` at that call) or a plain String()-coerced record.
+    const searchParamsProp = `searchParams?: ${SEARCH_PARAMS_PROP_TYPE}`;
 
     // Pattern variant FIRST (more specific).
     variants.push(
-      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`
+      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${searchParamsProp} }`
     );
 
     // Resolved-template variant SECOND (looser, matches interpolated hrefs).
     if (hasDynamicParams) {
       const templatePattern = buildResolvedPattern(route);
       if (templatePattern) {
-        // TIM-830: resolved-template href keeps the WRAPPED
-        // `{ definition, values }` shape — the registry can't be looked
-        // up by an already-interpolated href.
-        //
-        // TIM-833: searchParams falls back to `Record<string, unknown>`
-        // (was `Record<string, never>`) when the route has no
-        // definition, mirroring the pattern-variant change above. The
-        // resolved-template `segmentParams` is intentionally KEPT as
-        // `Record<string, never>` below to preserve TIM-835's
-        // pattern-variant typo detection: loosening segmentParams here
-        // would let the resolved-template variant shadow the pattern
-        // variant on literal pattern hrefs and silently swallow keyed
-        // typos like `<Link href="/[id]" segmentParams={{ idz: 1 }} />`.
-        const resolvedSearchParamsProp = searchParamsType
-          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-          : 'searchParams?: Record<string, unknown>';
         // TIM-835: `Record<string, never>` for segmentParams forbids ANY
         // provided keys on the resolved-template variant. Without this,
         // the resolved-template would shadow the pattern variant for
@@ -288,7 +255,7 @@ export function formatTypedLinkOverloads(
         // and the looser variant would silently swallow segmentParams
         // type errors.
         variants.push(
-          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`
+          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${searchParamsProp} }`
         );
       }
     }

package/src/routing/manifest-codegen.ts

@@ -1,6 +1,6 @@
 /**
  * Route manifest codegen — generates virtual module source for the route
- * manifest, search-params registry, and global schema.
+ * manifest and the global schema loader.
  *
  * Extracted from plugins/routing.ts to keep it under the 500-line budget.
  * See design/18-build-system.md §"Virtual Modules".
@@ -11,7 +11,6 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { collectInterceptionRewrites } from './interception.js';
-import { fileHasExport } from './export-detect.js';
 import type { RouteTree, SegmentNode, RouteFile } from './types.js';
 
 // ── Single-file conventions ─────────────────────────────────────────────
@@ -26,7 +25,6 @@ const SINGLE_FILE_KEYS = [
   'error',
   'default',
   'denied',
-  'params',
 ] as const;
 
 // ── Record-shaped conventions ───────────────────────────────────────────
@@ -107,10 +105,6 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
       }
     }
 
-    // searchParams is now a named export from page.tsx, not a separate file.
-    // The page module's searchParams export is loaded via the page's lazy import.
-    // Runtime registration happens in the route loader using the page module.
-
     // Record-shaped conventions — table-driven
     for (const key of RECORD_FILE_KEYS) {
       const record = node[key];
@@ -190,58 +184,6 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
   return code;
 }
 
-// ── Search-params registry ──────────────────────────────────────────────
-
-/**
- * Walk the route tree and collect every page that exports a
- * `searchParams` definition, then emit a module that statically imports
- * each export and registers it into the shared search-params registry.
- */
-export function generateSearchParamsRegistryModule(tree: RouteTree): string {
-  const entries: Array<{ urlPath: string; filePath: string }> = [];
-
-  function walk(node: SegmentNode): void {
-    if (node.page) {
-      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
-      } else if (fileHasSearchParamsExport(node.page.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
-      }
-    }
-    for (const child of node.children) walk(child);
-    for (const slot of Object.values(node.slots)) walk(slot);
-  }
-  walk(tree.root);
-
-  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-
-  const lines: string[] = [];
-  lines.push('// Auto-generated search-params registry — do not edit.');
-  lines.push('// Generated by timber-routing plugin (TIM-830).');
-  lines.push('');
-  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
-  lines.push('');
-
-  entries.forEach((entry, i) => {
-    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
-  });
-  lines.push('');
-
-  entries.forEach((entry, i) => {
-    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
-  });
-  lines.push('');
-
-  lines.push('export {};');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
-function fileHasSearchParamsExport(filePath: string): boolean {
-  return fileHasExport(filePath, 'searchParams');
-}
-
 // ── Schema module ───────────────────────────────────────────────────────
 
 /**

package/src/routing/scanner.ts

@@ -35,7 +35,7 @@ const PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'den
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
-const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'params']);
+const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route']);
 
 /**
  * Status-code file patterns:
@@ -184,12 +184,12 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       continue;
     }
 
-    // Fixed conventions (middleware, access, route, params) — only
+    // Fixed conventions (middleware, access, route) — only
     // .ts/.tsx/.js/.jsx, never pageExtensions like .mdx. The regex is
     // anchored: mts/cts/mjs/cjs (and stray tail matches like `.foots`)
     // are NOT recognized. See design/07-routing.md §"Page Extensions".
     if (FIXED_CONVENTIONS.has(name) && /^[jt]sx?$/.test(ext)) {
-      const key = name as 'middleware' | 'access' | 'route' | 'params';
+      const key = name as 'middleware' | 'access' | 'route';
       const existing = node[key];
       if (existing) {
         throwDuplicateConvention(name, existing.filePath, fullPath);

package/src/routing/segment-keys.ts

@@ -144,3 +144,40 @@ export function computeSlotKey(parentSegmentId: string, slotName: string): strin
   const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
   return `${prefix}/${name}`;
 }
+
+/**
+ * Compute a content key for a parallel route slot.
+ *
+ * The content key encodes everything that determines the slot's rendered
+ * output for a given navigation: the slot key (which includes the owning
+ * segment's identity and the slot name), the URL parts consumed by the
+ * owning segment (which determine parent params the slot page might
+ * read), the matched page file (or a sentinel for `default.tsx`), and
+ * the slot's own extracted params.
+ *
+ * The slot key prevents cross-group collisions: two route groups at the
+ * same URL level each owning a `@sidebar` slot produce different keys
+ * even when both fall back to `default.tsx`.
+ *
+ * The key is opaque to the client — it stores whatever the server sent
+ * and advertises it back. The server computes the destination key and
+ * checks membership. This eliminates the need for the server to
+ * reconstruct the client's state from a departing URL.
+ *
+ * See design/07-routing.md §"Segment Tree Diffing on Navigation"
+ */
+export function computeSlotContentKey(
+  slotKey: string,
+  ownerParts: string[],
+  entryFile: string | null,
+  slotParams: Record<string, string | string[]>
+): string {
+  const owner = ownerParts.join('/');
+  const entry = entryFile ?? '\x01';
+  const paramKeys = Object.keys(slotParams).sort();
+  const paramParts = paramKeys.map((k) => {
+    const v = slotParams[k];
+    return Array.isArray(v) ? `${k}=${v.join('\x02')}` : `${k}=${v}`;
+  });
+  return [slotKey, owner, entry, ...paramParts].join('\0');
+}

package/src/routing/types.ts

@@ -96,12 +96,6 @@ export interface SegmentNode<TFile = RouteFile> {
   middleware?: TFile;
   access?: TFile;
   route?: TFile;
-  /**
-   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
-   * Discovered by the scanner like middleware.ts and access.ts.
-   * See design/07-routing.md §"params.ts Convention File"
-   */
-  params?: TFile;
   error?: TFile;
   default?: TFile;
   /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */