npm - @timber-js/app - Versions diffs - 0.1.23 → 0.1.25 - Mend

@timber-js/app 0.1.23 → 0.1.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/dist/_chunks/{ssr-data-B2yikEEB.js → ssr-data-DLnbYpj1.js} +2 -4
package/dist/_chunks/{ssr-data-B2yikEEB.js.map → ssr-data-DLnbYpj1.js.map} +1 -1
package/dist/_chunks/{use-cookie-D5aS4slY.js → use-cookie-dDbpCTx-.js} +2 -2
package/dist/_chunks/{use-cookie-D5aS4slY.js.map → use-cookie-dDbpCTx-.js.map} +1 -1
package/dist/adapters/nitro.d.ts.map +1 -1
package/dist/adapters/nitro.js +4 -3
package/dist/adapters/nitro.js.map +1 -1
package/dist/cli.js +1 -1
package/dist/cli.js.map +1 -1
package/dist/client/browser-dev.d.ts +29 -0
package/dist/client/browser-dev.d.ts.map +1 -0
package/dist/client/browser-links.d.ts +32 -0
package/dist/client/browser-links.d.ts.map +1 -0
package/dist/client/error-boundary.js +1 -1
package/dist/client/index.d.ts +2 -0
package/dist/client/index.d.ts.map +1 -1
package/dist/client/index.js +150 -122
package/dist/client/index.js.map +1 -1
package/dist/client/navigation-context.d.ts +52 -0
package/dist/client/navigation-context.d.ts.map +1 -0
package/dist/client/router.d.ts.map +1 -1
package/dist/client/transition-root.d.ts +54 -0
package/dist/client/transition-root.d.ts.map +1 -0
package/dist/client/use-params.d.ts +35 -25
package/dist/client/use-params.d.ts.map +1 -1
package/dist/client/use-pathname.d.ts +11 -4
package/dist/client/use-pathname.d.ts.map +1 -1
package/dist/client/use-router.d.ts +14 -0
package/dist/client/use-router.d.ts.map +1 -1
package/dist/cookies/index.js +2 -2
package/dist/server/index.js +264 -218
package/dist/server/index.js.map +1 -1
package/dist/server/metadata-platform.d.ts +34 -0
package/dist/server/metadata-platform.d.ts.map +1 -0
package/dist/server/metadata-render.d.ts.map +1 -1
package/dist/server/metadata-social.d.ts +24 -0
package/dist/server/metadata-social.d.ts.map +1 -0
package/dist/server/pipeline-interception.d.ts +32 -0
package/dist/server/pipeline-interception.d.ts.map +1 -0
package/dist/server/pipeline-metadata.d.ts +31 -0
package/dist/server/pipeline-metadata.d.ts.map +1 -0
package/dist/server/pipeline.d.ts.map +1 -1
package/package.json +1 -1
package/src/adapters/nitro.ts +9 -7
package/src/cli.ts +9 -2
package/src/client/browser-dev.ts +142 -0
package/src/client/browser-entry.ts +73 -223
package/src/client/browser-links.ts +90 -0
package/src/client/index.ts +4 -0
package/src/client/navigation-context.ts +118 -0
package/src/client/router.ts +37 -33
package/src/client/transition-root.tsx +86 -0
package/src/client/use-params.ts +50 -54
package/src/client/use-pathname.ts +31 -24
package/src/client/use-router.ts +17 -15
package/src/server/metadata-platform.ts +229 -0
package/src/server/metadata-render.ts +9 -363
package/src/server/metadata-social.ts +184 -0
package/src/server/pipeline-interception.ts +76 -0
package/src/server/pipeline-metadata.ts +90 -0
package/src/server/pipeline.ts +2 -148

package/src/client/browser-entry.ts CHANGED Viewed

@@ -49,7 +49,10 @@ import type { RouterDeps, RouterInstance } from '@timber-js/app/client';
 import { applyHeadElements } from './head.js';
 import { TimberNuqsAdapter } from './nuqs-adapter.js';
 import { isPageUnloading } from './unload-guard.js';
