@timber-js/app 0.2.0-alpha.197 → 0.2.0-alpha.199

package/src/client/error-boundary.tsx

@@ -18,16 +18,31 @@
  * See design/10-error-handling.md §"Status-Code Files"
  */
 
-import { Component, createElement, type ReactNode } from 'react';
+import { Component, createContext, createElement, useContext, type ReactNode } from 'react';
 import { getSsrData } from './ssr-data.ts';
 import { getRouterOrNull } from './router-ref.ts';
 import { markStaleFromError } from './stale-client.ts';
+import { StatusPageMarker } from './status-page-marker.tsx';
+import { leaveSpa } from './router-effects.ts';
 // Page unload detection: when the page is being torn down, error boundaries
 // suppress activation — the error is from the aborted connection, not the
 // application. unload-guard.ts is the single owner of that state; this module
 // used to keep its own copy, which drifted (TIM-1260).
 import { isPageUnloading } from './unload-guard.ts';
 
+// ─── Ancestry Context ────────────────────────────────────────────────────────
+
+/**
+ * Tracks the chain of segment keys from root to the current boundary.
+ * Each keyed `TimberErrorBoundary` appends its `segmentKey`; unkeyed
+ * slot boundaries pass the parent value through. The claim rule uses
+ * this to find the first *reachable* owner from the `owners` list,
+ * eliminating the owner-below-throw-site escape. See TIM-1450.
+ */
+const DenyAncestryContext = createContext<readonly string[]>([]);
+
+export { DenyAncestryContext };
+
 // ─── Digest Types ────────────────────────────────────────────────────────────
 
 /** Structured digest returned by RSC onError for DenySignal. */
@@ -36,11 +51,13 @@ interface DenyDigest {
   status: number;
   data: unknown;
   /**
-   * Segment key of the segment that owns the matched deny page, present when
-   * an in-tree catch site matched a file it may not render at its own
-   * position and re-threw to reach the owner. See TIM-1356.
+   * Ordered candidate owners — segment keys of segments with matching deny
+   * pages, best match first. Present = addressed (a boundary should render
+   * it). In-tree hoists produce a single-element list; late addressing
+   * (TIM-1450) produces the full candidate list so the boundary can find the
+   * first *reachable* owner via its ancestry context.
    */
-  ownerKey?: string;
+  owners?: string[];
 }
 
 /** Structured digest returned by RSC onError for RenderError. */
@@ -86,10 +103,25 @@ export interface TimberErrorBoundaryProps {
   isSlotBoundary?: boolean;
   /**
    * Segment key of the segment that declared this boundary. Only meaningful
-   * against a deny digest carrying an `ownerKey`. See the decline rule in
+   * against a deny digest carrying `owners`. See the decline rule in
    * `render()` and TIM-1356.
    */
   segmentKey?: string;
+  /**
+   * Catch denies only; re-throw everything else. Set on the copy of a
+   * segment's boundaries placed outside its layout, which gives a deny thrown
+   * from that layout's own chrome a catcher keyed to the segment — without
+   * changing where a 5xx from the same chrome goes. See TIM-1450.
+   */
+  denyOnly?: boolean;
+  /**
+   * The deny chain's terminal: the outermost framework boundary, which claims
+   * any deny that streamed past every segment boundary and renders the
+   * framework default page. Implies `denyOnly`. Only a deny thrown from a
+   * layout's chrome with no status file at or above that layout gets here —
+   * the segment copies (`denyOnly`) claim every other shape. See TIM-1450.
+   */
+  lastResort?: boolean;
   children: ReactNode;
 }
 
@@ -105,6 +137,10 @@ interface TimberErrorBoundaryState {
 // duplicate router.navigate() calls.
 const _handledRedirects = new WeakSet<object>();
 
+// The same guard for the terminal's exit: React may render the fallback
+// path more than once for one error, and the document load must start once.
+const _handledExits = new WeakSet<object>();
+
 // Companion guard keyed by location: client-render redirect() (the
 // next/navigation shim) throws a FRESH error instance on every render
 // attempt, and React replays the errored render — so the WeakSet alone
@@ -162,9 +198,24 @@ export class TimberErrorBoundary extends Component<
     this.setState({ hasError: false, error: null });
   };
 
