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

package/src/client/index.ts

@@ -75,11 +75,22 @@ export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selec
 export { useActionState, useFormAction } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
-// Params — raw hook for untyped access. For typed params, use defineSegmentParams().useSegmentParams().
+// Params. Called with no argument this returns the untyped accumulated params;
+// pass the route's SEGMENT_PATH (from its generated `./$segment` module) to get
+// the exact types `app/schema.ts` declares — `useSegmentParams(SEGMENT_PATH)`.
 export { useSegmentParams } from './use-segment-params';
 
-// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
-// and is available via direct import for advanced cases.
+// Query states. `definition.useQueryStates()` is the usual form; this standalone
+// export is the inline codec-map form, for shared param bundles reused across
+// routes (design/23-search-params.md §"Client Access").
+//
+// Until TIM-1341 this export did not exist, yet four doc sites told users to
+// import it from here. It type-checked only because the generated `.d.ts`
+// augmented this module with a `useQueryStates` overload — so TypeScript
+// believed in a binding that was never emitted, and the documented import
+// failed at build time. Deleting that overload removed the lie; exporting the
+// hook makes the docs true.
+export { useQueryStates } from './use-query-states';
 
 // Cookies — useCookie lives on defineCookie().useCookie().
 // Types still exported for advanced use.

package/src/client/internal.ts

@@ -19,7 +19,7 @@ export type {
   RouterPhase,
   RscDecoder,
   RootRenderer,
-} from './router.js';
+} from './router-types.js';
 export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.js';
 
 // ── SSR bridge ───────────────────────────────────────────────────────────
@@ -32,14 +32,15 @@ export type { SegmentContextValue } from './segment-context.js';
 
 // ── Segment cache ────────────────────────────────────────────────────────
 export { SegmentCache, PrefetchCache } from './segment-cache.js';
-export type { SegmentNode, StateTree } from './segment-cache.js';
+export type { SegmentNode, PrefetchKey } from './segment-cache.js';
+export type { SegmentInfo, StateTree } from '../shared/segment-info.js';
 
 // ── History ──────────────────────────────────────────────────────────────
 export { HistoryStack } from './history.js';
 export type { HistoryEntry } from './history.js';
 
 // ── Params (internal setter + raw hooks) ─────────────────────────────────
-export { setCurrentParams } from './use-segment-params.js';
+export { setCurrentParams, setCurrentSlotParams } from './use-segment-params.js';
 export { useSearchParams } from './use-search-params.js';
 
 // ── Navigation context ───────────────────────────────────────────────────

package/src/client/link.tsx

@@ -14,18 +14,18 @@
 // Typed Link: design/09-typescript.md §"Typed Link"
 // - href validated against known routes (via codegen overloads, not runtime)
 // - params prop typed per-route, URL interpolated at runtime
-// - searchParams prop serialized via SearchParamsDefinition
+// - searchParams prop is a query string (from `definition.buildSearchParams()`)
+//   or a plain object whose values are String()-coerced
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
 import {
-  useTransition,
+  useRef,
+  useState,
   type AnchorHTMLAttributes,
   type ReactNode,
   type MouseEvent as ReactMouseEvent,
 } from 'react';