-import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
+import { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context.js';
+import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
+import { handleLinkClick, handleLinkHover } from './browser-links.js';
+import { TransitionRoot, transitionRender } from './transition-root.js';
 // ─── Server Action Dispatch ──────────────────────────────────────
@@ -178,7 +181,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
-  let reactRoot: Root | null = null;
+  let _reactRoot: Root | null = null;
   let initialElement: unknown = null;
   // Declared here so it's accessible after the if/else hydration block.
   // Assigned inside initRouter() which is called in both branches.
@@ -271,15 +274,44 @@ function bootstrap(runtimeConfig: typeof config): void {
     // hydrateRoot() synchronously executes component render functions.
     // Components that call useRouter() during render need the global
     // router to be available, otherwise they get a stale no-op reference.
-    // The renderRoot callback reads `reactRoot` lazily (via closure), so
-    // it's safe to create the router before reactRoot is assigned.
+    // The router must be initialized before hydration so useRouter() works.
+    // renderRoot uses transitionRender (no direct reactRoot dependency).
     initRouter();
+    // ── Initialize navigation state BEFORE hydration ───────────────────
+    // Read server-embedded params and set navigation state so that
+    // useParams() and usePathname() return correct values during hydration.
+    // This must happen before hydrateRoot so the NavigationProvider
+    // wrapping the element has the right values on the initial render.
+    const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
+    if (earlyParams && typeof earlyParams === 'object') {
+      setCurrentParams(earlyParams as Record<string, string | string[]>);
+      setNavigationState({
+        params: earlyParams as Record<string, string | string[]>,
+        pathname: window.location.pathname,
+      });
+      delete (self as unknown as Record<string, unknown>).__timber_params;
+    } else {
+      setNavigationState({
+        params: {},
+        pathname: window.location.pathname,
+      });
+    }
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
-    // Wrap with TimberNuqsAdapter so useQueryStates works out of the box.
-    const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
-    reactRoot = hydrateRoot(document, wrapped, {
+    // Wrap with NavigationProvider (for atomic useParams/usePathname),
+    // TimberNuqsAdapter (for nuqs context), and TransitionRoot (for
+    // transition-based rendering during client navigation).
+    //
+    // TransitionRoot holds the element in React state and updates via
+    // startTransition, so React keeps old UI visible while new Suspense
+    // boundaries resolve during navigation. See design/05-streaming.md.
+    const navState = getNavigationState();
+    const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
+    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+    const rootElement = createElement(TransitionRoot, { initial: wrapped });
+    _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
       // (wrapStreamWithErrorHandling closes the stream cleanly after
@@ -303,14 +335,14 @@ function bootstrap(runtimeConfig: typeof config): void {
     // The initial SSR HTML remains as-is; the first client navigation will
     // replace it with a React-managed tree.
     initRouter();
-    reactRoot = createRoot(document);
+    _reactRoot = createRoot(document);
   }
   // ── Router initialization (hoisted above hydrateRoot) ────────────────
   // Extracted into a function so both the hydration and createRoot paths
   // can call it. Must run before hydrateRoot so useRouter() works during
-  // the initial render. The renderRoot dep reads `reactRoot` via closure,
-  // so it's fine that reactRoot is assigned after this runs.
+  // the initial render. renderRoot uses transitionRender which is set
+  // by the TransitionRoot component during hydration.
   function initRouter(): void {
     const deps: RouterDeps = {
       fetch: (url, init) => window.fetch(url, init),
@@ -335,14 +367,28 @@ function bootstrap(runtimeConfig: typeof config): void {
         return createFromFetch(fetchPromise);
       },
-      // Render decoded RSC tree into the hydrated React root.
-      // Wrap with TimberNuqsAdapter to maintain nuqs context across navigations.
-      // Reads `reactRoot` from the outer closure — assigned after hydrateRoot().
+      // Render decoded RSC tree via TransitionRoot's state-based mechanism.
+      // Wraps with NavigationProvider (for atomic useParams/usePathname updates)
+      // and TimberNuqsAdapter (for nuqs context).
+      //
+      // The router calls setNavigationState() before renderRoot(), so
+      // getNavigationState() returns the new params/pathname. By wrapping
+      // the element in NavigationProvider here, the context value and the
+      // RSC tree are passed to startTransition(() => setState()) in the same
+      // call — making the update atomic. Preserved layout components that call
+      // useParams() or usePathname() re-render in the same pass as the
+      // new tree, preventing the dual-active-state flash.
+      //
+      // Using transitionRender instead of reactRoot.render() enables
+      // client-side Suspense deferral: React keeps the old committed tree
+      // visible while new Suspense boundaries in the navigation resolve.
+      // This is the client-side equivalent of deferSuspenseFor on the server.
+      // See design/05-streaming.md.
       renderRoot: (element: unknown) => {
-        if (reactRoot) {
-          const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
-          reactRoot.render(wrapped);
-        }
+        const navState = getNavigationState();
+        const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
+        const wrapped = createElement(TimberNuqsAdapter, null, withNav);
+        transitionRender(wrapped);
       },
       // Schedule a callback after the next paint so scroll operations
@@ -384,11 +430,16 @@ function bootstrap(runtimeConfig: typeof config): void {
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
-  // Populate useParams() from server-embedded route params.
-  // Without this, useParams() returns {} until the first client navigation.
-  const timberParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (timberParams && typeof timberParams === 'object') {
-    setCurrentParams(timberParams as Record<string, string | string[]>);
+  // Note: __timber_params is read before hydrateRoot (see above) so that
+  // NavigationProvider has correct values during hydration. If the hydration
+  // path was skipped (no RSC payload), populate the fallback here.
+  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
+  if (lateTimberParams && typeof lateTimberParams === 'object') {
+    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
+    setNavigationState({
+      params: lateTimberParams as Record<string, string | string[]>,
+      pathname: window.location.pathname,
+    });
     delete (self as unknown as Record<string, unknown>).__timber_params;
   }
@@ -481,208 +532,7 @@ function bootstrap(runtimeConfig: typeof config): void {
   }
 }
-// ─── Server Log Replay (Dev Only) ─────────────────────────────────
-/** Payload shape from plugins/dev-logs.ts */
-interface ServerLogPayload {
-  level: 'log' | 'warn' | 'error' | 'debug' | 'info';
-  args: unknown[];
-  location: string | null;
-  timestamp: number;
-}
-/**
- * Deserialize a serialized arg back into a console-friendly value.
- *
- * Handles Error objects (serialized as { __type: 'Error', ... }),
- * Maps, Sets, and passes everything else through.
- */
-function deserializeArg(arg: unknown): unknown {
-  if (arg === '[undefined]') return undefined;
-  if (arg === null || typeof arg !== 'object') return arg;
-  const obj = arg as Record<string, unknown>;
-  if (obj.__type === 'Error') {
-    const err = new Error(obj.message as string);
-    err.name = obj.name as string;
-    if (obj.stack) err.stack = obj.stack as string;
-    return err;
-  }
-  if (obj.__type === 'Map') {
-    return new Map(
-      Object.entries(obj.entries as Record<string, unknown>).map(([k, v]) => [k, deserializeArg(v)])
-    );
-  }
-  if (obj.__type === 'Set') {
-    return new Set((obj.values as unknown[]).map(deserializeArg));
-  }
-  if (Array.isArray(arg)) {
-    return arg.map(deserializeArg);
-  }
-  // Plain object — recurse
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(obj)) {
-    result[key] = deserializeArg(value);
-  }
-  return result;
-}
-/**
- * Set up the HMR listener that replays server console output in the browser.
- *
- * Each message arrives with a log level and serialized args. We prepend
- * a styled "[SERVER]" badge and call the matching console method.
- */
-function setupServerLogReplay(hot: {
-  on(event: string, cb: (...args: unknown[]) => void): void;
-}): void {
-  /** CSS styles for the [SERVER] badge in browser console. */
-  const BADGE_STYLES: Record<string, string> = {
-    log: 'background: #0070f3; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
-    info: 'background: #0070f3; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
-    warn: 'background: #f5a623; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
-    error:
-      'background: #e00; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
-    debug:
-      'background: #666; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
-  };
-  hot.on('timber:server-log', (data: unknown) => {
-    const payload = data as ServerLogPayload;
-    const level = payload.level;
-    const fn = console[level] ?? console.log;
-    const args = payload.args.map(deserializeArg);
-    const badge = `%cSERVER`;
-    const style = BADGE_STYLES[level] ?? BADGE_STYLES.log;
-    const locationSuffix = payload.location ? ` (${payload.location})` : '';
-    fn.call(console, badge, style, ...args, locationSuffix ? `\n  → ${payload.location}` : '');
-  });
-}
-// ─── Client Error Forwarding (Dev Only) ──────────────────────────
-/**
- * Set up global error handlers that forward uncaught client-side
- * errors to the dev server via Vite's HMR channel.
- *
- * The server receives 'timber:client-error' events, and echoes them
- * back as Vite '{ type: "error" }' payloads to trigger the overlay.
- */
-function setupClientErrorForwarding(hot: { send(event: string, data: unknown): void }): void {
-  window.addEventListener('error', (event: ErrorEvent) => {
-    // Skip errors without useful information
-    if (!event.error && !event.message) return;
-    // Skip errors during page unload — these are abort-related, not application errors
-    if (isPageUnloading()) return;
-    const error = event.error;
-    hot.send('timber:client-error', {
-      message: error?.message ?? event.message,
-      stack: error?.stack ?? '',
-      componentStack: error?.componentStack ?? null,
-    });
-  });
-  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
-    const reason = event.reason;
-    if (!reason) return;
-    // Skip rejections during page unload — aborted fetches/streams cause these
-    if (isPageUnloading()) return;
-    const message = reason instanceof Error ? reason.message : String(reason);
-    const stack = reason instanceof Error ? (reason.stack ?? '') : '';
-    hot.send('timber:client-error', {
-      message,
-      stack,
-      componentStack: null,
-    });
-  });
-}
-// ─── Link Click Interception ─────────────────────────────────────
-/**
- * Handle click events on timber links. Intercepts clicks on <a> elements
- * marked with data-timber-link and triggers SPA navigation instead of
- * a full page load.
- *
- * Passes through to default browser behavior when:
- * - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
- * - The click is not the primary button
- * - The link has a target attribute (e.g., target="_blank")
- * - The link has a download attribute
- */
-function handleLinkClick(event: MouseEvent, router: RouterInstance): void {
-  // Only intercept primary clicks without modifier keys
-  if (event.button !== 0) return;
-  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-  if (event.defaultPrevented) return;
-  // Find the closest <a> ancestor with data-timber-link
-  const anchor = (event.target as Element).closest?.(
-    'a[data-timber-link]'
-  ) as HTMLAnchorElement | null;
-  if (!anchor) return;
-  // Don't intercept links that should open externally
-  if (anchor.target && anchor.target !== '_self') return;
-  if (anchor.hasAttribute('download')) return;
-  const href = anchor.getAttribute('href');
-  if (!href) return;
-  // Prevent default navigation
-  event.preventDefault();
-  // Call onNavigate if registered on this anchor (via LinkNavigateInterceptor).
-  // If the handler calls preventDefault(), skip the default SPA navigation —
-  // the caller is responsible for navigating (e.g. via router.push()).
-  const onNavigate = anchor[ON_NAVIGATE_KEY];
-  if (onNavigate) {
-    let prevented = false;
-    onNavigate({
-      preventDefault: () => {
-        prevented = true;
-      },
-    });
-    if (prevented) return;
-  }
-  // Check scroll preference from data attribute
-  const scroll = anchor.getAttribute('data-timber-scroll') !== 'false';
-  // Trigger SPA navigation
-  void router.navigate(href, { scroll });
-}
-// ─── Prefetch on Hover ───────────────────────────────────────────
-/**
- * Handle mouseenter events on prefetch-enabled links. When the user
- * hovers over <a data-timber-prefetch>, the RSC payload is fetched
- * and cached for near-instant navigation.
- *
- * See design/19-client-navigation.md §"Prefetch Cache"
- */
-function handleLinkHover(event: MouseEvent, router: RouterInstance): void {
-  const anchor = (event.target as Element).closest?.(
-    'a[data-timber-prefetch]'
-  ) as HTMLAnchorElement | null;
-  if (!anchor) return;
-  const href = anchor.getAttribute('href');
-  if (!href) return;
-  router.prefetch(href);
-}
 bootstrap(config);

package/src/client/browser-links.ts ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * Link click interception and hover prefetch for SPA navigation.
+ *
+ * Handles click events on <a data-timber-link> and mouseenter events
+ * on <a data-timber-prefetch> for client-side navigation.
+ *
+ * Extracted from browser-entry.ts to keep files under 500 lines.
+ *
+ * See design/19-client-navigation.md
+ */
+import type { RouterInstance } from '@timber-js/app/client';
+import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
+// ─── Link Click Interception ─────────────────────────────────────
+/**
+ * Handle click events on timber links. Intercepts clicks on <a> elements
+ * marked with data-timber-link and triggers SPA navigation instead of
+ * a full page load.
+ *
+ * Passes through to default browser behavior when:
+ * - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
+ * - The click is not the primary button
+ * - The link has a target attribute (e.g., target="_blank")
+ * - The link has a download attribute
+ */
+export function handleLinkClick(event: MouseEvent, router: RouterInstance): void {
+  // Only intercept primary clicks without modifier keys
+  if (event.button !== 0) return;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+  if (event.defaultPrevented) return;
+  // Find the closest <a> ancestor with data-timber-link
+  const anchor = (event.target as Element).closest?.(
+    'a[data-timber-link]'
+  ) as HTMLAnchorElement | null;
+  if (!anchor) return;
+  // Don't intercept links that should open externally
+  if (anchor.target && anchor.target !== '_self') return;
+  if (anchor.hasAttribute('download')) return;
+  const href = anchor.getAttribute('href');
+  if (!href) return;
+  // Prevent default navigation
+  event.preventDefault();
+  // Call onNavigate if registered on this anchor (via LinkNavigateInterceptor).
+  // If the handler calls preventDefault(), skip the default SPA navigation —
+  // the caller is responsible for navigating (e.g. via router.push()).
+  const onNavigate = anchor[ON_NAVIGATE_KEY];
+  if (onNavigate) {
+    let prevented = false;
+    onNavigate({
+      preventDefault: () => {
+        prevented = true;
+      },
+    });
+    if (prevented) return;
+  }
+  // Check scroll preference from data attribute
+  const scroll = anchor.getAttribute('data-timber-scroll') !== 'false';
+  // Trigger SPA navigation
+  void router.navigate(href, { scroll });
+}
+// ─── Prefetch on Hover ───────────────────────────────────────────
+/**
+ * Handle mouseenter events on prefetch-enabled links. When the user
+ * hovers over <a data-timber-prefetch>, the RSC payload is fetched
+ * and cached for near-instant navigation.
+ *
+ * See design/19-client-navigation.md §"Prefetch Cache"
+ */
+export function handleLinkHover(event: MouseEvent, router: RouterInstance): void {
+  const anchor = (event.target as Element).closest?.(
+    'a[data-timber-prefetch]'
+  ) as HTMLAnchorElement | null;
+  if (!anchor) return;
+  const href = anchor.getAttribute('href');
+  if (!href) return;
+  router.prefetch(href);
+}

package/src/client/index.ts CHANGED Viewed

@@ -44,6 +44,10 @@ export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from '.
 // Params
 export { useParams, setCurrentParams } from './use-params';
+// Navigation context (framework-internal, used by browser-entry for atomic updates)
+export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
+export type { NavigationState } from './navigation-context';
 // Query states (URL-synced search params)
 export { useQueryStates, bindUseQueryStates } from './use-query-states';

package/src/client/navigation-context.ts ADDED Viewed

@@ -0,0 +1,118 @@
+/**
+ * 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 useParams() 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.
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import React, { createElement, type ReactNode } from 'react';
+// ---------------------------------------------------------------------------
+// Context type
+// ---------------------------------------------------------------------------
+export interface NavigationState {
+  params: Record<string, string | string[]>;
+  pathname: string;
+}
+// ---------------------------------------------------------------------------
+// Lazy context initialization
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+let _context: React.Context<NavigationState | null> | undefined;
+function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
+  if (_context !== undefined) return _context;
+  // createContext may not exist in the RSC environment
+  if (typeof React.createContext === 'function') {
+    _context = React.createContext<NavigationState | null>(null);
+  }
+  return _context;
+}
+/**
+ * Read the navigation context. Returns null during SSR (no provider)
+ * or in the RSC environment (no context available).
+ * Internal — used by useParams() and usePathname().
+ */
+export function useNavigationContext(): NavigationState | null {
+  const ctx = getOrCreateContext();
+  if (!ctx) return null;
+  // useContext may not exist in the RSC environment — caller wraps in try/catch
+  if (typeof React.useContext !== 'function') return null;
+  return React.useContext(ctx);
+}
+// ---------------------------------------------------------------------------
+// Provider component
+// ---------------------------------------------------------------------------
+export interface NavigationProviderProps {
+  value: NavigationState;
+  children?: ReactNode;
+}
+/**
+ * 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.
+ */
+export function NavigationProvider({ value, children }: NavigationProviderProps): React.ReactElement {
+  const ctx = getOrCreateContext();
+  if (!ctx) {
+    // RSC environment — no context available. Return children as-is.
+    return children as React.ReactElement;
+  }
+  return createElement(ctx.Provider, { value }, children);
+}
+// ---------------------------------------------------------------------------
+// Module-level state for renderRoot to read
+// ---------------------------------------------------------------------------
+/**
+ * Module-level navigation state. Updated by the router before calling
+ * renderRoot(). The renderRoot callback reads this to create the
+ * NavigationProvider with the correct values.
+ *
+ * This is NOT used by hooks directly — hooks read from React context.
+ * This exists only as a communication channel between the router
+ * (which knows the new nav state) and renderRoot (which wraps the element).
+ */
+let _currentNavState: NavigationState = { params: {}, pathname: '/' };
+export function setNavigationState(state: NavigationState): void {
+  _currentNavState = state;
+}
+export function getNavigationState(): NavigationState {
+  return _currentNavState;
+}