+  static override contextType = DenyAncestryContext;
+  declare context: readonly string[];
+
+  private get childAncestry(): readonly string[] {
+    const parent = this.context ?? [];
+    const key = this.props.segmentKey;
+    // A segment has two keyed boundary sets (outside and inside its layout);
+    // the inner one sees its own key already present and adds nothing.
+    return key && !parent.includes(key) ? [...parent, key] : parent;
+  }
+
   render(): ReactNode {
     if (!this.state.hasError || !this.state.error) {
-      return this.props.children;
+      return createElement(
+        DenyAncestryContext.Provider,
+        { value: this.childAncestry },
+        this.props.children
+      );
     }
 
     const error = this.state.error;
@@ -218,36 +269,70 @@ export class TimberErrorBoundary extends Component<
           window.location.href = parsed.location;
         }
       }
-      return null;
+      // Nothing to show, but still a subtree replaced: a layout that
+      // redirected after I/O never mounted its children, and the commit that
+      // renders this empty spot must not teach the cache otherwise — or the
+      // redirect's own navigation would advertise those layouts as mounted
+      // and the server would skip into an outlet the client does not have.
+      return this.markStatusPage(null);
     }
 
-    // Owner-addressed denies: an in-tree catch site already resolved the
-    // fallback chain and matched a file it may not render at its own
-    // position, so it re-threw to reach the segment that owns that file.
-    // Every boundary but that one declines — otherwise the nearest boundary
-    // whose status filter happens to match catches first and renders the
-    // deny page at its own depth, wrapped in the layouts the hoist existed
-    // to skip, and from a different file than the chain chose. (Boundary
-    // nesting is per-segment `{status} → category → error`; the 4xx chain
-    // runs status files across ALL segments before any error.tsx, so a
-    // leaf error.tsx would otherwise beat a root 404.tsx.)
+    // Owner-addressed denies: the digest carries an ordered `owners` list
+    // of segment keys with matching deny pages. This boundary claims the
+    // deny only when it is the first *reachable* owner — i.e. its
+    // segmentKey appears in `owners` AND in its ancestry (the chain from
+    // root to here). Unreachable owners (below the throw site) are skipped,
+    // and the first ancestor that IS reachable claims. This eliminates the
+    // owner-below-throw-site escape (TIM-1450).
     //
