@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/client/head.ts

@@ -1,61 +0,0 @@
-// Client-side head element updates for SPA navigation.
-//
-// On RSC payload responses, the server sends resolved HeadElement[] via the
-// X-Timber-Head response header. This module applies those elements to the
-// DOM so document.title and <meta> tags stay current after navigation.
-//
-// See design/16-metadata.md
-
-// ─── Types ───────────────────────────────────────────────────────
-
-/** Marker attribute for timber-managed head elements (cleanup on next navigation). */
-const TIMBER_ATTR = 'data-timber-head';
-
-/** A rendered head element descriptor (matches server-side HeadElement from metadata.ts). */
-export interface HeadElement {
-  tag: 'title' | 'meta' | 'link';
-  content?: string;
-  attrs?: Record<string, string>;
-}
-
-// ─── Apply Head Elements ─────────────────────────────────────────
-
-/**
- * Apply resolved head elements to the DOM.
- *
- * - Sets document.title for <title> elements
- * - Creates <meta> and <link> tags with a data-timber-head marker
- * - Removes previous timber-managed tags to prevent accumulation
- * - Replaces existing SSR-rendered tags with the same name/property
- */
-export function applyHeadElements(elements: HeadElement[]): void {
-  // Remove previous timber-managed meta/link tags
-  document.head.querySelectorAll(`[${TIMBER_ATTR}]`).forEach((el) => el.remove());
-
-  for (const el of elements) {
-    if (el.tag === 'title' && el.content !== undefined) {
-      document.title = el.content;
-      continue;
-    }
-
-    if (!el.attrs) continue;
-
-    // For meta: remove existing tag with same name/property to avoid duplicates from SSR
-    if (el.tag === 'meta') {
-      const key = el.attrs.name || el.attrs.property;
-      if (key) {
-        const existing = document.head.querySelector(
-          `meta[name="${key}"], meta[property="${key}"]`
-        );
-        if (existing) existing.remove();
-      }
-    }
-
-    const node = document.createElement(el.tag);
-    node.setAttribute(TIMBER_ATTR, '');
-    for (const [k, v] of Object.entries(el.attrs)) {
-      node.setAttribute(k, v);
-    }
-    document.head.appendChild(node);
-  }
-}

package/src/client/link-status-provider.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-// LinkStatusProvider — client component that provides per-link pending status
-// via React context. Used inside <Link> to power useLinkStatus().
-//
-// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
-// The pending URL is set as an URGENT update at navigation start (shows
-// immediately) and cleared inside startTransition when the new tree commits
-// (atomic with params/pathname). This eliminates both:
-// 1. The delay before showing the spinner (urgent update, not deferred)
-// 2. The gap between spinner disappearing and active state updating (same commit)
-
-import type { ReactNode } from 'react';
-import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { usePendingNavigationUrl } from './navigation-context.js';
-
-const NOT_PENDING: LinkStatus = { pending: false };
-const IS_PENDING: LinkStatus = { pending: true };
-
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
- * just a context provider around children.
- */
-export function LinkStatusProvider({ href, children }: { href: string; children?: ReactNode }) {
-  const pendingUrl = usePendingNavigationUrl();
-  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
-
-  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
-}

package/src/client/segment-merger.ts