-import type { SearchParamsDefinition } from '../search-params/define.js';
-import { getSearchParamsDefinition } from '../search-params/registry.js';
 import type { LinkFunction } from './index.js';
 import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.js';
 import {
@@ -130,26 +130,37 @@ export type LinkSegmentParams<T> = {
 
 // ─── searchParams prop shapes ────────────────────────────────────
 //
-// Per-route Link overloads (emitted by codegen) pass the flat values shape:
-//     searchParams={{ page: 2, q: 'boots' }}
-// The framework looks up the route's SearchParamsDefinition from the
-// search-params registry at runtime (see TIM-830).
+// Two shapes, discriminated at runtime by `typeof === 'string'`:
 //
-// The catch-all overload in client/index.ts (external/computed hrefs)
-// additionally accepts the legacy wrapped shape:
-//     searchParams={{ definition: def, values: { page: 2 } }}
-// because there is no way to look up a definition from a computed string.
+//   1. Codec-aware (preferred) — a query string built from a definition:
+//        searchParams={productParams.buildSearchParams({ page: 2, search: 'boots' })}
+//      `buildSearchParams` applies each codec, honours `withUrlKey` aliases,
+//      and omits values equal to their default. It is typed `Partial<T>` at
+//      the call site, so the definition supplies the type checking.
 //
-// `resolveHref` discriminates at runtime by presence of a `definition` key.
+//   2. Plain object (escape hatch) — every value is String()-coerced:
+//        searchParams={{ ref: 'email' }}
+//      No codecs, no aliases. This is for one-off params that have no
+//      definition. Passing a *definition's* keys this way is a mistake the
+//      types cannot catch: `{ search: 'x' }` emits `?search=x`, where the
+//      definition would emit `?q=x`. Prefer (1) whenever a definition exists.
+//
+// Why a STRING and not a URLSearchParams: a Link is routinely rendered by a
+// Server Component, so this prop crosses the RSC Flight boundary before the
+// client Link runs. `URLSearchParams` is iterable, and React serializes any
+// iterable as an array — so the prop arrived as `[['pg','2'], …]`, fell into
+// the plain-object branch, and rendered `?0=pg&0=2`. Strings survive Flight
+// unchanged. (Codex P1 on PR #1021; reproduced against a live dev server.)
+//
+// TIM-1343 removed the third shape — a flat values object resolved against a
+// runtime registry keyed by href. It required scanning a `params.ts`
+// convention file, a generated registry module, and eager imports of every
+// route's definition into all three entries, to save one `.buildSearchParams`
+// call. See design/23-search-params.md §"Link Integration".
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ParamValue = string | number | string[] | { toString(): string; [key: string]: any };
 
-type WrappedSearchParamsProp = {
-  definition: SearchParamsDefinition<Record<string, unknown>>;
-  values: Record<string, unknown>;
-};
-type FlatSearchParamsProp = Record<string, unknown>;
-type LinkSearchParamsProp = WrappedSearchParamsProp | FlatSearchParamsProp;
+type LinkSearchParamsProp = string | Record<string, unknown>;
 
 /**
  * Runtime-only loose props used internally by the Link implementation.
@@ -302,16 +313,35 @@ export function interpolateParams(pattern: string, params: Record<string, ParamV
  *
  * Handles:
  * - params interpolation into route patterns
- * - searchParams serialization via SearchParamsDefinition
+ * - searchParams serialization (see the two shapes documented above)
  * - Validation that searchParams and inline query strings are exclusive
  */
 /**
- * Runtime discriminator: treat `searchParams` as the legacy wrapped shape
- * only when it literally has a `definition` key. Everything else is the
- * flat `Partial<T>` values shape (TIM-830).
+ * Tolerate a leading '?'. `buildSearchParams()` never emits one, but callers
+ * hand-rolling a query string reasonably might, and silently producing
+ * `?%3Fa=b` for it would be a worse failure than accepting both.
+ */
+function stripLeadingQuestionMark(qs: string): string {
+  return qs.startsWith('?') ? qs.slice(1) : qs;
+}
+
+/**
+ * Escape-hatch serialization for a plain object: String()-coerce every
+ * value, append arrays as repeated keys, skip null/undefined.
+ *
+ * Deliberately codec-free and alias-free — see the shape docs above.
  */
-function isWrappedSearchParamsProp(sp: LinkSearchParamsProp): sp is WrappedSearchParamsProp {
-  return 'definition' in sp;
+function coerceToQueryString(values: Record<string, unknown>): string {
+  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));
+    }
+  }
+  return usp.toString();
 }
 
 export function resolveHref(
@@ -336,46 +366,18 @@ export function resolveHref(
       );
     }
 