-    // Declining is the default: an unkeyed boundary — a slot boundary, or
-    // one from a construction site that builds no deny chains — never
-    // claims a deny addressed to a segment. See TIM-1356.
-    // `typeof === 'string'`, not a null check: the digest is untrusted JSON —
-    // `parseDigest` validates only `type`, and any component can set
-    // `error.digest` itself. A non-string `ownerKey` is unequal to every
-    // boundary's key, so a truthiness test would let one error decline its
-    // way past the entire tree and blank the page, where it would otherwise
-    // have hit the nearest matching boundary.
-    if (
-      parsed?.type === 'deny' &&
-      typeof parsed.ownerKey === 'string' &&
-      parsed.ownerKey !== this.props.segmentKey
-    ) {
+    // Unkeyed boundaries (slots, or boundaries without deny chains) never
+    // claim an addressed deny. See TIM-1356.
+    if (parsed?.type === 'deny' && Array.isArray(parsed.owners) && parsed.owners.length > 0) {
+      // Slot boundaries always claim addressed denies — graceful degradation
+      // within the slot is correct regardless of which segment the owner
+      // chain resolved to. Without this, the deny escapes the slot and
+      // becomes a page-level 4xx. See TIM-1450.
+      if (!this.props.lastResort && !this.props.isSlotBoundary) {
+        const reachable = parsed.owners.find((k: string) => this.childAncestry.includes(k));
+        if (!this.props.segmentKey || reachable !== this.props.segmentKey) {
+          throw error;
+        }
+      }
+    }
+    // Deny-only boundaries (the outer segment copies) re-throw everything
+    // else so a crash in a layout's chrome still reaches the documented 5xx
+    // flow instead of a status page for an unrelated error.
+    if (this.props.denyOnly && !this.props.lastResort && parsed?.type !== 'deny') {
       throw error;
     }
+    // The terminal is where that flow ends on the client. A non-deny row
+    // nothing claimed — a RenderError or a plain crash on a route with no
+    // matching `error.tsx` — has no page to render in-SPA; React would
+    // unmount the root. So the terminal does what the router does for an
+    // error envelope (design/10 §"Error Page Rendering for Client
+    // Navigation"): leave the SPA, and let the document request render the
+    // real error page with the real status. On the server it re-throws so
+    // the Fizz shell fails and the pipeline serves that page directly. The
+    // envelope still covers errors that land inside Flight's opening window;
+    // this covers the ones that land after it, which used to be held for
+    // (TIM-1495, TIM-1497).
+    if (this.props.lastResort && parsed?.type !== 'deny') {
+      if (typeof window === 'undefined') {
+        throw error;
+      }
+      if (!_handledExits.has(error)) {
+        _handledExits.add(error);
+        const router = getRouterOrNull();
+        const current = window.location.pathname + window.location.search;
+        // The row arrived for the navigation in flight, whose URL is not on
+        // the address bar yet; fall back to the current document.
+        const target = router?.getPendingUrl() ?? current;
+        queueMicrotask(() => {
+          void leaveSpa(target, current);
+        });
+      }
+      return null;
+    }
 
     // If this boundary has a status filter, check whether the error matches.
     // Non-matching errors re-throw so an outer boundary can catch them.
@@ -290,21 +375,25 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
-    // Pre-rendered fallback element (MDX status files) — render directly.
-    // MDX components are server components that cannot be passed as function
-    // props across the RSC→client boundary. Instead, they are pre-rendered
-    // as elements in the RSC environment and passed here as fallbackElement.
+    return this.markStatusPage(this.renderFallback(parsed, error));
+  }
+
+  /**
+   * The status page this boundary shows for a row it claimed. Its shape is
+   * the file's documented contract: TSX status files get `{ status,
+   * dangerouslyPassData }`, `error.tsx` gets `{ error, digest, reset }` (plus
+   * the deny extras for dual-shape implementations — without the error prop,
+   * an error.tsx reading error.message crashes on deny fall-through, TIM-1081),
+   * and an MDX status file is the element pre-rendered for it at tree-build
+   * time, since a server component cannot cross the RSC→client boundary as a
+   * function prop.
+   */
+  private renderFallback(parsed: ParsedDigest | null, error: Error): ReactNode {
     if (this.props.fallbackElement != null) {
       return this.props.fallbackElement;
     }
 
-    // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
-      // Status-code file boundaries (404.tsx, 4xx.tsx, …) get the documented
-      // 4xx props. error.tsx boundaries (no status filter) get their
-      // documented { error, digest, reset } contract — plus the deny extras
-      // for dual-shape implementations. Without the error prop, an error.tsx
-      // reading error.message crashes on deny fall-through. See TIM-1081.
       if (this.props.status != null) {
         return createElement(this.props.fallbackComponent as never, {
           status: parsed.status,
@@ -330,6 +419,19 @@ export class TimberErrorBoundary extends Component<
       reset: this.reset,
     });
   }
+
+  /**
+   * A status page (or, for a redirect row, nothing at all) replaced part of
+   * the main route, and the segment cache must not learn a chain that never
+   * mounted; the marker tells the navigation that commits this tree. A boundary that declined in `render()` re-threw
+   * before getting here, so only the boundary that put a page on screen
+   * speaks. A slot degrading leaves the page and its chain intact, so slot
+   * boundaries stay silent. See `status-page-marker.tsx` (TIM-1495).
+   */
+  private markStatusPage(page: ReactNode): ReactNode {
+    if (this.props.isSlotBoundary) return page;
+    return createElement(StatusPageMarker, null, page);
+  }
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────

package/src/client/history.ts

@@ -48,21 +48,70 @@ export interface HistoryEntry {
  * Scroll positions are stored in history.state or Navigation API entry
  * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
  *
- * Entries persist for the session duration (no expiry) and are cleared
- * when the tab is closed — matching browser back-button behavior.
+ * Entries have no expiry, but only the 50 most recently used URLs are kept
+ * by default. Traversing to an evicted entry fetches a fresh payload.
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
+  private readonly maxEntries: number;
+
+  constructor({ maxEntries = 50 }: { maxEntries?: number } = {}) {
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError('HistoryStack maxEntries must be a positive integer');
+    }
+    this.maxEntries = maxEntries;
+  }
 
   push(url: string, entry: HistoryEntry): void {
+    // Push runs when a page becomes current (or hydration seeds it). Promote
+    // replacements too, so the current page always survives overflow.
+    this.entries.delete(url);
     this.entries.set(url, entry);
+    if (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) this.entries.delete(oldest.value);
+    }
   }
 
   get(url: string): HistoryEntry | undefined {
-    return this.entries.get(url);
+    const entry = this.entries.get(url);
+    if (entry) {
+      this.entries.delete(url);
+      this.entries.set(url, entry);
+    }
+    return entry;
   }
 
