@timber-js/app 0.2.0-alpha.122 → 0.2.0-alpha.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.122",
+  "version": "0.2.0-alpha.123",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -114,11 +114,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -162,5 +157,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-entry/action-dispatch.ts

@@ -15,7 +15,7 @@
  */
 
 import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.js';
-import { getRouter } from '#client-internal';
+import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
 import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
@@ -96,15 +96,14 @@ export function setupServerActions(): void {
       // Piggybacked response: wrapper object { _action, _tree }
       // Apply the revalidated tree directly — no separate router.refresh() needed.
       const wrapper = decoded as { _action: unknown; _tree: unknown };
-      try {
-        const router = getRouter();
-        const headElements = headElementsJson ? JSON.parse(headElementsJson) : null;
-        router.applyRevalidation(wrapper._tree, headElements);
-      } catch (e) {
-        console.debug(
-          '[timber] action revalidation: router not ready',
-          e instanceof Error ? e.message : e
-        );
+      const router = getRouterOrNull();
+      if (router) {
+        try {
+          const headElements = headElementsJson ? JSON.parse(headElementsJson) : null;
+          router.applyRevalidation(wrapper._tree, headElements);
+        } catch (e) {
+          console.error('[timber] applyRevalidation failed after server action', e);
+        }
       }
       return wrapper._action;
     }

package/src/client/browser-entry/post-hydration.ts

@@ -58,12 +58,18 @@ export function setupPostHydration({
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
-  // NOTE: We do NOT cache segment elements from the initial RSC payload here.
-  // The decoded element from createFromReadableStream is a thenable/lazy
-  // element that React resolves during render — the segment walker can't
-  // traverse it. The element cache is populated lazily after the first SPA
-  // navigation (via mergeAndCachePayload in renderViaTransition), when
-  // the decoded payload is a fully resolved React element tree.
+  // Cache segment elements from the initial RSC payload after hydration.
+  // The element from createFromReadableStream is a Flight thenable that
+  // React resolves during hydration. Once resolved (status='fulfilled'),
+  // its .value contains the React element tree we can walk.
+  // Use requestAnimationFrame to run after hydration commits.
+  if (initialElement != null) {
+    requestAnimationFrame(() => {
+      const el = initialElement as { status?: string; value?: unknown };
+      const resolved = el.status === 'fulfilled' && el.value != null ? el.value : initialElement;
+      router.cacheElementTree(resolved);
+    });
+  }
 
   // If the hydration path was skipped (no RSC payload), populate the
   // fallback params from server embed here.

package/src/client/index.ts

@@ -66,6 +66,7 @@ export type { LinkStatus } from './use-link-status';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
+export { replaceUrl } from './shallow-url';
 // useSearchParams removed from public exports — lives in next/navigation shim only.
 export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
 
@@ -82,8 +83,3 @@ export { useSegmentParams } from './use-segment-params';
 // Cookies — useCookie lives on defineCookie().useCookie().
 // Types still exported for advanced use.
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
-
-// Register the client useSegmentParams hook with defineSegmentParams.
-import { useSegmentParams as _useSegmentParams } from './use-segment-params.js';
-import { _registerUseSegmentParams } from '../segment-params/define.js';
-_registerUseSegmentParams(_useSegmentParams);

package/src/client/link.tsx

@@ -384,20 +384,28 @@ export function resolveHref(
         | SearchParamsDefinition<Record<string, unknown>>
         | undefined;
       values = searchParams;
-      if (!definition) {
-        throw new Error(
-          `<Link> received a flat searchParams object for href "${href}", but no ` +
-            `SearchParamsDefinition is registered for that route. ` +
-            `Either the route does not export \`searchParams\` from its \`params.ts\`/\`page.tsx\`, ` +
-            `or the search-params registry module was not loaded. ` +
-            `For external or computed hrefs, pass the legacy \`{ definition, values }\` shape instead.`
-        );
-      }
     }
 
-    const qs = definition.serialize(values);
-    if (qs) {
-      resolvedPath = `${resolvedPath}?${qs}`;
+    if (definition) {
+      const qs = definition.serialize(values);
+      if (qs) {
+        resolvedPath = `${resolvedPath}?${qs}`;
+      }
+    } else {
+      // No registered definition — serialize flat object as plain query params.
+      const usp = new URLSearchParams();
+      for (const [key, val] of Object.entries(values)) {
+        if (val === undefined || val === null) continue;
+        if (Array.isArray(val)) {
+          for (const item of val) usp.append(key, String(item));
+        } else {
+          usp.set(key, String(val));
+        }
+      }
+      const qs = usp.toString();
+      if (qs) {
+        resolvedPath = `${resolvedPath}?${qs}`;
+      }
     }
   }
 
@@ -591,6 +599,11 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
           return;
         }
 
+        // Hash-only hrefs — let the browser handle scroll-to-anchor natively.
+        // The Navigation API path already skips these via event.hashChange;
+        // this covers the fallback (Safari/Firefox) where we drive navigation manually.
+        if (resolvedHref.startsWith('#')) return;
+
         // History API fallback — prevent default and navigate via router
         event.preventDefault();
 

package/src/client/router.ts

@@ -215,6 +215,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentElementCache = new SegmentElementCache();
 
   let routerPhase: RouterPhase = { phase: 'idle' };
+  let navigationId = 0;
   const pendingListeners = new Set<(pending: boolean) => void>();
 
   // AbortController for the current in-flight navigation.
@@ -287,24 +288,46 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /**
    * Merge a partial RSC payload with cached segment elements if segments
-   * were skipped, then cache segments from the (merged) payload.
-   * Returns the merged payload ready for rendering.
+   * were skipped. Returns the merged payload ready for rendering.
+   *
+   * Segment element caching is deferred to after paint by the caller
+   * so it doesn't block the render path.
    */
-  function mergeAndCachePayload(
+  async function mergePayload(
     payload: unknown,
     skippedSegments: string[] | null | undefined
-  ): unknown {
-    let merged = payload;
-
-    // If segments were skipped, merge the partial payload with cached segments
+  ): Promise<unknown> {
     if (skippedSegments && skippedSegments.length > 0) {
-      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+      // Segment merging needs a resolved React element tree for cloneElement.
+      // Await the payload only when merging is actually needed.
+      const resolved =
+        payload != null && typeof payload === 'object' && 'then' in payload
+          ? await (payload as PromiseLike<unknown>)
+          : payload;
+      return mergeSegmentTree(resolved, skippedSegments, segmentElementCache);
     }
+    // No merging needed — return the payload as-is (may be an unresolved
+    // Flight thenable). React handles progressive rendering via Suspense.
+    return payload;
+  }
 
-    // Cache segment elements from the (merged) payload for future merges
-    cacheSegmentElements(merged, segmentElementCache);
-
-    return merged;
+  /**
+   * Schedule segment element caching after paint. Resolves thenable
+   * payloads first since tree walking requires resolved React elements.
+   * Guards against stale writes: if a newer navigation started before
+   * this callback fires, the cache write is skipped.
+   */
+  function deferSegmentCaching(payload: unknown): void {
+    const capturedNavId = navigationId;
+    afterPaint(async () => {
+      if (capturedNavId !== navigationId) return;
+      const resolved =
+        payload != null && typeof payload === 'object' && 'then' in payload
+          ? await (payload as PromiseLike<unknown>)
+          : payload;
+      if (capturedNavId !== navigationId) return;
+      cacheSegmentElements(resolved, segmentElementCache);
+    });
   }
 
   /**
@@ -335,17 +358,27 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * FetchResult plus the NavigationState (so it can be passed explicitly
    * to wrapPayload/renderRoot without temporal coupling).
    */
+  interface TransitionResult {
+    headElements: HeadElement[] | null;
+    decodePromise: Promise<void> | null;
+  }
+
   async function renderViaTransition(
     url: string,
     perform: () => Promise<FetchResult & { navState: NavigationState }>
-  ): Promise<HeadElement[] | null> {
+  ): Promise<TransitionResult> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
+      let decodePromise: Promise<void> | null = null;
       await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
-        // Merge partial payload with cached segments before wrapping
-        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        decodePromise = result.decodePromise;
+        // Merge partial payload with cached segments before wrapping.
+        // When no segments were skipped, mergePayload returns the payload
+        // as-is (possibly still an unresolved Flight thenable — React
+        // handles progressive rendering via Suspense).
+        const merged = await mergePayload(result.payload, result.skippedSegments);
         // Store the MERGED payload in history — not the partial pre-merge tree.
         // This ensures handlePopState replays the complete tree on back/forward.
         historyStack.push(url, {
@@ -353,24 +386,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: result.headElements,
           params: result.params,
         });
+        // Defer segment element caching to after paint — it only benefits
+        // future navigations and doesn't need to block the current render.
+        deferSegmentCaching(merged);
         // Pass navState explicitly — wrapPayload wraps element in
         // NavigationProvider with this state, no getNavigationState() needed.
         return wrapPayload(merged, result.navState);
       });
-      return headElements;
+      return { headElements, decodePromise };
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
     // Merge partial payload with cached segments before rendering
-    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    const merged = await mergePayload(result.payload, result.skippedSegments);
     // Store merged payload in history
     historyStack.push(url, {
       payload: merged,
       headElements: result.headElements,
       params: result.params,
     });
+    deferSegmentCaching(merged);
     renderPayload(merged, result.navState);
-    return result.headElements;
+    return { headElements: result.headElements, decodePromise: result.decodePromise };
   }
 
   /** Apply head elements (title, meta tags) to the DOM if available. */