@@ -1,339 +0,0 @@
-/**
- * Segment Merger — client-side tree merging for partial RSC payloads.
- *
- * When the server skips rendering sync layouts (because the client already
- * has them cached), the RSC payload is missing outer segment wrappers.
- * This module reconstructs the full element tree by splicing the partial
- * payload into cached segment subtrees.
- *
- * The approach:
- * 1. After each full RSC payload render, walk the decoded element tree
- *    and cache each segment's subtree (identified by SegmentProvider boundaries)
- * 2. When a partial payload arrives, wrap it with cached segment elements
- *    using React.cloneElement to preserve component identity
- *
- * React.cloneElement preserves the element's `type` — React sees the same
- * component at the same tree position and reconciles (preserving state)
- * rather than remounting. This is how layout state survives navigations.
- *
- * Design docs: 19-client-navigation.md §"Navigation Reconciliation"
- * Security: access.ts runs on the server regardless of skipping — this
- *           is a performance optimization only. See 13-security.md.
- */
-
-import { cloneElement, isValidElement, type ReactElement, type ReactNode } from 'react';
-
-// ─── Types ───────────────────────────────────────────────────────
-
-/**
- * A cached segment entry. Stores the full subtree rooted at a SegmentProvider
- * and the path through the tree to the next SegmentProvider (or leaf).
- */
-export interface CachedSegmentEntry {
-  /** The segment's URL path (e.g., "/", "/dashboard") */
-  segmentPath: string;
-  /** The SegmentProvider element for this segment */
-  element: ReactElement;
-  /**
-   * Whether this segment's cached element contains a nested SegmentProvider.
-   * Only segments with inner SegmentProviders are safe to skip — the merger
-   * can only replace inner SegmentProviders, not pages embedded in layout output.
-   * Used by the state tree serialization to exclude non-mergeable segments.
-   */
-  hasMergeableChild: boolean;
-}
-
-// ─── Segment Element Cache ───────────────────────────────────────
-
-/**
- * Cache of React element subtrees per segment path.
- * Updated after each navigation with the full decoded RSC element tree.
- */
-export class SegmentElementCache {
-  private entries = new Map<string, CachedSegmentEntry>();
-
-  get(segmentPath: string): CachedSegmentEntry | undefined {
-    return this.entries.get(segmentPath);
-  }
-
-  set(segmentPath: string, entry: CachedSegmentEntry): void {
-    this.entries.set(segmentPath, entry);
-  }
-
-  has(segmentPath: string): boolean {
-    return this.entries.has(segmentPath);
-  }
-
-  clear(): void {
-    this.entries.clear();
-  }
-
-  get size(): number {
-    return this.entries.size;
-  }
-
-  /**
-   * Get the set of segment paths that are safe for the server to skip.
-   * Only segments with an inner SegmentProvider (hasMergeableChild) are
-   * included — the merger can only replace inner SegmentProviders, not
-   * pages embedded in layout output. Used to filter the state tree.
-   *
-   * Returns an empty set if the element cache is empty (no elements
-   * cached yet). This is the safe default — an empty set means no
-   * segments pass the filter, so the state tree is empty and the server
-   * does a full render. The element cache is populated lazily after the
-   * first SPA navigation (RSC-decoded elements from hydration are
-   * thenables that can't be walked until React resolves them).
-   */
-  getMergeablePaths(): Set<string> {
-    const paths = new Set<string>();
-    for (const [, entry] of this.entries) {
-      if (entry.hasMergeableChild) {
-        paths.add(entry.segmentPath);
-      }
-    }
-    return paths;
-  }
-}
-
-// ─── SegmentProvider Detection ───────────────────────────────────
-
-/**
- * Check if a React element is a SegmentProvider by looking for the
- * `segments` prop (an array of path segments). This is the only
- * component that receives this prop shape.
- */
-export function isSegmentProvider(element: unknown): element is ReactElement {
-  if (!isValidElement(element)) return false;
-  const props = element.props as Record<string, unknown>;
-  return Array.isArray(props.segments);
-}
-
-/**
- * Extract the segment path from a SegmentProvider element.
- *
- * Uses the `segmentId` prop if available (set by the server for route groups
- * to distinguish siblings that share the same urlPath). Falls back to
- * reconstructing from the `segments` array prop.
- */
-export function getSegmentPath(element: ReactElement): string {
-  const props = element.props as { segments: string[]; segmentId?: string };
-  // segmentId is the authoritative key — includes group name for route groups
-  if (props.segmentId) return props.segmentId;
-  const filtered = props.segments.filter(Boolean);
-  return filtered.length === 0 ? '/' : '/' + filtered.join('/');
-}
-
-// ─── Tree Walking ────────────────────────────────────────────────
-
-/**
- * Walk a React element tree and extract all SegmentProvider boundaries.
- * Returns an ordered list of segment entries from outermost to innermost.
- *
- * This only finds SegmentProviders along the main children path — it does
- * not descend into parallel routes/slots (those are separate subtrees).
- */
-export function extractSegments(element: unknown): CachedSegmentEntry[] {
-  const segments: CachedSegmentEntry[] = [];
-  walkForSegments(element, segments);
-  // Compute hasMergeableChild: a segment is mergeable if there's another
-  // SegmentProvider nested below it. The segments list is ordered outermost
-  // to innermost, so each segment's child is the next entry.
-  for (let i = 0; i < segments.length; i++) {
-    segments[i].hasMergeableChild = i < segments.length - 1;
-  }
-  return segments;
-}
-
-function walkForSegments(node: unknown, out: CachedSegmentEntry[]): void {
-  if (!isValidElement(node)) return;
-
-  // Use a local binding to avoid TypeScript narrowing issues with
-  // isSegmentProvider's type predicate on the same variable.
-  const el: ReactElement = node as ReactElement;
-  const props = el.props as Record<string, unknown>;
-
-  if (isSegmentProvider(node)) {
-    out.push({
-      segmentPath: getSegmentPath(el),
-      element: el,
-      hasMergeableChild: false, // computed after collection in extractSegments
-    });
-    // Continue walking into children to find nested segments
-    walkChildren(props.children as ReactNode, out);
-    return;
-  }
-
-  // Not a SegmentProvider — walk children looking for one
-  walkChildren(props.children as ReactNode, out);
-}
-
-function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
-  if (children == null) return;
-
-  if (Array.isArray(children)) {
-    for (const child of children) {
-      walkForSegments(child, out);
-    }
-  } else {
-    walkForSegments(children, out);
-  }
-}
-
-// ─── Cache Population ────────────────────────────────────────────
-
-/**
- * Cache all segment subtrees from a fully-rendered RSC element tree.
- * Call this after every full RSC payload render (navigate, refresh, hydration).
- */
-export function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void {
-  const segments = extractSegments(element);
-  for (const entry of segments) {
-    cache.set(entry.segmentPath, entry);
-  }
-}
-
-// ─── Tree Merging ────────────────────────────────────────────────
-
-/**
- * Find a SegmentProvider nested in the children of a React element.
- * Returns the path of elements from the given element down to the
- * SegmentProvider, enabling reconstruction via cloneElement.
- *
- * The path is an array of [element, childIndex] pairs. childIndex is -1
- * for single-child (non-array) props.children.
- */
-type TreePath = Array<{ element: ReactElement; childIndex: number }>;
-
-function findSegmentProviderPath(node: ReactElement, targetPath?: string): TreePath | null {
-  const children = (node.props as { children?: ReactNode }).children;
-  if (children == null) return null;
-
-  if (Array.isArray(children)) {
-    for (let i = 0; i < children.length; i++) {
-      const child = children[i];
-      if (!isValidElement(child)) continue;
-
-      if (isSegmentProvider(child)) {
-        if (!targetPath || getSegmentPath(child) === targetPath) {
-          return [{ element: node, childIndex: i }];
-        }
-      }
-
-      const deeper = findSegmentProviderPath(child, targetPath);
-      if (deeper) {
-        return [{ element: node, childIndex: i }, ...deeper];
-      }
-    }
-  } else if (isValidElement(children)) {
-    if (isSegmentProvider(children)) {
-      if (!targetPath || getSegmentPath(children) === targetPath) {
-        return [{ element: node, childIndex: -1 }];
-      }
-    }
-
-    const deeper = findSegmentProviderPath(children, targetPath);
-    if (deeper) {
-      return [{ element: node, childIndex: -1 }, ...deeper];
-    }
-  }
-
-  return null;
-}
-
-/**
- * Replace a nested SegmentProvider within a cached element tree with
- * new content. Uses cloneElement along the path to produce a new tree
- * with preserved component identity at every level except the replaced node.
- *
- * @param cachedElement The cached SegmentProvider element for this segment
- * @param newInnerContent The new React element to splice in at the inner segment position
- * @param innerSegmentPath The path of the inner segment to replace (optional — replaces first found)
- * @returns New element tree with the inner segment replaced
- */
-export function replaceInnerSegment(
-  cachedElement: ReactElement,
-  newInnerContent: ReactNode,
-  innerSegmentPath?: string
-): ReactElement {
-  const path = findSegmentProviderPath(cachedElement, innerSegmentPath);
-
-  if (!path || path.length === 0) {
-    // No inner SegmentProvider found — this segment's cached element
-    // wraps a page directly (no child layout with a SegmentProvider).
-    // We CANNOT safely replace the page because it's embedded deep in
-    // the layout's server-rendered output tree and we don't know its
-    // position. Return the cached element unchanged as a safety fallback.
-    //
-    // The server should not skip segments without a child layout below
-    // them (enforced by hasRenderedLayoutBelow in buildRouteElement).
-    // If this codepath is reached, it indicates a server/client mismatch.
-    return cachedElement;
-  }
-
-  // Reconstruct bottom-up: replace the innermost element first, then
-  // clone each ancestor with the updated child.
-  let replacement: ReactNode = newInnerContent;
-
-  for (let i = path.length - 1; i >= 0; i--) {
-    const { element, childIndex } = path[i];
-
-    if (childIndex === -1) {
-      // Single child — replace it
-      replacement = cloneElement(element, {}, replacement);
-    } else {
-      // Array children — replace the specific index
-      const children = (element.props as { children: ReactNode[] }).children;
-      const newChildren = [...children];
-      newChildren[childIndex] = replacement;
-      replacement = cloneElement(element, {}, ...newChildren);
-    }
-  }
-
-  return replacement as ReactElement;
-}
-
-/**
- * Merge a partial RSC payload with cached segment elements.
- *
- * When the server skips segments, the partial payload starts from the
- * first non-skipped segment. This function wraps it with cached elements
- * for the skipped segments, producing a full tree that React can
- * reconcile with the mounted tree (preserving layout state).
- *
- * @param partialPayload The RSC payload element (may be partial)
- * @param skippedSegments Ordered list of segment paths that were skipped (outermost first)
- * @param cache The segment element cache
- * @returns The merged full element tree, or the partial payload if merging isn't possible
- */
-export function mergeSegmentTree(
-  partialPayload: unknown,
-  skippedSegments: string[],
-  cache: SegmentElementCache
-): unknown {
-  if (!isValidElement(partialPayload)) return partialPayload;
-  if (skippedSegments.length === 0) return partialPayload;
-
-  // Build from outermost to innermost: each skipped segment's cached
-  // element wraps the next, with the partial payload at the center.
-  let result: ReactNode = partialPayload;
-
-  // Process from innermost skipped segment to outermost
-  for (let i = skippedSegments.length - 1; i >= 0; i--) {
-    const segmentPath = skippedSegments[i];
-    const cached = cache.get(segmentPath);
-
-    if (!cached) {
-      // No cached element for this segment — can't merge.
-      // This shouldn't happen (server only skips segments the client
-      // has cached), but if it does, return the partial payload as-is.
-      return partialPayload;
-    }
-
-    // Replace the inner content of the cached segment with our current result.
-    // The inner content is either the next SegmentProvider or the page.
-    result = replaceInnerSegment(cached.element, result);
-  }
-
-  return result;
-}