+  /** Presence checks (such as hover prefetch probes) do not promote entries. */
   has(url: string): boolean {
     return this.entries.has(url);
   }
+
+  delete(url: string): boolean {
+    return this.entries.delete(url);
+  }
+
+  /**
+   * Evict all cached payloads (TIM-1476). Called after a server action
+   * that revalidated data — history entries are equally stale since they
+   * replay on back/forward without a server check. Clearing forces a
+   * fresh fetch on the next traversal.
+   *
+   * The current URL's `segmentInfo` is preserved (payload nulled) so
+   * `applyActionResult` can read it to maintain the segment cache
+   * across the piggybacked revalidation. Other branches (reval.paths-
+   * only, redirect) do not call `applyActionResult`, so their entries
+   * are fully removed (codex on #1131 round 2).
+   */
+  clearExcept(currentUrl: string): void {
+    const currentEntry = this.entries.get(currentUrl);
+    this.entries.clear();
+    if (currentEntry) {
+      this.entries.set(currentUrl, {
+        payload: null,
+        params: currentEntry.params,
+        segmentInfo: currentEntry.segmentInfo,
+      });
+    }
+  }
 }

package/src/client/internal.ts

@@ -21,6 +21,7 @@ export type {
   RootRenderer,
 } from './router-types.ts';
 export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.ts';
+export type { NavigationEpoch } from './router-lifecycle.ts';
 
 // ── SSR bridge ───────────────────────────────────────────────────────────
 export { setSsrData, clearSsrData, getSsrData } from './ssr-data.ts';

package/src/client/link.tsx

