@timber-js/app 0.1.23 → 0.1.25

package/dist/client/use-params.d.ts

@@ -18,10 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: useParams() uses useSyncExternalStore so that components
- * in unchanged layouts (e.g., sidebar items) re-render atomically when
- * params change during client-side navigation. This matches the pattern
- * used by usePathname() and useSearchParams().
+ * Reactivity: On the client, useParams() reads from NavigationContext
+ * which is updated atomically with the RSC tree render. This replaces
+ * the previous useSyncExternalStore approach that suffered from a
+ * timing gap between tree render and store notification — causing
+ * preserved layout components to briefly show stale active state.
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -30,37 +31,40 @@
  */
 import type { Routes } from '#/index.js';
 /**
- * Subscribe to params changes. Called by useSyncExternalStore.
- * Exported for testing — not intended for direct use by app code.
+ * Subscribe to params changes.
+ * Retained for backward compatibility with tests that verify the
+ * subscribe/notify contract. On the client, useParams() reads from
+ * NavigationContext instead.
  */
 export declare function subscribe(callback: () => void): () => void;
 /**
- * Get the current params snapshot (client).
- * Exported for testing — not intended for direct use by app code.
+ * Get the current params snapshot (module-level fallback).
+ * Used by tests and by the hook when called outside a React component.
  */
 export declare function getSnapshot(): Record<string, string | string[]>;
 /**
- * Set the current route params WITHOUT notifying subscribers.
- * Called by the router before renderPayload() so that new components
- * in the RSC tree see the updated params via getSnapshot(), but
- * preserved layout components don't re-render prematurely with
- * {old tree, new params}.
+ * Set the current route params in the module-level store.
  *
- * After the React render commits, the router calls notifyParamsListeners()
- * to trigger re-renders in preserved layouts that read useParams().
+ * Called by the router on each navigation. This updates the fallback
+ * snapshot used by tests and by the hook when called outside a React
+ * component (no NavigationContext available).
+ *
+ * On the client, the primary reactivity path is NavigationContext —
+ * the router calls setNavigationState() then renderRoot() which wraps
+ * the element in NavigationProvider. setCurrentParams is still called
+ * for the module-level fallback.
  *
- * On the client, the segment router calls this on each navigation.
  * During SSR, params are also available via getSsrData().params
- * (ALS-backed), but setCurrentParams is still called for the
- * module-level fallback path.
+ * (ALS-backed).
  */
 export declare function setCurrentParams(params: Record<string, string | string[]>): void;
 /**
- * Notify all useSyncExternalStore subscribers that params have changed.
- * Called by the router AFTER renderPayload() so that preserved layout
- * components re-render only after the new tree is committed — producing
- * an atomic {new tree, new params} update instead of a stale
- * {old tree, new params} intermediate state.
+ * Notify all legacy subscribers that params have changed.
+ *
+ * Retained for backward compatibility with tests. On the client,
+ * the NavigationContext + renderRoot pattern replaces this — params
+ * update atomically with the tree render, so explicit notification
+ * is no longer needed.
  */
 export declare function notifyParamsListeners(): void;
 /**
@@ -69,9 +73,15 @@ export declare function notifyParamsListeners(): void;
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). This ensures params update
+ * atomically with the RSC tree — no timing gap.
+ *
  * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation. On the client, subscribes to the module-level
- * params store via useSyncExternalStore.
+ * per-request isolation across concurrent requests with streaming Suspense.
+ *
+ * When called outside a React component (e.g., in test assertions),
+ * falls back to the module-level snapshot.
  *
  * @overload Typed — when a known route path is passed, returns the
  *   exact params shape from the generated Routes interface.

package/dist/client/use-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-params.d.ts","sourceRoot":"","sources":["../../src/client/use-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAQzC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACjF,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}
+{"version":3,"file":"use-params.d.ts","sourceRoot":"","sources":["../../src/client/use-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AASzC;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACjF,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/dist/client/use-pathname.d.ts

@@ -4,17 +4,24 @@
  * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
  * Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.pathname, provided for
- * Next.js API compatibility (libraries like nuqs import usePathname
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render. This replaces the previous useSyncExternalStore
+ * approach which only subscribed to popstate events — meaning usePathname()
+ * did NOT re-render on forward navigation (pushState). The context approach
+ * fixes this: pathname updates in the same render pass as the new tree.
  *
  * During SSR, reads the request pathname from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
+ *
+ * Compatible with Next.js's `usePathname()` from `next/navigation`.
  */
 /**
  * Read the current URL pathname.
  *
- * Compatible with Next.js's `usePathname()` from `next/navigation`.
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). During SSR, reads from the
+ * ALS-backed SSR data context. Falls back to window.location.pathname
+ * when called outside a React component (e.g., in tests).
  */
 export declare function usePathname(): string;
 //# sourceMappingURL=use-pathname.d.ts.map

package/dist/client/use-pathname.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuBH;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAoBpC"}

package/dist/client/use-router.d.ts

@@ -7,6 +7,20 @@
  *
  * This wraps timber's internal RouterInstance in the Next.js-compatible
  * AppRouterInstance shape that ecosystem libraries expect.
+ *
+ * NOTE: Unlike Next.js, these methods do NOT wrap navigation in
+ * startTransition. In Next.js, router state is React state (useReducer)
+ * so startTransition defers the update and provides isPending tracking.
+ * In timber, navigation calls reactRoot.render() which is a root-level
+ * render — startTransition has no effect on root renders.
+ *
+ * Navigation state (params, pathname) is delivered atomically via
+ * NavigationContext embedded in the element tree passed to
+ * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
+ *
+ * For loading UI during navigation, use:
+ * - useLinkStatus()          — per-link pending indicator (inside <Link>)
+ * - useNavigationPending()   — global navigation pending state
  */
 export interface AppRouterInstance {
     /** Navigate to a URL, pushing a new history entry */

package/dist/client/use-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CAuD7C"}
+{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CA4C7C"}

package/dist/cookies/index.js

@@ -1,7 +1,7 @@
 import "../_chunks/als-registry-c0AGnbqS.js";
 import { n as cookies } from "../_chunks/request-context-C69VW4xS.js";
-import "../_chunks/ssr-data-B2yikEEB.js";
-import { t as useCookie } from "../_chunks/use-cookie-D5aS4slY.js";
+import "../_chunks/ssr-data-DLnbYpj1.js";
+import { t as useCookie } from "../_chunks/use-cookie-dDbpCTx-.js";
 //#region src/cookies/define-cookie.ts
 /**
 * defineCookie — typed cookie definitions.