package/src/client/stale-reload.ts

@@ -1,87 +0,0 @@
-/**
- * Stale Client Reference Reload
- *
- * When a new deployment ships updated bundles, clients running stale
- * JavaScript may encounter "Could not find the module" errors during
- * RSC Flight stream decoding. This happens because the RSC payload
- * references module IDs from the new bundle that don't exist in the
- * old client bundle.
- *
- * This module detects these specific errors and triggers a full page
- * reload so the browser fetches the new bundle. A sessionStorage flag
- * guards against infinite reload loops.
- *
- * See: LOCAL-332
- */
-
-const RELOAD_FLAG_KEY = '__timber_stale_reload';
-
-/**
- * Check if an error is a stale client reference error from React's
- * Flight client. These errors have the message pattern:
- *   "Could not find the module \"<id>\""
- *
- * This is thrown by react-server-dom-webpack's client when the RSC
- * payload references a module ID that doesn't exist in the client's
- * module map — typically because the server has been redeployed with
- * new bundle hashes while the client is still running old JavaScript.
- */
-export function isStaleClientReference(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const msg = error.message;
-  return msg.includes('Could not find the module') || msg.includes('client reference not found');
-}
-
-/**
- * Trigger a full page reload to pick up new bundles.
- *
- * Sets a sessionStorage flag before reloading. If the flag is already
- * set (meaning we already reloaded once for this reason), we don't
- * reload again — this prevents infinite reload loops if the error
- * persists after reload (e.g., a genuine bug rather than a stale bundle).
- *
- * @returns true if a reload was triggered, false if suppressed (loop guard)
- */
-export function triggerStaleReload(): boolean {
-  try {
-    // Check if we already reloaded — prevent infinite loop
-    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
-      console.warn(
-        '[timber] Stale client reference detected again after reload. ' +
-          'Not reloading to prevent infinite loop. ' +
-          'This may indicate a deployment issue — try a hard refresh.'
-      );
-      return false;
-    }
-
-    // Set the flag before reloading
-    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');
-
-    console.warn(
-      '[timber] Stale client reference detected — the server has been ' +
-        'redeployed with new bundles. Reloading to pick up the new version.'
-    );
-
-    window.location.reload();
-    return true;
-  } catch {
-    // sessionStorage may be unavailable (private browsing, storage full, etc.)
-    // Fall back to reloading without loop protection
-    console.warn('[timber] Stale client reference detected. Reloading page.');
-    window.location.reload();
-    return true;
-  }
-}
-
-/**
- * Clear the stale reload flag. Called on successful bootstrap to reset
- * the loop guard — if the page loaded successfully, the next stale
- * reference error should trigger a fresh reload attempt.
- */
-export function clearStaleReloadFlag(): void {
-  try {
-    sessionStorage.removeItem(RELOAD_FLAG_KEY);
-  } catch {
-    // sessionStorage unavailable — nothing to clear
-  }
-}

