@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/dist/_chunks/use-segment-params-D1CzlgBo.js

@@ -0,0 +1,151 @@
+import { a as _setCurrentParams, l as currentParams, n as getSsrData } from "./ssr-data-BOWsq18U.js";
+import React, { createElement } from "react";
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current route params and pathname, updated atomically
+* with the RSC tree on each navigation. This replaces the previous
+* useSyncExternalStore approach for useSegmentParams() and usePathname(),
+* which suffered from a timing gap: the new tree could commit before
+* the external store re-renders fired, causing a frame where both
+* old and new active states were visible simultaneously.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (useParams, usePathname) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in usePendingNavigation (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*
+* NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an
+* internal helper — the public hook is `usePendingNavigation()` in
+* use-pending-navigation.ts.
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+function getOrCreateContext() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by useSegmentParams() and usePathname().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		params: {},
+		pathname: "/",
+		search: ""
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+//#endregion
+//#region src/client/use-segment-params.ts
+/**
+* Set the current route params in the module-level store.
+*
+* 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.
+*
+* During SSR, params are also available via getSsrData().params
+* (ALS-backed).
+*/
+function setCurrentParams(params) {
+	_setCurrentParams(params);
+}
+function useSegmentParams(_segmentPath) {
+	try {
+		const navContext = useNavigationContext();
+		if (navContext !== null) return navContext.params;
+	} catch {}
+	return getSsrData()?.params ?? currentParams;
+}
+//#endregion
+export { setNavigationState as a, getNavigationState as i, useSegmentParams as n, useNavigationContext as o, NavigationProvider as r, setCurrentParams as t };
+
+//# sourceMappingURL=use-segment-params-D1CzlgBo.js.map

package/dist/_chunks/use-segment-params-D1CzlgBo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segment-params-D1CzlgBo.js","names":[],"sources":["../../src/client/navigation-context.ts","../../src/client/use-segment-params.ts"],"sourcesContent":["'use client';\n\n/**\n * NavigationContext — React context for navigation state.\n *\n * Holds the current route params and pathname, updated atomically\n * with the RSC tree on each navigation. This replaces the previous\n * useSyncExternalStore approach for useSegmentParams() and usePathname(),\n * which suffered from a timing gap: the new tree could commit before\n * the external store re-renders fired, causing a frame where both\n * old and new active states were visible simultaneously.\n *\n * By wrapping the RSC payload element in NavigationProvider inside\n * renderRoot(), the context value and the element tree are passed to\n * reactRoot.render() in the same call — atomic by construction.\n * All consumers (useParams, usePathname) see the new values in the\n * same render pass as the new tree.\n *\n * During SSR, no NavigationProvider is mounted. Hooks fall back to\n * the ALS-backed getSsrData() for per-request isolation.\n *\n * IMPORTANT: createContext and useContext are NOT available in the RSC\n * environment (React Server Components use a stripped-down React).\n * The context is lazily initialized on first access, and all functions\n * that depend on these APIs are safe to call from any environment —\n * they return null or no-op when the APIs aren't available.\n *\n * SINGLETON GUARANTEE: All shared mutable state uses globalThis via\n * Symbol.for keys. The RSC client bundler can duplicate this module\n * across chunks (browser-entry graph + client-reference graph). With\n * ESM output, each chunk gets its own module scope — module-level\n * variables would create separate singleton instances per chunk.\n * globalThis guarantees a single instance regardless of duplication.\n *\n * This workaround will be removed when Rolldown ships `format: 'app'`\n * (module registry format that deduplicates like webpack/Turbopack).\n * See design/27-chunking-strategy.md.\n *\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport React, { createElement, type ReactNode } from 'react';\n\n// ---------------------------------------------------------------------------\n// Context type\n// ---------------------------------------------------------------------------\n\nexport interface NavigationState {\n  params: Record<string, string | string[]>;\n  pathname: string;\n  search: string;\n}\n\n// ---------------------------------------------------------------------------\n// Lazy context initialization\n// ---------------------------------------------------------------------------\n\n/**\n * The context is created lazily to avoid calling createContext at module\n * level. In the RSC environment, React.createContext doesn't exist —\n * calling it at import time would crash the server.\n *\n * Context instances are stored on globalThis (NOT in module-level\n * variables) because the ESM bundler can duplicate this module across\n * chunks. Module-level variables would create separate instances per\n * chunk — the provider in NavigationRoot (index chunk) would use\n * context A while the consumer in usePendingNavigation (shared chunk)\n * reads from context B. globalThis guarantees a single instance.\n *\n * See design/27-chunking-strategy.md §\"Singleton Safety\"\n *\n * NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an\n * internal helper — the public hook is `usePendingNavigation()` in\n * use-pending-navigation.ts.\n */\n\n// Symbol keys for globalThis storage — prevents collisions with user code\nconst NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');\nconst PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');\n\nfunction getOrCreateContext(): React.Context<NavigationState | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as\n    | React.Context<NavigationState | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  // createContext may not exist in the RSC environment\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<NavigationState | null>(null);\n    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the navigation context. Returns null during SSR (no provider)\n * or in the RSC environment (no context available).\n * Internal — used by useSegmentParams() and usePathname().\n */\nexport function useNavigationContext(): NavigationState | null {\n  const ctx = getOrCreateContext();\n  if (!ctx) return null;\n  // useContext may not exist in the RSC environment — caller wraps in try/catch\n  if (typeof React.useContext !== 'function') return null;\n  // eslint-disable-next-line rules-of-hooks -- conditional on environment, not render path\n  return React.useContext(ctx);\n}\n\n// ---------------------------------------------------------------------------\n// Provider component\n// ---------------------------------------------------------------------------\n\nexport interface NavigationProviderProps {\n  value: NavigationState;\n  children?: ReactNode;\n}\n\n/**\n * Wraps children with NavigationContext.Provider.\n *\n * Used in browser-entry.ts renderRoot to wrap the RSC payload element\n * so that navigation state updates atomically with the tree render.\n */\nexport function NavigationProvider({\n  value,\n  children,\n}: NavigationProviderProps): React.ReactElement {\n  const ctx = getOrCreateContext();\n  if (!ctx) {\n    // RSC environment — no context available. Return children as-is.\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n\n// ---------------------------------------------------------------------------\n// Module-level state for renderRoot to read\n// ---------------------------------------------------------------------------\n\n/**\n * Navigation state communicated between the router and renderRoot.\n *\n * The router calls setNavigationState() before renderRoot(). The\n * renderRoot callback reads via getNavigationState() to create the\n * NavigationProvider with the correct params/pathname.\n *\n * This is NOT used by hooks directly — hooks read from React context.\n *\n * Stored on globalThis (like the context instances above) because the\n * router lives in one chunk while renderRoot lives in another. Module-\n * level variables would be separate per chunk.\n */\nconst NAV_STATE_KEY = Symbol.for('__timber_nav_state');\n\nfunction _getNavStateStore(): { current: NavigationState } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_STATE_KEY]) {\n    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/', search: '' } };\n  }\n  return g[NAV_STATE_KEY] as { current: NavigationState };\n}\n\nexport function setNavigationState(state: NavigationState): void {\n  _getNavStateStore().current = state;\n}\n\nexport function getNavigationState(): NavigationState {\n  return _getNavStateStore().current;\n}\n\n// ---------------------------------------------------------------------------\n// Pending Navigation Context (same module for singleton guarantee)\n// ---------------------------------------------------------------------------\n\n/**\n * Separate context for the in-flight navigation URL. Provided by\n * NavigationRoot (urgent useState), consumed by usePendingNavigation\n * and TopLoader. Per-link pending state uses useOptimistic instead\n * (see design/19-client-navigation.md §\"Per-Link Pending State\").\n *\n * Uses globalThis via Symbol.for for the same reason as NavigationContext\n * above — the bundler may duplicate this module across chunks, and module-\n * level variables would create separate context instances.\n */\n\nfunction getOrCreatePendingContext(): React.Context<string | null> | undefined {\n  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as\n    | React.Context<string | null>\n    | undefined;\n  if (existing !== undefined) return existing;\n  if (typeof React.createContext === 'function') {\n    const ctx = React.createContext<string | null>(null);\n    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;\n    return ctx;\n  }\n  return undefined;\n}\n\n/**\n * Read the pending navigation URL from context.\n * Returns null during SSR (no provider) or in the RSC environment.\n */\nexport function usePendingNavigationUrl(): string | null {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) return null;\n  if (typeof React.useContext !== 'function') return null;\n  // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n  return React.useContext(ctx);\n}\n\n/**\n * Provider for the pending navigation URL. Wraps children with\n * the pending context Provider.\n */\nexport function PendingNavigationProvider({\n  value,\n  children,\n}: {\n  value: string | null;\n  children?: ReactNode;\n}): React.ReactElement {\n  const ctx = getOrCreatePendingContext();\n  if (!ctx) {\n    return children as React.ReactElement;\n  }\n  return createElement(ctx.Provider, { value }, children);\n}\n","/**\n * useParams() — client-side hook for accessing route params.\n *\n * Returns the dynamic route parameters for the current URL.\n * When called with a route pattern argument, TypeScript narrows\n * the return type to the exact params shape for that route.\n *\n * Two layers of type narrowing work together:\n * 1. The generic overload here uses the Routes interface directly —\n *    `useParams<R>()` returns `Routes[R]['segmentParams']`.\n * 2. Build-time codegen generates per-route string-literal overloads\n *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).\n *\n * When the Routes interface is empty (no codegen yet), the generic\n * overload has `keyof Routes = never`, so only the fallback matches.\n *\n * During SSR, params are read from the ALS-backed SSR data context\n * (populated by ssr-entry.ts) to ensure correct per-request isolation\n * across concurrent requests with streaming Suspense.\n *\n * Reactivity: On the client, useParams() reads from NavigationContext\n * which is updated atomically with the RSC tree render. This replaces\n * the previous useSyncExternalStore approach that suffered from a\n * timing gap between tree render and store notification — causing\n * preserved layout components to briefly show stale active state.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n *\n * Design doc: design/09-typescript.md §\"Typed Routes\"\n */\n\nimport type { Routes } from '../index.js';\nimport { getSsrData } from './ssr-data.js';\nimport { currentParams, _setCurrentParams, paramsListeners } from './state.js';\nimport { useNavigationContext } from './navigation-context.js';\n\n// ---------------------------------------------------------------------------\n// Module-level subscribe/notify pattern — kept for backward compat and tests\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribe to params changes.\n * Retained for backward compatibility with tests that verify the\n * subscribe/notify contract. On the client, useParams() reads from\n * NavigationContext instead.\n */\nexport function subscribe(callback: () => void): () => void {\n  paramsListeners.add(callback);\n  return () => paramsListeners.delete(callback);\n}\n\n/**\n * Get the current params snapshot (module-level fallback).\n * Used by tests and by the hook when called outside a React component.\n */\nexport function getSnapshot(): Record<string, string | string[]> {\n  return currentParams;\n}\n\n// ---------------------------------------------------------------------------\n// Framework API — called by the segment router on each navigation\n// ---------------------------------------------------------------------------\n\n/**\n * Set the current route params in the module-level store.\n *\n * Called by the router on each navigation. This updates the fallback\n * snapshot used by tests and by the hook when called outside a React\n * component (no NavigationContext available).\n *\n * On the client, the primary reactivity path is NavigationContext —\n * the router calls setNavigationState() then renderRoot() which wraps\n * the element in NavigationProvider. setCurrentParams is still called\n * for the module-level fallback.\n *\n * During SSR, params are also available via getSsrData().params\n * (ALS-backed).\n */\nexport function setCurrentParams(params: Record<string, string | string[]>): void {\n  _setCurrentParams(params);\n}\n\n/**\n * Notify all legacy subscribers that params have changed.\n *\n * Retained for backward compatibility with tests. On the client,\n * the NavigationContext + renderRoot pattern replaces this — params\n * update atomically with the tree render, so explicit notification\n * is no longer needed.\n */\nexport function notifyParamsListeners(): void {\n  for (const listener of paramsListeners) {\n    listener();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public hook\n// ---------------------------------------------------------------------------\n\n/**\n * Read the current route's dynamic params.\n *\n * The optional `_route` argument exists only for TypeScript narrowing —\n * it does not affect the runtime return value.\n *\n * On the client, reads from NavigationContext (provided by\n * NavigationProvider in renderRoot). This ensures params update\n * atomically with the RSC tree — no timing gap.\n *\n * During SSR, reads from the ALS-backed SSR data context to ensure\n * per-request isolation across concurrent requests with streaming Suspense.\n *\n * When called outside a React component (e.g., in test assertions),\n * falls back to the module-level snapshot.\n *\n * @overload Typed — when a known segment path is passed, returns the\n *   exact params shape from the generated Routes interface.\n * @overload Fallback — returns the generic params record.\n */\nexport function useSegmentParams<R extends keyof Routes>(\n  segmentPath: R\n): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;\nexport function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;\nexport function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {\n  // Try reading from NavigationContext (client-side, inside React tree).\n  // During SSR, no NavigationProvider is mounted, so this returns null.\n  // When called outside a React component, useContext throws — caught below.\n  try {\n    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path\n    const navContext = useNavigationContext();\n    if (navContext !== null) {\n      return navContext.params;\n    }\n  } catch {\n    // No React dispatcher available (called outside a component).\n    // Fall through to module-level snapshot below.\n  }\n\n  // SSR path: read from ALS-backed SSR data context.\n  // Falls back to module-level currentParams for tests.\n  return getSsrData()?.params ?? currentParams;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,IAAM,cAAc,OAAO,IAAI,kBAAkB;AAGjD,SAAS,qBAAwE;CAC/E,MAAM,WAAY,WAAuC;CAGzD,IAAI,aAAa,KAAA,GAAW,OAAO;CAEnC,IAAI,OAAO,MAAM,kBAAkB,YAAY;EAC7C,MAAM,MAAM,MAAM,cAAsC,IAAI;EAC5D,WAAwC,eAAe;EACvD,OAAO;CACT;AAEF;;;;;;AAOA,SAAgB,uBAA+C;CAC7D,MAAM,MAAM,mBAAmB;CAC/B,IAAI,CAAC,KAAK,OAAO;CAEjB,IAAI,OAAO,MAAM,eAAe,YAAY,OAAO;CAEnD,OAAO,MAAM,WAAW,GAAG;AAC7B;;;;;;;AAiBA,SAAgB,mBAAmB,EACjC,OACA,YAC8C;CAC9C,MAAM,MAAM,mBAAmB;CAC/B,IAAI,CAAC,KAEH,OAAO;CAET,OAAO,cAAc,IAAI,UAAU,EAAE,MAAM,GAAG,QAAQ;AACxD;;;;;;;;;;;;;;AAmBA,IAAM,gBAAgB,OAAO,IAAI,oBAAoB;AAErD,SAAS,oBAAkD;CACzD,MAAM,IAAI;CACV,IAAI,CAAC,EAAE,gBACL,EAAE,iBAAiB,EAAE,SAAS;EAAE,QAAQ,CAAC;EAAG,UAAU;EAAK,QAAQ;CAAG,EAAE;CAE1E,OAAO,EAAE;AACX;AAEA,SAAgB,mBAAmB,OAA8B;CAC/D,kBAAkB,CAAC,CAAC,UAAU;AAChC;AAEA,SAAgB,qBAAsC;CACpD,OAAO,kBAAkB,CAAC,CAAC;AAC7B;;;;;;;;;;;;;;;;;;ACzFA,SAAgB,iBAAiB,QAAiD;CAChF,kBAAkB,MAAM;AAC1B;AA4CA,SAAgB,iBAAiB,cAA0D;CAIzF,IAAI;EAEF,MAAM,aAAa,qBAAqB;EACxC,IAAI,eAAe,MACjB,OAAO,WAAW;CAEtB,QAAQ,CAGR;CAIA,OAAO,WAAW,CAAC,EAAE,UAAU;AACjC"}