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

@timber-js/app 0.1.24 → 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 (47) hide show

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/index.d.ts +1 -1
package/dist/client/index.d.ts.map +1 -1
package/dist/client/index.js +46 -20
package/dist/client/index.js.map +1 -1
package/dist/client/navigation-context.d.ts +10 -8
package/dist/client/navigation-context.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-router.d.ts +14 -0
package/dist/client/use-router.d.ts.map +1 -1
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 +32 -222
package/src/client/browser-links.ts +90 -0
package/src/client/index.ts +1 -1
package/src/client/navigation-context.ts +39 -9
package/src/client/transition-root.tsx +86 -0
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,8 +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 ──────────────────────────────────────
@@ -179,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.
@@ -272,8 +274,8 @@ 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 ───────────────────
@@ -298,12 +300,18 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
-    // Wrap with NavigationProvider (for atomic useParams/usePathname) and
-    // TimberNuqsAdapter (for nuqs context).
+    // 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);
-    reactRoot = hydrateRoot(document, wrapped, {
+    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
@@ -327,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),
@@ -359,25 +367,28 @@ function bootstrap(runtimeConfig: typeof config): void {
         return createFromFetch(fetchPromise);
       },
-      // Render decoded RSC tree into the hydrated React root.
+      // Render decoded RSC tree via TransitionRoot's state-based mechanism.
       // Wraps with NavigationProvider (for atomic useParams/usePathname updates)
-      // and TimberNuqsAdapter (for nuqs context). Reads `reactRoot` and
-      // navigation state from closures — both set before this callback fires.
+      // 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 reactRoot.render() in the same call —
-      // making the update atomic. Preserved layout components that call
+      // 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 navState = getNavigationState();
-          const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
-          const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-          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
@@ -521,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

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

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

@@ -17,13 +17,19 @@
  * During SSR, no NavigationProvider is mounted. Hooks fall back to
  * the ALS-backed getSsrData() for per-request isolation.
  *
- * See design/19-client-navigation.md §"Navigation Flow"
+ * 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 { createContext, useContext, createElement, type ReactNode } from 'react';
+import React, { createElement, type ReactNode } from 'react';
 // ---------------------------------------------------------------------------
-// Context type and creation
+// Context type
 // ---------------------------------------------------------------------------
 export interface NavigationState {
@@ -31,18 +37,37 @@ export interface NavigationState {
   pathname: string;
 }
+// ---------------------------------------------------------------------------
+// Lazy context initialization
+// ---------------------------------------------------------------------------
 /**
- * The context value is null when no provider is mounted (SSR).
- * On the client, NavigationProvider always wraps the tree.
+ * 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.
  */
-export const NavigationContext = createContext<NavigationState | null>(null);
+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).
+ * 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 {
-  return useContext(NavigationContext);
+  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);
 }
 // ---------------------------------------------------------------------------
@@ -61,7 +86,12 @@ export interface NavigationProviderProps {
  * so that navigation state updates atomically with the tree render.
  */
 export function NavigationProvider({ value, children }: NavigationProviderProps): React.ReactElement {
-  return createElement(NavigationContext.Provider, { value }, children);
+  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);
 }
 // ---------------------------------------------------------------------------

package/src/client/transition-root.tsx ADDED Viewed

@@ -0,0 +1,86 @@
+/**
+ * TransitionRoot — Wrapper component for transition-based rendering.
+ *
+ * Solves the "new boundary has no old content" problem for client-side
+ * navigation. When React renders a completely new Suspense boundary via
+ * root.render(), it shows the fallback immediately — root.render() is
+ * always an urgent update regardless of startTransition.
+ *
+ * TransitionRoot holds the current element in React state. Navigation
+ * updates call startTransition(() => setState(newElement)), which IS
+ * a transition update. React keeps the old committed tree visible while
+ * any new Suspense boundaries in the transition resolve.
+ *
+ * This is the client-side equivalent of deferSuspenseFor on the server:
+ * the old content stays visible until the new content is ready, avoiding
+ * flash-of-fallback during fast navigations.
+ *
+ * See design/05-streaming.md §"deferSuspenseFor"
+ */
+import { useState, startTransition, type ReactNode } from 'react';
+// ─── Module-level render function ────────────────────────────────
+/**
+ * Module-level reference to the state setter wrapped in startTransition.
+ * Set during TransitionRoot's render. This is safe because there is
+ * exactly one TransitionRoot per application (the document root).
+ */
+let _transitionRender: ((element: ReactNode) => void) | null = null;
+// ─── Component ───────────────────────────────────────────────────
+/**
+ * Root wrapper component that enables transition-based rendering.
+ *
+ * Renders no DOM elements — returns the current element directly.
+ * This means the DOM tree matches the server-rendered HTML during
+ * hydration (TransitionRoot is invisible to the DOM).
+ *
+ * Usage in browser-entry.ts:
+ *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
+ *   reactRoot = hydrateRoot(document, rootEl);
+ *
+ * Subsequent navigations:
+ *   transitionRender(newWrappedElement);
+ */
+export function TransitionRoot({ initial }: { initial: ReactNode }): ReactNode {
+  const [element, setElement] = useState<ReactNode>(initial);
+  // Update the module-level ref on every render so it always points
+  // to the current component instance's setState.
+  _transitionRender = (newElement: ReactNode) => {
+    startTransition(() => {
+      setElement(newElement);
+    });
+  };
+  return element;
+}
+// ─── Public API ──────────────────────────────────────────────────
+/**
+ * Trigger a transition render. React keeps the old committed tree
+ * visible while any new Suspense boundaries in the update resolve.
+ *
+ * This is the function called by the router's renderRoot callback
+ * instead of reactRoot.render() directly.
+ *
+ * Falls back to no-op if TransitionRoot hasn't mounted yet (shouldn't
+ * happen in practice — TransitionRoot mounts during hydration).
+ */
+export function transitionRender(element: ReactNode): void {
+  if (_transitionRender) {
+    _transitionRender(element);
+  }
+}
+/**
+ * Check if the TransitionRoot is mounted and ready for renders.
+ * Used by browser-entry.ts to guard against renders before hydration.
+ */
+export function isTransitionRootReady(): boolean {
+  return _transitionRender !== null;
+}

package/src/client/use-router.ts CHANGED Viewed

@@ -7,9 +7,22 @@
  *
  * 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
  */
-import { startTransition } from 'react';
 import { getRouterOrNull } from './router-ref.js';
 export interface AppRouterInstance {
@@ -54,14 +67,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      // Wrap in startTransition so React 19 tracks the async navigation.
-      // React 19's startTransition accepts async callbacks — it keeps
-      // isPending=true until the returned promise resolves. This means
-      // useTransition's isPending reflects the full RSC fetch + render
-      // lifecycle when wrapping router.push() in startTransition.
-      startTransition(async () => {
-        await router.navigate(href, { scroll: options?.scroll });
-      });
+      void router.navigate(href, { scroll: options?.scroll });
     },
     replace(href: string, options?: { scroll?: boolean }) {
       const router = getRouterOrNull();
@@ -71,9 +77,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      startTransition(async () => {
-        await router.navigate(href, { scroll: options?.scroll, replace: true });
-      });
+      void router.navigate(href, { scroll: options?.scroll, replace: true });
     },
     refresh() {
       const router = getRouterOrNull();
@@ -83,9 +87,7 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      startTransition(async () => {
-        await router.refresh();
-      });
+      void router.refresh();
     },
     back() {
       if (typeof window !== 'undefined') window.history.back();