-    let definition: SearchParamsDefinition<Record<string, unknown>> | undefined;
-    let values: Record<string, unknown>;
-
-    if (isWrappedSearchParamsProp(searchParams)) {
-      // Legacy wrapped shape — used by the catch-all overload for
-      // computed/external hrefs where no route lookup is possible.
-      definition = searchParams.definition;
-      values = searchParams.values;
-    } else {
-      // Flat shape (TIM-830): look up the definition from the runtime
-      // registry using the un-interpolated href pattern (e.g. '/products/[id]').
-      // The search-params registry is populated eagerly at startup by the
-      // virtual:timber-search-params-registry module generated by the
-      // timber-routing Vite plugin.
-      definition = getSearchParamsDefinition(href) as
-        | SearchParamsDefinition<Record<string, unknown>>
-        | undefined;
-      values = searchParams;
-    }
-
-    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}`;
-      }
+    // A string is already a serialized query (from
+    // `definition.buildSearchParams()`), so it passes through untouched.
+    // `typeof` is the only discriminator that survives the RSC Flight
+    // boundary — see the shape docs above for what happened when this was
+    // an object test.
+    const qs =
+      typeof searchParams === 'string'
+        ? stripLeadingQuestionMark(searchParams)
+        : coerceToQueryString(searchParams);
+
+    if (qs) {
+      resolvedPath = `${resolvedPath}?${qs}`;
     }
   }
 
@@ -472,11 +474,38 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
 
   // ─── Per-link pending state ─────────────────────────────────────────
-  // Each Link owns a useTransition. On click, it wraps
-  // router.navigate() in startTransition — only this Link re-renders
-  // for isPending, zero siblings touched. The transition tracks the
-  // full navigation lifecycle (fetch + render + commit).
-  const [isPending, startTransition] = useTransition();
+  // Local `useState`, deliberately NOT `useTransition` (TIM-1307).
+  //
+  // Either shape keeps the re-render local — the state lives on this Link's
+  // own fiber, so no sibling link is touched. The difference is what wrapping
+  // `router.navigate()` in a transition does to the REST of the app: returning
+  // a thenable from `startTransition` hands it to `ReactSharedInternals.S`,
+  // which calls react-dom's `entangleAsyncAction`. That opens an action scope
+  // whose `currentEntangledLane` collects every transition update scheduled
+  // while it is open — including `NavigationRoot`'s `setRendered`, which is a
+  // fully synchronous `startTransition` in a different component — and
+  // rendering that lane suspends on `currentEntangledActionThenable` until the
+  // action settles. `navigateTransition` awaits `decodePromise`, so a Link
+  // navigation used to commit only after the whole Flight stream had decoded,
+  // while `useRouter().push()` committed as soon as React could render it.
+  //
+  // Two commit-timing regimes, and the slower one was the dominant path: no
+  // streaming reveal, and the TIM-1301 publish (address bar, segment cache,
+  // `timber:navigation-end`) waited for full decode. Not opening an action
+  // scope is what collapses them into one.
+  //
+  // `isPending` runs from the click until `router.navigate()` settles, which
+  // is after `decodePromise` — the same lifecycle the router's pending store
+  // and the TopLoader use.
+  //
+  // `clickSeq` exists because a superseded navigation RESOLVES rather than
+  // rejecting: `runNavigation` swallows AbortErrors. So clicking the same link
+  // twice in quick succession settles the first promise while the second is
+  // still in flight, and an unguarded clear would report idle mid-navigation.
+  // Only the newest click for this link may clear its flag. Written on click
+  // and nowhere else, so there is no reset for a settle handler to race.
+  const [isPending, setIsPending] = useState(false);
+  const clickSeq = useRef(0);
   const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 
   // Preserve search params from the current URL when requested.
@@ -544,8 +573,27 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         // from the RSC fetch URL inside the router (TIM-1035).
         const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
 
-        startTransition(async () => {
-          await router.navigate(absoluteHref, { scroll: shouldScroll });
+        const seq = ++clickSeq.current;
+        const settle = () => {
+          if (clickSeq.current === seq) setIsPending(false);
+        };
+        setIsPending(true);
+        router.navigate(absoluteHref, { scroll: shouldScroll }).then(settle, (error: unknown) => {
+          settle();
+          // Rethrow, so a navigation error that the router did not already
+          // recover from surfaces as an unhandled rejection — the same
+          // regime as `useRouter().push()`'s `void router.navigate(...)`.
+          //
+          // It used to reach the nearest error boundary instead: React
+          // re-throws a rejected async action during render (measured on
+          // 19.2.7). That replaced the departing page with the app's error
+          // UI, which contradicts what every other failure path here
+          // promises — a navigation that fails leaves the user on the page
+          // they were already looking at (TIM-1306). Recoverable failures
+          // never get here anyway; `runNavigation` swallows AbortErrors and
+          // `recoverFromNavigationError` turns a failed fetch into a full
+          // document load.
+          throw error;
         });
       }
     : userOnClick; // External links — just pass through user's onClick

package/src/client/navigation-api.ts

@@ -97,8 +97,8 @@ export interface NavigationApiController {
   /**
    * Resolve the deferred promise created by setRouterNavigating(true),
    * clearing the browser's native loading state. Call this when the
-   * navigation fully completes — aligned with when the TopLoader's
-   * pendingUrl clears (same finally block in router.navigate).
+   * navigation fully completes — the same finally block in router.navigate
+   * that clears the router's pending store.
    */
   completeRouterNavigation: () => void;
 
@@ -147,7 +147,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
   // setRouterNavigating(true) is called, resolved by completeRouterNavigation().
   // The navigate event handler intercepts with this promise so the browser's
   // native loading state (tab spinner) stays active until the navigation
-  // completes — aligned with TopLoader's pendingUrl lifecycle.
+  // completes — the same lifecycle the TopLoader is driven by.
   let routerNavDeferred: { promise: Promise<void>; resolve: () => void } | null = null;
 
   function handleNavigate(event: NavigateEvent): void {

package/src/client/navigation-commit.ts

@@ -0,0 +1,197 @@
+/**
+ * What it means for a page to be "current" on the client.
+ *
+ * One module owns every write that makes a navigation's destination the
+ * current page, and the read that describes the current page back to the
+ * server. Keeping them together is the point: `X-Timber-State-Tree` is
+ * derived from the segment cache, so the thing that publishes and the thing
+ * that reports have to agree about when a page becomes current.
+ *
+ * See design/19-client-navigation.md §"State Update Invariants".
+ */
+
+import { buildSegmentTree, type SegmentCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import { setNavigationState, type NavigationState } from './navigation-context.js';
+
+/** Everything a commit needs to describe the page it makes current. */
+export interface NavigationCommitInput {
+  payload: unknown;
+  /** The params that payload published — replayed with it on popstate. */
+  params: ParamsSource;
+  /**
+   * The rendered chain's metadata, or null/undefined when this commit
+   * carries none at all — a revalidation payload, or a history entry
+   * stored before the channel existed.
+   *
+   * An empty *array* is a different statement from an absent one: the
+   * server rendered a route with no layout-bearing segments (a layoutless
+   * app — the missing-root-layout check is a warning, not an error), so
+   * the correct tree is the empty one. Collapsing the two left the
+   * departing route's tree in place, which `treePaths` then reported as
+   * mounted — enough to select an intercepting rewrite whose slot is not
+   * on screen (TIM-1282).
+   */
+  segmentInfo?: SegmentInfo[] | null;
+  /** When true, clear the segment cache if segmentInfo is absent
+   *  (popstate replay for entries without layout metadata). */
+  clearSegmentCacheOnEmpty?: boolean;
+  /**
+   * HTTP status of the response this navigation rendered, when it came from a
+   * fetch. Omitted by replays, which re-publish a tree already judged.
+   *
+   * An error response rendered a status page, and a status page replaces a
+   * subtree: the deny page lands at the segment owning the matched file and
+   * nothing below it mounts. `segmentInfo` nonetheless describes the whole
+   * chain the payload was built against — it must, because the merge point is
+   * chosen out of it — so the cache has to be told not to learn from this one.
+   *
+   * Enforced here rather than at the call sites because there are three of
+   * them (`performNavigationFetch`, `refresh()`, and uncached traversal, the
+   * last two through `fetchCommitAndRender`) and only one had the check.
+   * See TIM-1356.
+   */
+  status?: number;
+}
+
+/**
+ * A navigation's destination, split into what a render needs and what a
+ * commit publishes.
+ */
+export interface PreparedNavigation {
+  /** The state the incoming tree renders with. Pure — safe before winning. */
+  navState: NavigationState;
+  /** Publishes the destination. Call only once the render has won. */
+  commit: () => void;
+}
+
+export interface NavigationCommitter {
+  prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
+  currentStateTree(): StateTree | undefined;
+  updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+}
+
+/**
+ * Derive the navigation state (pathname + search) a URL renders with.
+ *
+ * Pure: publishing it — the module-level fallback for tests and SSR, and the
+ * globalThis bridge — is `prepareNavigation`'s commit, which runs only once
+ * the render is known to have won (TIM-1301). Callers pass the returned value
+ * explicitly to renderRoot/wrapPayload, so a render never depends on the
+ * publish having happened first.
+ */
+export function deriveNavigationState(url: string): NavigationState {
+  // Params are not part of it. They travel with the payload and are published
+  // by the one client-owned `ParamsProvider` as the new tree renders, which is
+  // also what clears the previous route's — a route with no params of its own
+  // still publishes an empty record (TIM-1294/TIM-1297, and the clearing
+  // requirement from TIM-1285).
+  const parsed = new URL(url, 'http://localhost');
+  return { pathname: parsed.pathname || '/', search: parsed.search };
+}
+
+export function createNavigationCommitter(deps: {
+  segmentCache: SegmentCache;
+  historyStack: HistoryStack;
+  /** Read at call time — the router's `clientSegmentCache` opt-in. */
+  clientSegmentCache: () => boolean | undefined;
+}): NavigationCommitter {
+  const { segmentCache, historyStack } = deps;
+
+  /**
+   * Update the segment cache from server-provided segment metadata.
+   *
+   * Runs whether or not `clientSegmentCache` is enabled: the tree is also
+   * where the mounted tree paths come from, and those cross on every
+   * navigation. What the flag gates is which parts get serialized — see
+   * `currentStateTree`.
+   */
+  function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!segmentInfo || segmentInfo.length === 0) return;
+    const tree = buildSegmentTree(segmentInfo);
+    if (tree) {
+      segmentCache.set('/', tree);
+    }
+  }
+
+  return {
+    updateSegmentCache,
+
+    /**
+     * The X-Timber-State-Tree to send with the next RSC request.
+     *
+     * Two different things travel on one header. `segments`/`slots` are the
+     * caching opt-in and are omitted unless `clientSegmentCache` is on.
+     * `treePaths` is how the server learns which route is actually mounted,
+     * which stops being derivable from the address bar as soon as a modal is
+     * open — so it crosses regardless (TIM-1282). Undefined when there is
+     * nothing to say, so a no-op header never enters the `_rsc` cache key.
+     *
+     * Reads what the last *committed* navigation published, so a superseded
+     * navigation's destination can never end up describing the mounted tree
+     * (TIM-1301).
+     */
+    currentStateTree(): StateTree | undefined {
+      const tree = segmentCache.serializeStateTree();
+      if (deps.clientSegmentCache()) return tree;
+      return tree.treePaths ? { segments: [], treePaths: tree.treePaths } : undefined;
+    },
+
+    /**
+     * Prepare all navigation-owned state for a new page — without publishing
+     * any of it. Every code path that changes the "current page" must go
+     * through this function, which is what makes "forgot a field" impossible
+     * by construction.
+     *
+     * Returns the destination's `NavigationState`, which is a pure function of
+     * the URL and is what the incoming tree is *rendered* with, plus a
+     * `commit` thunk that performs the writes that make a page current:
+     * 1. Segment cache — update from server-provided segment metadata
+     * 2. Navigation state — pathname/search for usePathname/useSearchParams
+     * 3. History stack — store the payload for instant back/forward replay
+     *
+     * Nothing is written until `commit()` runs, and on a transitioned
+     * navigation it runs only once the transition is known to have won — see
+     * `renderViaTransition` and `NavigationRoot`. A navigation superseded
+     * while its payload was in flight never calls it, so the cache, the
+     * pathname the client reports and the history stack all keep describing
+     * the route still on screen (TIM-1301).
+     *
+     * Callers with state of their own to publish — the address bar, the
+     * client's record of the mounted tree — wrap this thunk rather than
+     * commit beside it, so there stays exactly one moment at which a page
+     * becomes current.
+     */
+    prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation {
+      const navState = deriveNavigationState(url);
+
+      // A tree rendered by an error response is not one to cache — see
+      // `status` on NavigationCommitInput. Normalized here, once, so no fetch
+      // caller can forget it; the history entry records the same thing, or a
+      // traversal back to this URL would replay the metadata this drops.
+      const cacheable = opts.status === undefined || opts.status < 400;
+      const segmentInfo = cacheable ? opts.segmentInfo : [];
+
+      return {
+        navState,
+        commit() {
+          if (segmentInfo && segmentInfo.length > 0) {
+            updateSegmentCache(segmentInfo);
+          } else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
+            segmentCache.clear();
+          }
+
+          setNavigationState(navState);
+
+          historyStack.push(url, {
+            payload: opts.payload,
+            params: opts.params,
+            segmentInfo,
+          });
+        },
+      };
+    },
+  };
+}