@@ -414,6 +451,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     let result: FetchResult | undefined = prefetched
       ? {
           payload: prefetched.payload,
+          decodePromise: null,
           headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
@@ -466,6 +504,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const externalSignal = options._signal as AbortSignal | undefined;
     const skipHistory = options._skipHistory === true;
 
+    navigationId++;
+
     // Create an abort controller for this navigation. Links to the external
     // signal (Navigation API's event.signal) when provided.
     const navAbort = createNavAbort(externalSignal);
@@ -499,7 +539,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, url);
 
     try {
-      const headElements = await renderViaTransition(url, () =>
+      const { headElements, decodePromise } = await renderViaTransition(url, () =>
         performNavigationFetch(url, {
           replace,
           signal: navAbort.signal,
@@ -507,6 +547,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         })
       );
 
+      // Await async RSC decode errors (truncated streams, Flight parse failures)
+      // so they surface through this try/catch rather than becoming unhandled.
+      if (decodePromise) await decodePromise;
+
       // Update document.title and <meta> tags with the new page's metadata
       applyHead(headElements);
 
@@ -575,12 +619,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
+    navigationId++;
     const navAbort = createNavAbort();
 
     setPending(true, currentUrl);
 
     try {
-      const headElements = await renderViaTransition(currentUrl, async () => {
+      const { headElements, decodePromise } = await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
           currentUrl,
@@ -595,6 +640,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         return { ...result, navState };
       });
 
+      if (decodePromise) await decodePromise;
       applyHead(headElements);
     } catch (error) {
       // Stale transition (superseded by a newer navigation) or aborted
@@ -615,6 +661,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     scrollY: number = 0,
     externalSignal?: AbortSignal
   ): Promise<void> {
+    navigationId++;
     // Scroll position is read from history.state by the caller (browser-entry.ts)
     // and passed in. This is more reliable than tracking scroll per-URL in memory
     // because the browser maintains per-entry state even with duplicate URLs.
@@ -634,7 +681,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const navAbort = createNavAbort(externalSignal);
       setPending(true, url);
       try {
-        const headElements = await renderViaTransition(url, async () => {
+        const { headElements, decodePromise } = await renderViaTransition(url, async () => {
           const stateTree = segmentCache.serializeStateTree(
             segmentElementCache.getMergeablePaths()
           );
@@ -645,6 +692,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           return { ...result, navState };
         });
 
+        if (decodePromise) await decodePromise;
         applyHead(headElements);
         restoreScrollAfterPaint(scrollY);
       } catch (error) {
@@ -697,18 +745,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload and applies
       // head elements — same as refresh() but without a server fetch.
-      // Cache segment elements for future partial merges.
+      // Revalidation payloads are already resolved (no Flight thenable),
+      // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
-      const merged = mergeAndCachePayload(element, null);
       historyStack.push(currentUrl, {
-        payload: merged,
+        payload: element,
         headElements,
       });
+      deferSegmentCaching(element);
       // Revalidation doesn't change params/pathname — preserve current state.
       // DO NOT call updateNavigationState(null, ...) here: that normalizes
       // params to {}, clearing dynamic route params on every action response.
       const navState = getNavigationState();
-      renderPayload(merged, navState);
+      renderPayload(element, navState);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),

package/src/client/rsc-fetch.ts

@@ -20,6 +20,14 @@ import type { RouterDeps } from './router';
 /** Result of fetching an RSC payload — includes head elements and segment metadata. */
 export interface FetchResult {
   payload: unknown;
+  /**
+   * Promise that settles when the RSC decode completes or fails.
+   * The payload thenable is NOT awaited before returning (for streaming),
+   * so callers must monitor this to catch async decode errors
+   * (truncated streams, Flight parse failures) that would otherwise
+   * become unhandled rejections.
+   */
+  decodePromise: Promise<void> | null;
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
@@ -313,11 +321,17 @@ export async function fetchRscPayload(
     });
     // Await headers so headElements/segmentInfo/params are populated.
     await wrappedPromise;
-    // Await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree once the Flight stream
-    // has enough data to produce the shell.
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params, skippedSegments };
+    // Start decoding but do NOT await — return the in-progress thenable.
+    // React can render a Flight thenable directly: it suspends on unresolved
+    // parts and progressively renders as chunks arrive, spreading work across
+    // frames instead of blocking the main thread in one burst.
+    const payload = deps.decodeRsc(wrappedPromise);
+    // Track decode completion so callers can catch async errors (truncated
+    // streams, Flight parse failures) that fire after fetchRscPayload returns.
+    const decodePromise = Promise.resolve(payload).then(() => undefined);
+    // Prevent unhandled rejection — the router monitors decodePromise separately.
+    decodePromise.catch(() => {});
+    return { payload, decodePromise, headElements, segmentInfo, params, skippedSegments };
   }
   // Test/fallback path: return raw text
   const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
@@ -330,6 +344,7 @@ export async function fetchRscPayload(
   }
   return {
     payload: await response.text(),
+    decodePromise: null,
     headElements: extractHeadElements(response),
     segmentInfo: extractSegmentInfo(response),
     params: extractParams(response),

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.js';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}

package/src/segment-params/define.ts

@@ -20,6 +20,7 @@ import {
   isStandardSchema,
   isCodec,
 } from '../schema-bridge.js';
+import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
 
 // ---------------------------------------------------------------------------
 // Server-only ALS reference for .get()
@@ -28,28 +29,6 @@ import {
 // Same pattern as search-params: eagerly registered at server startup
 // to avoid dynamic imports that lose ALS context. See TIM-523.
 let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
-let _useSegmentParamsHook: (() => Record<string, string | string[]>) | undefined;
-
-/**
- * Register the client useSegmentParams hook.
- * Called by client entry at module load time to avoid require() at call time.
- * @internal
- */
-export function _registerUseSegmentParams(hook: () => Record<string, string | string[]>): void {
-  _useSegmentParamsHook = hook;
-}
-
-// Self-register on the client when the barrel hasn't been imported yet.
-// Handles the edge case where a client component imports only from params.ts
-// without importing anything from @timber-js/app/client (which runs the
-// registration). The dynamic import resolves before React hydration in Vite.
-if (typeof window !== 'undefined' && !_useSegmentParamsHook) {
-  import('../client/use-segment-params.js').then((mod) => {
-    if (!_useSegmentParamsHook) {
-      _useSegmentParamsHook = mod.useSegmentParams;
-    }
-  });
-}
 
 /**
  * Register the getSegmentParams function. Called once at module load time
@@ -311,13 +290,7 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
   // Client hook that reads typed params from the navigation context.
   // Delegates to the existing useSegmentParams hook from use-segment-params.ts.
   function useSegmentParams(): T {
-    if (!_useSegmentParamsHook) {
-      throw new Error(
-        '[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. ' +
-          'This hook can only be used in client components.'
-      );
-    }
-    const raw = _useSegmentParamsHook();
+    const raw = clientUseSegmentParams();
     // Params are already coerced by the server pipeline before being sent
     // to the client — return as-is. Re-parsing would break non-idempotent
     // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.

package/dist/_chunks/define-CPVQaWbx.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"define-CPVQaWbx.js","names":[],"sources":["../../src/segment-params/define.ts"],"sourcesContent":["/**\n * defineSegmentParams — factory for typed route param coercion.\n *\n * Creates a ParamsDefinition that coerces raw string params from the\n * URL into typed values. Used by exporting from params.ts (segment-level)\n * convention file.\n *\n * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,\n * same pattern as defineSearchParams. Runtime constraints are stricter:\n * - serialize must return string (not null — path segments can't be omitted)\n * - parse throwing → 404 (invalid param value)\n *\n * Design doc: design/07a-route-params-triage.md\n */\n\nimport type { Codec } from '../codec.js';\nimport {\n  type StandardSchemaV1,\n  validateSync,\n  isStandardSchema,\n  isCodec,\n} from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Server-only ALS reference for .get()\n// ---------------------------------------------------------------------------\n\n// Same pattern as search-params: eagerly registered at server startup\n// to avoid dynamic imports that lose ALS context. See TIM-523.\nlet _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;\nlet _useSegmentParamsHook: (() => Record<string, string | string[]>) | undefined;\n\n/**\n * Register the client useSegmentParams hook.\n * Called by client entry at module load time to avoid require() at call time.\n * @internal\n */\nexport function _registerUseSegmentParams(hook: () => Record<string, string | string[]>): void {\n  _useSegmentParamsHook = hook;\n}\n\n// Self-register on the client when the barrel hasn't been imported yet.\n// Handles the edge case where a client component imports only from params.ts\n// without importing anything from @timber-js/app/client (which runs the\n// registration). The dynamic import resolves before React hydration in Vite.\nif (typeof window !== 'undefined' && !_useSegmentParamsHook) {\n  import('../client/use-segment-params.js').then((mod) => {\n    if (!_useSegmentParamsHook) {\n      _useSegmentParamsHook = mod.useSegmentParams;\n    }\n  });\n}\n\n/**\n * Register the getSegmentParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {\n  _getSegmentParamsFn = fn;\n}\n\nfunction getSegmentParamsFromAls(): Record<string, string | string[]> {\n  if (!_getSegmentParamsFn) {\n    throw new Error(\n      '[timber] segmentParams.get() is only available on the server. ' +\n        'Use segmentParams.useSegmentParams() on the client.'\n    );\n  }\n  return _getSegmentParamsFn();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from a Codec or StandardSchemaV1. */\nexport type InferParamField<V> =\n  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineParams: a Codec or a Standard Schema. */\nexport type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;\n\nexport type { StandardSchemaV1 };\n\n/**\n * A typed route params definition.\n *\n * Returned by defineParams(). Provides parse (string → typed) and\n * serialize (typed → string) for each declared param.\n */\nexport interface ParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw string params into typed values. Throws on invalid values. */\n  parse(raw: Record<string, string | string[]>): T;\n\n  /** Serialize typed values back to strings for URL construction. */\n  serialize(values: T): Record<string, string>;\n\n  /**\n   * Get typed segment params from the current request context (ALS).\n   *\n   * Server-only, sync.\n   *\n   * ```ts\n   * // app/products/[id]/params.ts\n   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })\n   *\n   * // app/products/[id]/page.tsx\n   * import { segmentParams } from './params'\n   * export default function Page() {\n   *   const { id } = segmentParams.get() // id: number\n   * }\n   * ```\n   */\n  get(): T;\n\n  /**\n   * Client hook for accessing typed segment params reactively.\n   *\n   * ```tsx\n   * 'use client'\n   * import { segmentParams } from './params'\n   * export function ProductHeader() {\n   *   const { id } = segmentParams.useSegmentParams()\n   * }\n   * ```\n   */\n  useSegmentParams(): T;\n\n  /** Read-only codec map. */\n  codecs: { [K in keyof T]: Codec<T[K]> };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a Standard Schema into a Codec for route params.\n *\n * Unlike fromSchema for search params:\n * - Parse throws on failure (no fallback to default)\n * - Serialize returns string (not null)\n */\nfunction fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Route params are always strings (single segment) or string[] (catch-all)\n      const input = Array.isArray(value) ? value : value;\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // For route params, parse failure means the param is invalid → throw\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      // Catch-all segments produce arrays — join with '/' for path reconstruction\n      if (Array.isArray(value)) {\n        return value.join('/');\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Resolve a field value to a Codec. Auto-detects Standard Schema objects.\n */\nfunction resolveField(fieldName: string, value: ParamField): Codec<unknown> {\n  if (isCodec(value)) {\n    return value;\n  }\n\n  if (isStandardSchema(value)) {\n    return fromParamSchema(fieldName, value);\n  }\n\n  throw new Error(\n    `[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that no codec's serialize returns null.\n * Route params are structural — they must produce a valid path segment.\n */\nfunction validateSerialize(codecMap: Record<string, Codec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    // Test serialize with a sample parsed value to check for null\n    // We can't exhaustively test, but we can check that serialize(parse(\"test\"))\n    // doesn't return null for a basic input.\n    try {\n      const testValue = codec.parse('test');\n      const serialized = codec.serialize(testValue);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\\n` +\n            `  Route params are path segments — they cannot be omitted.\\n` +\n            `  Ensure serialize() always returns a string.`\n        );\n      }\n    } catch (e) {\n      // parse('test') may throw for strict codecs (e.g., number-only).\n      // That's fine — it means the codec validates. We only care about\n      // serialize returning null, which we can't test without a valid value.\n      if (e instanceof Error && e.message.includes('returned null')) {\n        throw e;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.\n *\n * ```ts\n * // app/products/[id]/layout.tsx\n * import { defineSegmentParams } from '@timber-js/app/segment-params'\n * import { z } from 'zod/v4'\n *\n * export const segmentParams = defineSegmentParams({\n *   id: z.coerce.number().int().positive(),\n * })\n * ```\n */\nexport function defineSegmentParams<C extends Record<string, ParamField>>(\n  codecs: C\n): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {\n  type T = { [K in keyof C]: InferParamField<C[K]> };\n\n  const resolvedCodecs: Record<string, Codec<unknown>> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    resolvedCodecs[key] = resolveField(key, value as ParamField);\n  }\n\n  // Validate that serialize doesn't return null\n  validateSerialize(resolvedCodecs);\n\n  // ---- parse ----\n  function parse(raw: Record<string, string | string[]>): T {\n    const result: Record<string, unknown> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const rawValue = raw[key];\n      // Skip params not present in the URL at this route depth.\n      // This supports TIM-834 inheritance: a parent params.ts can declare\n      // codecs for descendant segments. At shallower depths those params\n      // don't exist yet — skip them instead of passing undefined to the codec.\n      if (rawValue === undefined) continue;\n      result[key] = codec.parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: T): Record<string, string> {\n    const result: Record<string, string> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const serialized = codec.serialize(values[key as keyof T] as unknown);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] params.serialize: field '${key}' serialized to null. ` +\n            `Route params must produce a valid path segment.`\n        );\n      }\n      result[key] = serialized;\n    }\n\n    return result;\n  }\n\n  // ---- get ----\n  // ALS-backed: reads segment params from the current request context.\n  // Server-only, sync.\n  //\n  // The pipeline already coerces params via coerceSegmentParams() which\n  // calls parse() and stores typed values in ALS via setSegmentParams().\n  // We return those directly instead of re-parsing, because codecs may\n  // not be idempotent (e.g., a codec that only accepts raw strings would\n  // throw if given an already-parsed value). See TIM-574.\n  function get(): T {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] segmentParams.get() is server-only. ' +\n          'Use segmentParams.useSegmentParams() on the client.'\n      );\n    }\n    const params = getSegmentParamsFromAls();\n    // params are already coerced by the pipeline — return as-is.\n    return params as unknown as T;\n  }\n\n  // ---- useSegmentParams ----\n  // Client hook that reads typed params from the navigation context.\n  // Delegates to the existing useSegmentParams hook from use-segment-params.ts.\n  function useSegmentParams(): T {\n    if (!_useSegmentParamsHook) {\n      throw new Error(\n        '[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. ' +\n          'This hook can only be used in client components.'\n      );\n    }\n    const raw = _useSegmentParamsHook();\n    // Params are already coerced by the server pipeline before being sent\n    // to the client — return as-is. Re-parsing would break non-idempotent\n    // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.\n    return raw as unknown as T;\n  }\n\n  const definition: ParamsDefinition<T> = {\n    parse,\n    serialize,\n    get,\n    useSegmentParams,\n    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },\n  };\n\n  return definition;\n}\n"],"mappings":";;AA6BA,IAAI;AACJ,IAAI;;;;;;AAOJ,SAAgB,0BAA0B,MAAqD;AAC7F,yBAAwB;;AAO1B,IAAI,OAAO,WAAW,eAAe,CAAC,sBACpC,QAAO,oCAAA,MAAA,MAAA,EAAA,EAAA,CAAmC,MAAM,QAAQ;AACtD,KAAI,CAAC,sBACH,yBAAwB,IAAI;EAE9B;;;;;;AAQJ,SAAgB,uBAAuB,IAAmD;AACxF,uBAAsB;;AAGxB,SAAS,0BAA6D;AACpE,KAAI,CAAC,oBACH,OAAM,IAAI,MACR,oHAED;AAEH,QAAO,qBAAqB;;;;;;;;;AA2E9B,SAAS,gBAAmB,WAAmB,QAAuC;AACpF,QAAO;EACL,MAAM,OAAyC;GAI7C,MAAM,SAAS,aAAa,QAFd,MAAM,QAAQ,MAAM,GAAG,QAAQ,MAEH;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;AAC/D,SAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,WAAW;;EAG/E,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAGT,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,KAAK,IAAI;AAExB,UAAO,OAAO,MAAM;;EAEvB;;;;;AAMH,SAAS,aAAa,WAAmB,OAAmC;AAC1E,KAAI,QAAQ,MAAM,CAChB,QAAO;AAGT,KAAI,iBAAiB,MAAM,CACzB,QAAO,gBAAgB,WAAW,MAAM;AAG1C,OAAM,IAAI,MACR,wCAAwC,UAAU,uJAGnD;;;;;;AAOH,SAAS,kBAAkB,UAAgD;AACzE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAIjD,KAAI;EACF,MAAM,YAAY,MAAM,MAAM,OAAO;AAErC,MADmB,MAAM,UAAU,UAAU,KAC1B,KACjB,OAAM,IAAI,MACR,wCAAwC,IAAI,+IAG7C;UAEI,GAAG;AAIV,MAAI,aAAa,SAAS,EAAE,QAAQ,SAAS,gBAAgB,CAC3D,OAAM;;;;;;;;;;;;;;;;AAuBd,SAAgB,oBACd,QAC6D;CAG7D,MAAM,iBAAiD,EAAE;AAEzD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,gBAAe,OAAO,aAAa,KAAK,MAAoB;AAI9D,mBAAkB,eAAe;CAGjC,SAAS,MAAM,KAA2C;EACxD,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,WAAW,IAAI;AAKrB,OAAI,aAAa,KAAA,EAAW;AAC5B,UAAO,OAAO,MAAM,MAAM,SAAS;;AAGrC,SAAO;;CAIT,SAAS,UAAU,QAAmC;EACpD,MAAM,SAAiC,EAAE;AAEzC,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,aAAa,MAAM,UAAU,OAAO,KAA2B;AACrE,OAAI,eAAe,KACjB,OAAM,IAAI,MACR,qCAAqC,IAAI,uEAE1C;AAEH,UAAO,OAAO;;AAGhB,SAAO;;CAYT,SAAS,MAAS;AAChB,MAAI,OAAO,WAAW,YACpB,OAAM,IAAI,MACR,mGAED;AAIH,SAFe,yBAAyB;;CAQ1C,SAAS,mBAAsB;AAC7B,MAAI,CAAC,sBACH,OAAM,IAAI,MACR,0IAED;AAMH,SAJY,uBAAuB;;AAerC,QARwC;EACtC;EACA;EACA;EACA;EACA,QAAQ;EACT"}