@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.73

package/src/plugin-context.ts

@@ -0,0 +1,200 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import type { RouteTree } from './routing/types';
+import type { BuildManifest } from './server/build-manifest';
+import type { StartupTimer } from './utils/startup-timer';
+import { createStartupTimer } from './utils/startup-timer';
+import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+import type { HoldingServer } from './server/dev-holding-server.js';
+
+// Re-export for sub-plugin convenience — they import from plugin-context.ts
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+
+// ── Client JavaScript config ─────────────────────────────────────────────
+
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+  disabled: boolean;
+  enableHMRInDev: boolean;
+}
+
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
+  if (config.clientJavascript !== undefined) {
+    if (typeof config.clientJavascript === 'boolean') {
+      return {
+        disabled: !config.clientJavascript,
+        enableHMRInDev: !config.clientJavascript,
+      };
+    }
+    return {
+      disabled: config.clientJavascript.disabled,
+      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
+    };
+  }
+  return { disabled: false, enableHMRInDev: false };
+}
+
+// ── Plugin Context ────────────────────────────────────────────────────────
+
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export interface PluginContext {
+  config: TimberUserConfig;
+  /** Resolved client JavaScript configuration */
+  clientJavascript: ResolvedClientJavascript;
+  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
+  routeTree: RouteTree | null;
+  /** Absolute path to the app/ directory */
+  appDir: string;
+  /** Absolute path to the project root */
+  root: string;
+  /** Whether the dev server is running (set by timber-root-sync in configResolved) */
+  dev: boolean;
+  /** CSS build manifest (populated by adapter after client build, null in dev) */
+  buildManifest: BuildManifest | null;
+  /** Per-build deployment ID for version skew detection (null in dev) */
+  deploymentId: string | null;
+  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
+  timer: StartupTimer;
+  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+  holdingServer?: HoldingServer | null;
+}
+
+// ── App directory resolution ──────────────────────────────────────────────
+
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+export function resolveAppDir(root: string, configAppDir?: string): string {
+  if (configAppDir) {
+    const explicit = join(root, configAppDir);
+    if (!existsSync(explicit)) {
+      throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
+    }
+    return explicit;
+  }
+
+  const rootApp = join(root, 'app');
+  if (existsSync(rootApp)) return rootApp;
+
+  const srcApp = join(root, 'src', 'app');
+  if (existsSync(srcApp)) return srcApp;
+
+  throw new Error(
+    `[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. ` +
+      `You can set appDir in timber.config.ts to specify a custom location.`
+  );
+}
+
+// ── Plugin context factory ────────────────────────────────────────────────
+
+export function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
+  const projectRoot = root ?? process.cwd();
+  const resolvedConfig: TimberUserConfig = { ...config };
+  return {
+    config: resolvedConfig,
+    clientJavascript: resolveClientJavascript(resolvedConfig),
+    routeTree: null,
+    appDir: join(projectRoot, 'app'),
+    root: projectRoot,
+    dev: false,
+    buildManifest: null,
+    deploymentId: null,
+    timer: createStartupTimer(),
+    holdingServer: null,
+  };
+}
+
+// ── Config file loading ───────────────────────────────────────────────────
+
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ *
+ * Uses require() which works for ESM modules on Node 22.12+.
+ * This keeps timber() synchronous — no async config loading needed.
+ */
+export function loadTimberConfigFile(root: string): TimberUserConfig | null {
+  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  const req = createRequire(join(root, 'package.json'));
+
+  for (const name of configNames) {
+    const configPath = join(root, name);
+    if (existsSync(configPath)) {
+      const mod = req(configPath);
+      return (mod.default ?? mod) as TimberUserConfig;
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+ * and warn the user. The `output` key is excluded because it defaults to 'server'
+ * in createPluginContext and would always appear as an inline key.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export function warnConfigConflicts(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): string[] {
+  const conflicts: string[] = [];
+  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
+    if (key in inline && inline[key] !== undefined) {
+      conflicts.push(key);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.warn(
+      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
+        `vite.config.ts (inline) and timber.config.ts. ` +
+        `Move all config to timber.config.ts to avoid confusion. ` +
+        `The inline value from vite.config.ts will be used.`
+    );
+  }
+  return conflicts;
+}
+
+/**
+ * Merge file-based config into ctx.config. Inline config (already in ctx.config)
+ * takes precedence — file config only fills in missing fields.
+ */
+export function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void {
+  const inline = ctx.config;
+  warnConfigConflicts(inline, fileConfig);
+
+  ctx.config = {
+    ...fileConfig,
+    ...inline,
+    ...(fileConfig.limits && inline.limits
+      ? { limits: { ...fileConfig.limits, ...inline.limits } }
+      : {}),
+    ...(fileConfig.dev && inline.dev ? { dev: { ...fileConfig.dev, ...inline.dev } } : {}),
+    ...(fileConfig.mdx && inline.mdx ? { mdx: { ...fileConfig.mdx, ...inline.mdx } } : {}),
+  };
+}

package/src/plugins/adapter-build.ts

@@ -16,7 +16,7 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {

package/src/plugins/build-manifest.ts

@@ -18,7 +18,7 @@
 
 import { randomUUID } from 'node:crypto';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import type { BuildManifest } from '../server/build-manifest.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.

package/src/plugins/build-report.ts

@@ -15,7 +15,7 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import type { SegmentNode, RouteTree } from '../routing/types.js';
 import { formatSize } from '../utils/format.js';
 

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',

package/src/plugins/dev-browser-logs.ts

@@ -16,7 +16,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/plugins/dev-logs.ts

@@ -13,7 +13,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/plugins/dev-server.ts

@@ -15,7 +15,7 @@
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import { setViteServer } from '../server/dev-warnings.js';
 import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
 import { compressResponse } from '../server/compress.js';
@@ -96,6 +96,21 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // Pre-hook — registers middleware before Vite's internals
       server.middlewares.use(createTimberMiddleware(server, ctx.root));
 
+      // Wrap server.listen() to close the holding server immediately
+      // before Vite binds the port — no gap where nothing is listening.
+      // The holding server was started in rootSync's config() hook to
+      // serve a loading page during initialization.
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
+      if (ctx.holdingServer) {
+        const originalListen = server.listen.bind(server);
+        const holdingRef = ctx.holdingServer;
+        ctx.holdingServer = null;
+        server.listen = async (port?: number, isRestart?: boolean) => {
+          await holdingRef.close().catch(() => {});
+          return originalListen(port, isRestart);
+        };
+      }
+
       // Log startup timing summary. configureServer runs on all plugins
       // before the server listens, so this captures the full cold start.
       ctx.timer.end('dev-server-setup');

package/src/plugins/entries.ts

@@ -15,7 +15,7 @@ import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -49,7 +49,7 @@ const VIRTUAL_IDS = {
 const ENTRY_FILE_MAP: Record<string, string> = {
   [VIRTUAL_IDS.rscEntry]: resolve(SRC_DIR, 'server', 'rsc-entry', 'index.ts'),
   [VIRTUAL_IDS.ssrEntry]: resolve(SRC_DIR, 'server', 'ssr-entry.ts'),
-  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry.ts'),
+  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry', 'index.ts'),
 };
 
 /** The \0-prefixed resolved ID for virtual:timber-config */

package/src/plugins/fonts.ts

@@ -17,7 +17,7 @@
 import type { Plugin, ViteDevServer } from 'vite';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, normalize } from 'node:path';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import type { ExtractedFont, GoogleFontConfig } from '../fonts/types.js';
 import type { ManifestFontEntry } from '../server/build-manifest.js';
 import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from '../fonts/css.js';
@@ -470,11 +470,12 @@ export function timberFonts(ctx: PluginContext): Plugin {
                 googleFontFacesMap.set(font.id, faces);
               } catch (e) {
                 // In dev mode, fail gracefully — fonts fall back to system fonts.
+                // Don't cache the failure so transient errors (network blips,
+                // rate limits) are retried on the next request. See TIM-636.
                 const msg = e instanceof Error ? e.message : String(e);
                 console.warn(
-                  `[timber-fonts] Failed to resolve Google font "${font.family}": ${msg}`
+                  `[timber-fonts] Failed to resolve Google font "${font.family}": ${msg}. Will retry on next request.`
                 );
-                googleFontFacesMap.set(font.id, []);
               }
             }
           }

package/src/plugins/mdx.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const MDX_EXTENSIONS = ['mdx', 'md'];
 

package/src/plugins/routing.ts

@@ -19,7 +19,7 @@ import {
   formatStatusFileLintWarnings,
 } from '../routing/status-file-lint.js';
 import type { RouteTree, SegmentNode, RouteFile } from '../routing/types.js';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;

package/src/plugins/shims.ts

@@ -17,7 +17,7 @@
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Detect whether we're running from source (src/plugins/) or dist (dist/).
@@ -48,11 +48,9 @@ const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
  */
 const SUBPATH_SRC_MAP: Record<string, string> = {
   'cache': 'cache/index.ts',
-  'content': 'content/index.ts',
   'cookies': 'cookies/index.ts',
-  'segment-params': 'segment-params/index.ts',
   'search-params': 'search-params/index.ts',
-  'routing': 'routing/index.ts',
+
   'adapters/cloudflare': 'adapters/cloudflare.ts',
   'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
   'adapters/nitro': 'adapters/nitro.ts',
@@ -163,6 +161,50 @@ export function timberShims(_ctx: PluginContext): Plugin {
       // In the client (browser) environment, all imports resolve to dist/
       // via package.json exports (no remapping needed).
 
+      // ── #imports resolution for package-internal modules ─────────────
+      //
+      // #server-internal and #client-internal are Node package imports
+      // (package.json "imports" field). They are only resolvable from
+      // within this package — external consumers get module-not-found.
+      //
+      // In Vite, we intercept them here to resolve to src/ for dev/build
+      // correctness (same rationale as the @timber-js/app/* remap above).
+      if (cleanId === '#server-internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '#client-internal') {
+        // Always resolve to src/ — framework internals only,
+        // no 'use client' directives to preserve.
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
+      if (cleanId === '#routing') {
+        return resolve(PKG_ROOT, 'src', 'routing', 'index.ts');
+      }
+
+      // Legacy aliases — vitest and monorepo configs may still reference
+      // the old @timber-js/app/server/internal and @timber-js/app/client/internal
+      // specifiers via resolve.alias. When those aliases resolve to the
+      // absolute src/ path, they bypass this plugin entirely. But if the
+      // specifier reaches us unresolved (e.g., in a Vite build without
+      // aliases), handle it the same way as the #imports above.
+      if (cleanId === '@timber-js/app/server/internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '@timber-js/app/client/internal') {
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
       if (cleanId === '@timber-js/app/server') {
         const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
         if (envName === 'client') {
@@ -245,6 +287,12 @@ const msg = "[timber] @timber-js/app/server was imported from client code. " +
 function stub() { throw new Error(msg); }
 export const headers = stub;
 export const cookies = stub;
+export const getHeaders = stub;
+export const getHeader = stub;
+export const getCookies = stub;
+export const getCookie = stub;
+export const getSearchParams = stub;
+export const getSegmentParams = stub;
 export const searchParams = stub;
 export const deny = stub;
 export const notFound = stub;
@@ -252,7 +300,7 @@ export const redirect = stub;
 export const permanentRedirect = stub;
 export const redirectExternal = stub;
 export const waitUntil = stub;
-export const RenderError = stub;
+export const DenyOptions = {};
 export const RedirectType = {};
 export const DenySignal = stub;
 export const RedirectSignal = stub;

package/src/plugins/static-build.ts

@@ -2,7 +2,7 @@
  * timber-static-build — Vite sub-plugin for static output mode.
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
+ * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
  * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
  * 3. Coordinates build-time rendering of all pages
  *
@@ -10,7 +10,7 @@
  */
 
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../index.js';
+import type { PluginContext } from '../plugin-context.js';
 import { detectFileDirective } from '../utils/directive-parser.js';
 
 // ---------------------------------------------------------------------------
@@ -29,7 +29,7 @@ export interface StaticOptions {
 }
 
 // ---------------------------------------------------------------------------
-// Detection: dynamic APIs (cookies, headers)
+// Detection: dynamic APIs (getCookies, getHeaders, and legacy cookies/headers)
 // ---------------------------------------------------------------------------
 
 /**
@@ -39,12 +39,14 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
+  { pattern: /\bgetCookies\s*\(/, name: 'getCookies()' },
+  { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },
 ];
 
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
@@ -134,7 +136,7 @@ export function detectDirectives(
  * Run all static mode validations on a source file.
  *
  * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
+ * - Dynamic API detection (getCookies, getHeaders) — always in static mode
  * - Directive detection ('use client', 'use server') — only when client JS is disabled
  */
 export function validateStaticMode(
@@ -170,7 +172,7 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
      * Validate source files during transform.
      *
      * In static mode, we check every app/ file for:
-     * - Dynamic API usage (cookies(), headers()) → build error
+     * - Dynamic API usage (getCookies(), getHeaders()) → build error
      * - When client JS disabled: 'use client' / 'use server' directives → build error
      */
     transform(code: string, id: string) {

package/src/search-params/define.ts

@@ -15,33 +15,33 @@ import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
 import type { StandardSchemaV1 } from '../schema-bridge.js';
 import type { Codec } from '../codec.js';
 
-// Server-only reference for .load() — avoids pulling server ALS into client bundles.
-// In client environments, .load() throws before reaching this code path.
+// Server-only reference for .get() — avoids pulling server ALS into client bundles.
+// In client environments, .get() throws before reaching this code path.
 //
-// IMPORTANT: This is set eagerly via _setRawSearchParamsFn() at server startup
+// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
 // (called from request-context.ts module initialization). It must NOT use
 // dynamic `await import()` at call time because the async microtask from the
 // dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
-// breaking rawSearchParams() in parallel slot pages. See TIM-523.
-let _rawSearchParams: (() => Promise<URLSearchParams>) | undefined;
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+let _getSearchParamsFn: (() => Promise<URLSearchParams>) | undefined;
 
 /**
- * Register the rawSearchParams function. Called once at module load time
+ * Register the getSearchParams function. Called once at module load time
  * from request-context.ts to avoid dynamic import at call time.
  * @internal
  */
-export function _setRawSearchParamsFn(fn: () => Promise<URLSearchParams>): void {
-  _rawSearchParams = fn;
+export function _setGetSearchParamsFn(fn: () => Promise<URLSearchParams>): void {
+  _getSearchParamsFn = fn;
 }
 
-function getRawSearchParams(): Promise<URLSearchParams> {
-  if (!_rawSearchParams) {
+function getSearchParamsFromAls(): Promise<URLSearchParams> {
+  if (!_getSearchParamsFn) {
     throw new Error(
-      '[timber] searchParams.load() is only available on the server. ' +
+      '[timber] searchParams.get() is only available on the server. ' +
         'Use searchParams.useQueryStates() on the client.'
     );
   }
-  return _rawSearchParams();
+  return _getSearchParamsFn();
 }
 
 // ---------------------------------------------------------------------------
@@ -109,9 +109,9 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;
 
   /**
-   * Load typed search params from the current request context (ALS-backed).
+   * Get typed search params from the current request context (ALS-backed).
    *
-   * Server-only — reads rawSearchParams() from ALS and parses through codecs.
+   * Server-only — reads getSearchParams() from ALS and parses through codecs.
    * Throws on client. Eliminates the naming conflict between the definition
    * export and the server helper.
    *
@@ -119,11 +119,11 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
    * // app/products/page.tsx
    * import { searchParams } from './params'
    * export default async function Page() {
-   *   const { page, category } = await searchParams.load()
+   *   const { page, category } = await searchParams.get()
    * }
    * ```
    */
-  load(): Promise<T>;
+  get(): Promise<T>;
 
   /** Client hook — reads current URL params and returns typed values + setter. */
   useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
@@ -451,23 +451,23 @@ function buildDefinition<T extends Record<string, unknown>>(
     ];
   }
 
-  // ---- load ----
-  // ALS-backed: reads rawSearchParams() from the current request context
+  // ---- get ----
+  // ALS-backed: reads getSearchParams() from the current request context
   // and parses through codecs. Server-only — throws on client.
-  async function load(): Promise<T> {
+  async function get(): Promise<T> {
     if (typeof window !== 'undefined') {
       throw new Error(
-        '[timber] searchParams.load() is server-only. ' +
+        '[timber] searchParams.get() is server-only. ' +
           'Use searchParams.useQueryStates() on the client.'
       );
     }
-    const raw = await getRawSearchParams();
+    const raw = await getSearchParamsFromAls();
     return parseSync(raw);
   }
 
   const definition: SearchParamsDefinition<T> = {
     parse,
-    load,
+    get,
     useQueryStates,
     extend,
     pick,

package/src/search-params/index.ts

@@ -1,7 +1,7 @@
 // @timber-js/app/search-params — Typed search params
 
-// Shared codec protocol
-export type { Codec } from '../codec.js';
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
 
 // Core types and factory
 export type {
@@ -25,4 +25,4 @@ export { defineSearchParams } from './define.js';
 export { withDefault, withUrlKey } from './wrappers.js';
 
 // Runtime registry (route-scoped useQueryStates)
-export { registerSearchParams, getSearchParams } from './registry.js';
+export { registerSearchParams, getSearchParamsDefinition } from './registry.js';

package/src/search-params/registry.ts

@@ -26,6 +26,6 @@ export function registerSearchParams(route: string, definition: SearchParamsDefi
  * Returns undefined if the route hasn't been loaded yet.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {
+export function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined {
   return registry.get(route);
 }