package/src/client/transition-root.tsx

@@ -1,166 +0,0 @@
-/**
- * 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.
- *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
- *
- * See design/05-streaming.md §"deferSuspenseFor"
- * See design/19-client-navigation.md §"NavigationContext"
- */
-
-import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
-import { PendingNavigationProvider } from './navigation-context.js';
-import { TopLoader, type TopLoaderConfig } from './top-loader.js';
-
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- * Wraps a full navigation (fetch + render) in a single startTransition
- * with useOptimistic for the pending URL.
- */
-let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
-  | null = null;
-
-// ─── Component ───────────────────────────────────────────────────
-
-/**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
- *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
- *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
- */
-export function TransitionRoot({
-  initial,
-  topLoaderConfig,
-}: {
-  initial: ReactNode;
-  topLoaderConfig?: TopLoaderConfig;
-}): ReactNode {
-  const [element, setElement] = useState<ReactNode>(initial);
-  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
-  const [, startTransition] = useTransition();
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setElement(newElement);
-    });
-  };
-
-  // Full navigation transition.
-  // setPendingUrl(url) is an URGENT update — React commits it before the next
-  // paint, so the pending spinner appears immediately when navigation starts.
-  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)
-  // are deferred. When the transition commits, the new tree and pendingUrl=null
-  // both apply in the same React commit — making the pending→active transition
-  // atomic (no frame where pending is false but the old tree is still visible).
-  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately
-    setPendingUrl(url);
-
-    return new Promise<void>((resolve, reject) => {
-      startTransition(async () => {
-        try {
-          const newElement = await perform();
-          setElement(newElement);
-          // Clear pending inside the transition — commits atomically with new tree
-          setPendingUrl(null);
-          resolve();
-        } catch (err) {
-          // Clear pending on error too
-          setPendingUrl(null);
-          reject(err);
-        }
-      });
-    });
-  };
-
-  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.
-  // The TopLoader reads pendingUrl from context to show/hide the progress bar.
-  // It is rendered only when not explicitly disabled via config.
-  const showTopLoader = topLoaderConfig?.enabled !== false;
-  const children = showTopLoader
-    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)
-    : element;
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (useOptimistic urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  pendingUrl: string,
-  perform: () => Promise<ReactNode>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(pendingUrl, perform);
-  }
-  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
-  return perform().then(() => {});
-}
-
-/**
- * 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;
-}