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

package/src/client/browser-entry/router-init.ts

@@ -0,0 +1,406 @@
+/**
+ * Router Initialization — creates the timber router with all dependencies.
+ *
+ * Wires up RouterDeps (fetch, history, scroll, RSC decoding, render
+ * callbacks) and optionally sets up Navigation API integration.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+
+import { createElement } from 'react';
+import { createFromFetch } from '../../rsc-runtime/browser.ts';
+import { PayloadRoot } from '../params-context.ts';
+import type { ParamsSource } from '../../shared/payload-root.ts';
+import { createRouter, setGlobalRouter } from '#client-internal';
+import type { RouterDeps, RouterInstance } from '#client-internal';
+import type { NavigationState } from '#client-internal';
+import type { HydrationPage } from '../router-types.ts';
+import { TimberNuqsAdapter } from '../nuqs-adapter.tsx';
+import { NavigationProvider } from '../navigation-context.ts';
+import { navigateTransition, type RenderOwner } from '../navigation-transition.ts';
+import type { NavigationRender } from '../navigation-root.tsx';
+import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.ts';
+import { SlotContentCacheContext, type SlotContentCache } from '../slot-content-cache-context.ts';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from '../navigation-api.ts';
+import { getScrollY, scrollToHashTarget } from './scroll.ts';
+import { locationSearch } from '../location-search.ts';
+import { stripRscCacheKey } from '../../shared/rsc-cache-key.ts';
+
+export interface RouterInitOptions {
+  /**
+   * The router's React root (`createReactRoot().render`). Every path that puts
+   * a page on screen renders through it — it is the synchronous transition
+   * around `root.render`, and the `publish` it takes runs on React's commit.
+   */
+  render: NavigationRender;
+  clientSegmentCache?: boolean;
+}
+
+export interface RouterInitResult {
+  router: RouterInstance;
+  navApiController: NavigationApiController | null;
+  /**
+   * Make the server-rendered page current and hand its tree to React
+   * hydration. `hydrateRoot` receives the tree, built by the same
+   * `renderTree` every navigation renders through. With no payload there is
+   * no tree to hydrate and `hydrateRoot` is not called.
+   */
+  hydrate: (page: HydrationPage, hydrateRoot: (element: React.ReactElement) => void) => void;
+}
+
+/**
+ * Create and register the global timber router.
+ *
+ * Must be called before hydrateRoot so `useRouter()` works during
+ * the initial render (methods lazily resolve the router at invocation,
+ * not render time, but initRouter must still run first).
+ */
+export function createTimberRouter(options: RouterInitOptions): RouterInitResult {
+  const { render } = options;
+
+  // Feature-detect Navigation API. When available, the navigate event
+  // replaces popstate for back/forward and catches external navigations.
+  // See design/19-client-navigation.md §"Navigation API Integration"
+  const useNavApi = hasNavigationApi();
+
+  /**
+   * The tree on screen, with the params published over it and the location
+   * it renders — the client's one record of the displayed page. Null until
+   * a page with a payload is on screen (a document hydrated without one).
+   *
+   * The unwrapped tree is kept because a partial navigation re-wraps this
+   * same element with new context so mounted SegmentOutlets are preserved
+   * (they pick up changes via SegmentUpdateContext, not from new children
+   * props). The params and location are kept beside it because the render
+   * paths that do NOT receive a payload — a shallow search update, a partial
+   * navigation — must republish them rather than drop them.
+   *
+   * The location used to live in a separate `globalThis` store as well,
+   * written by the router's commit, by hydration and by the shallow search
+   * path, and read back here. It was a second record of this one (TIM-1541).
+   */
+  let displayed: { tree: unknown; params: ParamsSource; navState: NavigationState } | null = null;
+
+  // The slot content the client has committed, by segmentPath. Owned here so
+  // there is exactly one per router (never a module or globalThis singleton —
+  // SegmentOutlet also executes during SSR, where a process-wide Map would be
+  // shared across requests). Read by SegmentOutlet in render, written by it
+  // at commit only. See client/slot-content-cache-context.ts (TIM-1423).
+  const slotContentCache: SlotContentCache = new Map();
+
+  /**
+   * Build the client's wrapper chain around a tree. **The only place it is
+   * built.**
+   *
+   * Every render path goes through here — hydration (`hydrate.ts`) receives
+   * this function and builds its root with it, and a navigation, a shallow
+   * search update, a popstate replay and a revalidation all call this. That
+   * matters beyond tidiness: an element type present on one render and absent
+   * on the next changes the type at that position, so React unmounts and
+   * remounts everything below it, destroying the layout state partial
+   * navigation exists to preserve (caught by
+   * tests/e2e/segment-merge-navigation.test.ts when the params wrapper was
+   * conditional).
+   *
+   * `PayloadRoot` is *above* the displayed tree, which on a partial navigation
+   * is the retained tree. That position is the whole design: it is the only
+   * provider a reader in a skipped layout can resolve to (TIM-1297).
+   *
+   * Pure — building the element does not make it the displayed one. Every
+   * caller pairs this with `publishTree` at the point the tree is actually
+   * handed to React, because a navigation builds its element before it is
+   * known to have won and a superseded one must leave the displayed record
+   * describing the route still on screen (TIM-1301).
+   */
+  function renderTree(
+    tree: unknown,
+    navState: NavigationState,
+    params: ParamsSource,
+    segmentUpdates?: Map<string, React.ReactNode>
+  ): React.ReactElement {
+    const withParams = createElement(PayloadRoot, { source: params }, tree as React.ReactNode);
+    const withNav = createElement(NavigationProvider, { value: navState }, withParams);
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: segmentUpdates ?? EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const withSlotCache = createElement(
+      SlotContentCacheContext.Provider,
+      { value: slotContentCache },
+      withUpdates
+    );
+    return createElement(TimberNuqsAdapter, null, withSlotCache);
+  }
+
+  /**
+   * Record the tree the client is now displaying, the params published over
+   * it and the location it renders. Written together — the paths that re-wrap
+   * without a fresh payload (a shallow search update, a partial navigation)
+   * read them back as one and would otherwise restore one route's tree with
+   * another's params or pathname.
+   */
+  function publishTree(tree: unknown, params: ParamsSource, navState: NavigationState): void {
+    displayed = { tree, params, navState };
+  }
+
+  // Late-bound: syncShallowSearch is defined before createRouter, but only
+  // called after the router exists (from patched pushState/replaceState or
+  // the Navigation API handler, both of which fire from user code).
+  let router: RouterInstance | null = null;
+
+  // ─── History API Patch ──────────────────────────────────────────
+  // Patch pushState/replaceState to detect external URL changes (nuqs
+  // shallow updates, replaceUrl, third-party libraries). When the router
+  // itself calls pushState/replaceState, it sets a flag so the patch
+  // skips the sync — the router already updates NavigationContext.
+  //
+  // On Navigation API browsers, the navigate event catches most URL
+  // changes. The patch is defense-in-depth and the primary mechanism
+  // for History API-only browsers (older Safari/Firefox).
+  const ROUTER_HISTORY_FLAG = Symbol.for('__timber_router_history_update');
+  const gFlags = globalThis as Record<symbol, boolean>;
+
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+
+  /**
+   * Sync NavigationContext.search after a shallow URL update. Called by
+   * the Navigation API shallow handler and the History API patch.
+   *
+   * @param search — the new search string. The Navigation API path passes
+   *   this from event.destination.url (window.location hasn't committed
+   *   yet when the navigate listener fires). The History API patch omits
+   *   it, reading window.location.search (already committed by the time
+   *   the patched pushState/replaceState returns).
+   *
+   * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
+   * Re-wraps the displayed tree with updated NavigationProvider and hands it to
+   * React through the root's `render` (startTransition — non-blocking).
+   */
+  function syncShallowSearch(search?: string): void {
+    if (!displayed) return;
+    const currentSearch = search != null ? stripRscCacheKey(search) : locationSearch();
+    if (currentSearch === displayed.navState.search) return;
+
+    // A shallow search update does not re-render the tree from the server, so
+    // the params are unchanged — but they are the client's to publish now, and
+    // this path rebuilds the whole chain. Republishing `displayed.params` is what
+    // keeps a `?q=` change from silently clearing the route's params
+    // (TIM-1285's failure mode, on a path that used to be exempt from it
+    // because the record lived inside the payload).
+    const { tree, params } = displayed;
+    const newNavState: NavigationState = {
+      pathname: displayed.navState.pathname,
+      search: currentSearch,
+    };
+
+    // A shallow search update displaces whatever React is rendering. If a
+    // handed-off tree is still suspended (e.g. a cached popstate replay whose
+    // client component is lazy-loading), this render replaces it and React
+    // will never commit it — so forgetOlderHandoffs never fires and
+    // hasUncommittedNav stays true forever, blocking runWhenIdle tasks.
+    //
+    // Deferred to a microtask so that when a child layout effect fires a
+    // pushState during the same commit (e.g. nuqs syncing on mount),
+    // forgetOlderHandoffs — which runs in the parent layout effect, i.e.
+    // synchronously before the microtask — clears pendingCommit first,
+    // and this settle is a no-op. A genuinely displaced suspended tree
+    // never fires forgetOlderHandoffs, so the microtask settles it
+    // (TIM-1480).
+    queueMicrotask(() => router?.settleHandoffs());
+
+    publishTree(tree, params, newNavState);
+    // No transition types: this is not a navigation, and a
+    // `<ViewTransition>` keyed on the router's types must not mistake a
+    // query-string sync for one. It is still a transition commit, though, so
+    // it claims whatever types a still-suspended navigation queued
+    // (design/37-navigation-api.md §"The claim window").
+    render(renderTree(tree, newNavState, params), null, []);
+  }
+
+  window.history.pushState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalPushState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  window.history.replaceState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalReplaceState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  const deps: RouterDeps = {
+    clientSegmentCache: options?.clientSegmentCache ?? false,
+    fetch: (url, init) => window.fetch(url, init),
+    pushState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.pushState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    replaceState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.replaceState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    navigationApiActive: useNavApi,
+    scrollTo: (x, y) => {
+      // Scroll the document viewport.
+      window.scrollTo(x, y);
+      document.documentElement.scrollTop = y;
+      document.body.scrollTop = y;
+      // Scroll any element explicitly marked as a scroll container.
+      // With segment tree merging, shared layouts (sidebars, nav bars)
+      // are reconciled in place via cloneElement — React preserves their
+      // DOM and scroll state naturally. We no longer auto-detect overflow
+      // containers, which previously found the wrong element (e.g.,
+      // scrolling a sidebar instead of the main content area).
+      // Use `data-timber-scroll-restoration` to opt in specific containers.
+      for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
+        (el as HTMLElement).scrollTop = y;
+      }
+    },
+    getCurrentUrl: () => window.location.pathname + locationSearch(),
+    getScrollY,
+    scrollToHash: scrollToHashTarget,
+
+    decodeRsc: (fetchPromise: Promise<Response>) => {
+      return createFromFetch(fetchPromise);
+    },
+
+    // Hand a navigation's tree to React in a transition
+    // (navigation-transition.ts). The fetch runs outside any transition
+    // scope; only the render that hands the tree over is wrapped, and in a
+    // synchronous `startTransition`. Do NOT make this callback's caller an
+    // async React action — see the entanglement note in
+    // `navigateTransition` (TIM-1306, TIM-1307).
+    //
+    // The perform callback receives a wrapPayload function that wraps the
+    // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+    // is passed explicitly by the router.
+    //
+    // Every render the router makes comes through here — navigations,
+    // refreshes, traversals (fetched or replayed) and revalidations.
+    //
+    // `_url` names the pending URL the router already published to its own
+    // pending store before calling here; the transition has no use for it.
+    navigateTransition: (_url: string, owner: RenderOwner, types, perform, onCommit) => {
+      return navigateTransition(
+        owner,
+        async () => {
+          // What wrapPayload built, held until the transition wins. The client's
+          // record of the displayed tree is navigation state like any other, so
+          // it rides the same commit as the segment cache rather than being
+          // written as a side effect of building the element (TIM-1301).
+          let built: { tree: unknown; params: ParamsSource; navState: NavigationState } | null =
+            null;
+          const { element, decodePromise, commit } = await perform(
+            (
+              rawPayload: unknown,
+              navState: NavigationState,
+              params: ParamsSource,
+              segmentUpdates?: Map<string, unknown>
+            ) => {
+              built = { tree: rawPayload, params, navState };
+              return renderTree(
+                rawPayload,
+                navState,
+                params,
+                segmentUpdates as Map<string, React.ReactNode> | undefined
+              );
+            }
+          );
+          return {
+            element: element as React.ReactNode,
+            decodePromise,
+            commit: () => {
+              if (built) publishTree(built.tree, built.params, built.navState);
+              commit();
+            },
+          };
+        },
+        render,
+        types,
+        onCommit
+      );
+    },
+
+    _getCurrentPayload: () => displayed?.tree ?? null,
+
+    // Schedule a callback after the next paint so scroll operations
+    // happen after React commits the new content to the DOM.
+    // Double-rAF ensures the browser has painted the new frame.
+    afterPaint: (callback: () => void) => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(callback);
+      });
+    },
+  };
+
+  router = createRouter(deps);
+  setGlobalRouter(router);
+
+  // Set up Navigation API integration after router is created.
+  // The navigate event listener delegates to router.navigate and
+  // router.handlePopState for external navigations and traversals.
+  let navApiController: NavigationApiController | null = null;
+  if (useNavApi) {
+    navApiController = setupNavigationApi({
+      onExternalNavigate: async (url, { replace, signal, scroll, departingUrl }) => {
+        await router.navigate(url, {
+          replace,
+          scroll,
+          _signal: signal,
+          _skipHistory: true,
+          _departingUrl: departingUrl,
+        });
+      },
+      onTraverse: async (url, scrollY, signal, direction) => {
+        // Back/forward — delegate to the router's popstate handler.
+        await router.handlePopState(url, scrollY, signal, direction);
+      },
+      onShallowNavigate: (destinationUrl: string) => {
+        const search = new URL(destinationUrl).search;
+        syncShallowSearch(search);
+      },
+    });
+
+    // Wire the router-navigating flag into RouterDeps.
+    // This must be done after setupNavigationApi returns the controller.
+    deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+    deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
+    deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
+    deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
+  }
+
+  /**
+   * See `RouterInitResult.hydrate`.
+   *
+   * Everything is recorded at handover, not on hydration's commit: the
+   * server's HTML for this tree is already what the user is looking at, and
+   * React may never commit the hydration render — see `RouterInstance.hydrate`.
+   */
+  const hydrate: RouterInitResult['hydrate'] = (page, hydrateRoot) => {
+    const navState = router.hydrate(page);
+    if (page.payload == null) return;
+    publishTree(page.payload, page.params, navState);
+    hydrateRoot(renderTree(page.payload, navState, page.params));
+  };
+
+  return { router, navApiController, hydrate };
+}