@@ -20,7 +20,6 @@
 // - searchParams and inline query string are mutually exclusive
 
 import {
-  startTransition,
   useRef,
   useState,
   type AnchorHTMLAttributes,
@@ -60,6 +59,18 @@ function getCurrentSearch(): string {
   return getSsrData()?.search ?? '';
 }
 
+/** Native in-page scrolling needs neither an RSC navigation nor a prefetch. */
+function isNativeFragmentLink(anchor: HTMLAnchorElement): boolean {
+  // Default browser navigation follows the rendered anchor, which may differ
+  // from a freshly resolved preserveSearchParams URL after a shallow update.
+  const href = anchor.href;
+  const hashIndex = href.indexOf('#');
+  // Compare browser-serialized URLs, excluding only fragments. URL.hash and
+  // URL.search erase the distinction between absent and explicitly empty
+  // delimiters, but '/current' and '/current?' are different documents.
+  return hashIndex !== -1 && href.slice(0, hashIndex) === window.location.href.split('#', 1)[0];
+}
+
 // ─── Types ───────────────────────────────────────────────────────
 
 export type OnNavigateEvent = {
@@ -496,21 +507,32 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   // `timber:navigation-end`) waited for full decode. Not opening an action
   // scope is what collapses them into one.
   //
-  // `isPending` runs from the click until `router.navigate()` settles, which
-  // is after `decodePromise` — the same lifecycle the router's pending store
-  // and the TopLoader use. The clear wraps in `startTransition` so it lands
-  // on the same React lane as the router's `root.render` — without it,
-  // the clear is an urgent update that paints before the transition commits,
-  // and destinations with pending Suspense boundaries flash idle for one frame
-  // while the old page is still showing (TIM-1418). The callback is
-  // synchronous, so no action scope is opened (TIM-1306/1307 safe).
+  // `isPending` runs from the click until BOTH `router.navigate()` has settled
+  // (after `decodePromise` — the lifecycle the router's pending store and the
+  // TopLoader use) AND the navigation's `onCommit` has fired. The second
+  // condition is what keeps the flag honest: the promise resolves on decode,
+  // and a destination with a pending Suspense boundary is still off screen
+  // then. A clear scheduled at that point — urgent or in its own transition —
+  // can commit ahead of the suspended tree, so the link flashes idle for a
+  // frame while the old page is still showing (TIM-1418). Wrapping the clear
+  // in `startTransition` was tried: it only holds when both updates share a
+  // lane, and React assigns lanes per event, so the decode-time clear and the
+  // click-time `root.render` never do. (Next.js gets the shared lane because
+  // it hands React the tree in the click event; timber fetches first.) The
+  // commit itself is the only signal that cannot beat the commit, and it is
+  // the router's to give: `onCommit` fires exactly once, on the commit or
+  // when the navigation is abandoned — superseded or failed — so the link
+  // can never be left pending for a commit that will not come.
+  //
+  // Order is not fixed: a destination that does not suspend commits before
+  // decode finishes (streaming reveal), so whichever of settle/commit comes
+  // second clears.
   //
-  // `clickSeq` exists because a superseded navigation RESOLVES rather than
-  // rejecting: `runNavigation` swallows AbortErrors. So clicking the same link
-  // twice in quick succession settles the first promise while the second is
-  // still in flight, and an unguarded clear would report idle mid-navigation.
-  // Only the newest click for this link may clear its flag. Written on click
-  // and nowhere else, so there is no reset for a settle handler to race.
+  // `clickSeq` guards the same-link double click: the first navigation is
+  // superseded (its promise RESOLVES — `runNavigation` swallows AbortErrors —
+  // and its `onCommit` fires) while the second is still in flight, and only
+  // the newest click for this link may clear its flag. Written on click and
+  // nowhere else, so there is no reset for a settle handler to race.
   const [isPending, setIsPending] = useState(false);
   const clickSeq = useRef(0);
   const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
@@ -529,6 +551,15 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
       ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
       : baseHref;
 
+  // Event callbacks may update the URL, so resolve preserved params at use time.
+  const resolveEventUrl = () =>
+    new URL(
+      preserveSearchParams
+        ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+        : resolvedHref,
+      window.location.href
+    );
+
   // ─── Click handler ───────────────────────────────────────────
   // Each Link component owns its click handling. The router is
   // accessed via the singleton ref — during SSR, getRouterOrNull()
@@ -540,6 +571,10 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
 
         if (!shouldInterceptClick(event, resolvedHref)) return;
 
+        // Native anchor scrolling is not an SPA navigation. Decide before
+        // onNavigate can cancel it, just as we do before hover prefetching.
+        if (isNativeFragmentLink(event.currentTarget)) return;
+
         // Call onNavigate if provided — allows caller to cancel
         if (onNavigate) {
           let prevented = false;
@@ -557,19 +592,10 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         const router = getRouterOrNull();
         if (!router) return;
 
-        const navHref = preserveSearchParams
-          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
-          : resolvedHref;
-
-        const resolved = new URL(navHref, window.location.href);
-
-        if (
-          resolved.pathname === window.location.pathname &&
-          stripRscCacheKey(resolved.search) === locationSearch() &&
-          resolved.hash
-        ) {
-          return;
-        }
+        // Keep the post-callback read: onNavigate may change the current URL
+        // and therefore the search params to preserve or fragment locality.
+        const resolved = resolveEventUrl();
+        if (isNativeFragmentLink(event.currentTarget)) return;
 
         event.preventDefault();
 
@@ -580,12 +606,23 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
 
         const seq = ++clickSeq.current;
+        let settled = false;
+        let committed = false;
+        const clear = () => {
+          if (clickSeq.current === seq) setIsPending(false);
+        };
+        const onCommit = () => {
+          committed = true;
+          if (settled) clear();
+        };
         const settle = () => {
-          if (clickSeq.current === seq) startTransition(() => setIsPending(false));
+          settled = true;
+          if (committed) clear();
         };
         setIsPending(true);
-        router.navigate(absoluteHref, { scroll: shouldScroll }).then(settle, (error: unknown) => {
-          settle();
+        const navigation = router.navigate(absoluteHref, { scroll: shouldScroll, onCommit });
+        navigation.then(settle, (error: unknown) => {
+          clear();
           // Rethrow, so a navigation error that the router did not already
           // recover from surfaces as an unhandled rejection — the same
           // regime as `useRouter().push()`'s `void router.navigate(...)`.
@@ -611,10 +648,8 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
           userOnMouseEnter?.(event);
           const router = getRouterOrNull();
           if (router) {
-            const prefetchHref = preserveSearchParams
-              ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
-              : resolvedHref;
-            const resolved = new URL(prefetchHref, window.location.href);
+            if (isNativeFragmentLink(event.currentTarget)) return;
+            const resolved = resolveEventUrl();
             router.prefetch(resolved.pathname + stripRscCacheKey(resolved.search));
           }
         }