package/src/client/browser-entry/rsc-stream.ts

@@ -0,0 +1,145 @@
+/**
+ * RSC Stream Bootstrap — decodes the server-inlined RSC payload.
+ *
+ * The RSC payload is embedded in the HTML as progressive inline script
+ * tags that call `self.__timber_f.push([type, data])` as RSC chunks arrive.
+ * Typed tuples: [0] = bootstrap signal, [1, string] = Flight data chunk.
+ *
+ * This module sets up a ReadableStream fed by those push() calls so
+ * `createFromReadableStream` can decode the Flight protocol progressively.
+ *
+ * See design/18-build-system.md §"Entry Files"
+ */
+
+import { createFromReadableStream } from '../../rsc-runtime/browser.ts';
+import { isPageUnloading } from '../unload-guard.ts';
+import { splitPayloadRoot, type PublishedParams } from '../../shared/payload-root.ts';
+
+type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
+
+export interface RscStreamResult {
+  /** The decoded RSC element (thenable/lazy — resolved by React during render) */
+  element: unknown;
+  /**
+   * The params the same payload published beside that tree. A promise: the
+   * inlined Flight stream is still arriving when this runs, and hydration must
+   * not wait for it. `PayloadRoot` suspends on it at the position React was
+   * going to suspend on `element` anyway (TIM-1297).
+   */
+  params: Promise<PublishedParams>;
+}
+
+/**
+ * Create the RSC payload stream from server-inlined `__timber_f` chunks.
+ *
+ * Returns null if no RSC payload was inlined (e.g., JS-only client).
+ * When a payload exists, returns the decoded element for hydration.
+ */
+export function createRscPayloadStream(): RscStreamResult | null {
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). If it doesn't exist, skip Flight decoding
+  // entirely and fall through to the createRoot branch.
+  // Do NOT defensively create it here: that would cause
+  // createFromReadableStream to be called on an empty stream, producing
+  // a "Connection closed" error on hydration. See TIM-552.
+  const timberChunks = (self as unknown as Record<string, FlightSegment[] | undefined>).__timber_f;
+  if (!timberChunks) return null;
+
+  const encoder = new TextEncoder();
+
+  // Buffer to hold string data until the stream writer is ready.
+  // Scripts that execute before hydration starts push data here.
+  let dataBuffer: string[] | undefined = [];
+  let streamWriter: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let streamFlushed = false;
+
+  /** Process a typed tuple from __timber_f. */
+  function handleSegment(seg: FlightSegment): void {
+    if (seg[0] === 0) {
+      // Bootstrap signal — initialize buffer (already done above)
+      if (!dataBuffer) dataBuffer = [];
+    } else if (seg[0] === 1) {
+      // Flight data chunk
+      if (streamWriter) {
+        streamWriter.enqueue(encoder.encode(seg[1]));
+      } else if (dataBuffer) {
+        dataBuffer.push(seg[1]);
+      }
+    }
+  }
+
+  // Process any chunks that arrived before this script executed.
+  for (const seg of timberChunks) {
+    handleSegment(seg);
+  }
+  // Clear the array to release memory.
+  timberChunks.length = 0;
+
+  // Patch push() so subsequent script tags feed data in real time.
+  (timberChunks as unknown as { push: (seg: FlightSegment) => void }).push = handleSegment;
+
+  const rscPayload = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamWriter = controller;
+      // Flush buffered data into the stream.
+      if (dataBuffer) {
+        for (const data of dataBuffer) {
+          controller.enqueue(encoder.encode(data));
+        }
+        dataBuffer = undefined;
+      }
+      // If DOM already loaded (non-streaming or fast page), close now.
+      if (streamFlushed) {
+        controller.close();
+      }
+    },
+  });
+
+  // Close the stream when the document finishes loading.
+  // DOMContentLoaded fires after the HTML parser has processed all
+  // inline scripts (including streamed Suspense replacements and
+  // RSC data), so all push() calls have completed by this point.
+  //
+  // If the page is unloading (user refreshed or navigated away),
+  // do NOT close the stream. When the connection drops mid-stream,
+  // DOMContentLoaded fires because the parser finishes. Closing an
+  // incomplete RSC stream causes React's Flight client to throw
+  // "Connection closed." — a jarring error on a page being replaced.
+  // Leaving the stream open is harmless: the page is being torn down.
+  function onDOMContentLoaded(): void {
+    if (isPageUnloading()) return;
+
+    if (streamWriter && !streamFlushed) {
+      streamWriter.close();
+      streamFlushed = true;
+      dataBuffer = undefined;
+    }
+    streamFlushed = true;
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', onDOMContentLoaded, false);
+  } else {
+    // DOM already parsed. All inline RSC <script> tags have already
+    // executed and pushed their data into the buffer. The buffer was
+    // flushed into the stream during start() above.
+    //
+    // Close via queueMicrotask rather than setTimeout. setTimeout
+    // defers to the next macrotask, which can race with React's
+    // Flight client read loop — if React finishes reading all queued
+    // chunks and issues a reader.read() that pends, the stream is
+    // NOT closed yet (setTimeout hasn't fired), so React sees an
+    // open stream and waits. Then setTimeout fires and closes it.
+    // This works in theory but some React Flight builds interpret
+    // a mid-read close as "Connection closed" rather than clean EOF.
+    // queueMicrotask fires at the end of the current microtask
+    // checkpoint — after start() and createFromReadableStream
+    // initialization but before any macrotask, giving React a
+    // consistent close signal. See TIM-524.
+    queueMicrotask(onDOMContentLoaded);
+  }
+
+  const { tree, params } = splitPayloadRoot(createFromReadableStream(rscPayload));
+  // The stream is a thenable, so the split is asynchronous on both halves.
+  return { element: tree, params: params as Promise<PublishedParams> };
+}

package/src/client/browser-entry/scroll.ts

@@ -0,0 +1,50 @@
+/**
+ * Scroll position helpers for the browser entry.
+ *
+ * Reads scroll position from the document viewport or explicitly marked
+ * `data-timber-scroll-restoration` containers.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
+
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ */
+/**
+ * Scroll the element matching a URL #fragment into view.
+ *
+ * Mirrors browser anchor behavior: looks up the decoded fragment by id,
+ * then by anchor name. Returns true when a matching element was found and
+ * scrolled; false otherwise (the router falls back to scroll-to-top, same
+ * as a full page load with an unknown fragment). See TIM-1035.
+ */
+export function scrollToHashTarget(hash: string): boolean {
+  const fragment = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!fragment) return false;
+  let id: string;
+  try {
+    id = decodeURIComponent(fragment);
+  } catch {
+    return false;
+  }
+  const target = document.getElementById(id) ?? document.getElementsByName(id)[0];
+  if (!target) return false;
+  target.scrollIntoView();
+  return true;
+}
+
+export function getScrollY(): number {
+  if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
+    return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
+  }
+  for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
+    if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
+  }
+  return 0;
+}

package/src/client/deny-last-resort.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { statusReasonPhrase } from '../shared/status-reason-phrase.ts';
+
+/**
+ * The deny chain's terminal, in client form.
+ *
+ * design/10-error-handling.md §"Fallback Chain" ends every chain in the
+ * framework default page. On a document load that page is the HTML string in
+ * `server/default-status-page.ts`. This is the same terminal for a deny that
+ * streamed to the client as an error row and reached the root boundary with
+ * nothing in between able to render it — which happens in exactly one shape:
+ * a server component rendered by a layout's own chrome denied, and no status
+ * file exists at or above that layout. Files *below* the denying layout are
+ * not candidates: rendering any of them means executing that layout again,
+ * which denies again. So there is no user file to show, and this renders the
+ * default one. See TIM-1450, design/04-authorization.md §"Where a Deny Page
+ * Renders".
+ *
+ * A plain reload button, not an automatic navigation: the status and phrase
+ * are already on screen and tell the reader what happened; the button hands
+ * them the one recovery the framework can offer (a document request, which
+ * takes the re-render fallback) without doing it behind their back. An
+ * effect-driven reload could not be told apart from a loop.
+ *
+ * Same content rules as the HTML page: the status code is the only thing
+ * interpolated, and it is clamped by `statusReasonPhrase`. No URL, no error
+ * message, no stack. See design/13-security.md principle 4.
+ */
+export function DenyLastResort({ status }: { status: number }) {
+  const phrase = statusReasonPhrase(status);
+  return (
+    <main
+      data-timber-deny-terminal=""
+      style={{
+        fontFamily: 'system-ui, -apple-system, "Segoe UI", sans-serif',
+        textAlign: 'center',
+        padding: '2rem',
+      }}
+    >
+      <h1 style={{ fontSize: '3rem', fontWeight: 600, margin: 0, letterSpacing: '-0.02em' }}>
+        {status}
+      </h1>
+      <p style={{ margin: '0.5rem 0 0', opacity: 0.7 }}>{phrase}</p>
+      <button
+        type="button"
+        onClick={() => window.location.reload()}
+        style={{ marginTop: '1.5rem', padding: '0.5rem 1rem', font: 'inherit', cursor: 'pointer' }}
+      >
+        Reload
+      </button>
+    </main>
+  );
+}