@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/browser-entry/action-dispatch.ts

@@ -0,0 +1,209 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * Actions are dispatched sequentially through a client-wide queue
+ * (TIM-1475): each action's POST starts only after the previous one has
+ * settled and its result has been applied. Navigations do not enter the
+ * queue — they preempt via the NavigationEpoch, marking any running
+ * action as discarded (TIM-1474). Queries (TIM-1415) will bypass the
+ * queue entirely.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+
+import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.ts';
+import { getRouter, getRouterOrNull } from '#client-internal';
+import { setHardNavigating } from '../navigation-root.tsx';
+import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.ts';
+import { markClientStale } from '../stale-client.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+import { createActionQueue } from './action-queue.ts';
+
+/**
+ * Wait for a navigation or refresh to both settle (promise resolved) AND
+ * commit (pushState / renderPayload's commit thunk ran). The queue must
+ * not release the next action until the URL is correct in the address bar
+ * — same rule `<Link>` uses for `isPending` (design/19 §Per-Link Pending
+ * State). `onCommit` fires exactly once: on commit, supersession, or
+ * failure, so nothing awaiting this can hang (codex on #1125).
+ */
+function settledAndCommitted(start: (onCommit: () => void) => Promise<void>): Promise<void> {
+  let commitResolve!: () => void;
+  const committed = new Promise<void>((r) => (commitResolve = r));
+  return Promise.all([start(commitResolve).catch(() => {}), committed]).then(() => {});
+}
+
+export function setupServerActions(): void {
+  const queue = createActionQueue({
+    refreshWhenIdle(): void {
+      const router = getRouterOrNull();
+      if (!router) return;
+      router.runWhenIdle(() => void router.refresh());
+    },
+    // Every hold below is `applyActionResult` — the router's own refresh
+    // or piggybacked commit. If it has not settled in `holdTimeoutMs`, the
+    // router is stuck non-idle on that very work (a user navigation would
+    // have superseded it and settled the hold), so `runWhenIdle` would
+    // park forever. A fresh `refresh()` supersedes the stuck owner —
+    // aborting its fetch, settling its uncommitted tree — and re-fetches
+    // the current URL (TIM-1485).
+    recoverStalledHold(): void {
+      const router = getRouterOrNull();
+      if (!router) return;
+      void router.refresh();
+    },
+  });
+
+  setServerCallback((id: string, args: unknown[]) => {
+    return queue.run(async ({ hold }) => {
+      // encodeReply inside the queue — preserves call order when two
+      // calls' args serialize in different numbers of microtasks.
+      const body = await encodeReply(args);
+
+      // Capture the epoch AFTER the previous action has settled and
+      // applied, so it reflects the router's real state — not stale
+      // from a predecessor's refresh bumping the seq (TIM-1474).
+      const router = getRouterOrNull();
+      const epoch = router?.epoch();
+
+      let hasRevalidation = false;
+      let hasRedirect = false;
+      const reval: { paths: string | null } = { paths: null };
+
+      const actionHeaders: Record<string, string> = {
+        'Accept': RSC_CONTENT_TYPE,
+        'x-rsc-action': id,
+      };
+      const actionDeploymentId = getClientDeploymentId();
+      if (actionDeploymentId) {
+        actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+      }
+
+      const response = fetch(window.location.href, {
+        method: 'POST',
+        headers: actionHeaders,
+        body,
+      }).then((res) => {
+        if (res.headers.get(RELOAD_HEADER) === '1') {
+          markClientStale();
+          throw new Error('Version skew detected — this client is out of date');
+        }
+        hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+        hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+        reval.paths = res.headers.get('X-Timber-Revalidation-Path');
+        return res;
+      });
+
+      const decoded = await createFromFetch(response);
+
+      // TIM-1454: Invalidate non-matching paths unconditionally — the
+      // mutation happened server-side regardless of navigation state.
+      if (reval.paths) {
+        if (router) {
+          for (const p of reval.paths.split(' ')) {
+            router.invalidatePath(p);
+          }
+        }
+      }
+
+      // TIM-1476: When the server reports any revalidation, evict all
+      // prefetch cache entries and history stack payloads — the mutation
+      // may affect data any route reads, not just the paths the server
+      // named. Placed before the redirect branch so an internal redirect
+      // via router.navigate() cannot consume a stale prefetch (codex on
+      // #1131). In-flight prefetch singleflights are fenced by the
+      // eviction generation and will not repopulate the cache.
+      if (router && (hasRevalidation || reval.paths)) {
+        router.evictStaleCaches();
+      }
+
+      // Redirects apply unconditionally — the server mutated and told
+      // the client where to go. Return undefined to React NOW so the
+      // action scope settles — awaiting the commit inline would deadlock:
+      // React entangles the commit lane with the action scope, so the
+      // commit waits on the action while the action waits on the commit.
+      // The navigate is fire-and-forget: unlike revalidation (where the
+      // next action must capture the refreshed epoch), a redirect leaves
+      // the page entirely — no subsequent action runs on this URL.
+      if (hasRedirect) {
+        const wrapper = decoded as { _redirect: string; _status: number };
+        const isExternal =
+          wrapper._redirect.startsWith('https://') || wrapper._redirect.startsWith('http://');
+        if (isExternal) {
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+          // Never settle — the document is going away and queued actions
+          // must not resume during page teardown (codex on #1125).
+          return new Promise<undefined>(() => {});
+        }
+        try {
+          const r = getRouter();
+          void r.navigate(wrapper._redirect);
+        } catch (e) {
+          console.debug(
+            '[timber] action redirect: router not ready, using full navigation',
+            e instanceof Error ? e.message : e
+          );
+          setHardNavigating(true);
+          window.location.href = wrapper._redirect;
+        }
+        return undefined;
+      }
+
+      if (hasRevalidation) {
+        const wrapper = decoded as { _action: unknown; _tree: unknown };
+        // Return the action result to React NOW — it may be validation errors
+        // the form needs immediately — and hold the queue until the piggybacked
+        // tree commits. Awaiting applyActionResult inline would deadlock: the
+        // action promise settles only after the commit, but React entangles the
+        // commit lane with the action scope, so the commit waits on the action.
+        // Same pattern as the no-tree branch below (codex on #1126).
+        if (router && epoch) {
+          hold(
+            Promise.resolve()
+              .then(() => router.applyActionResult(epoch, wrapper._tree))
+              .then(
+                (applied) => {
+                  if (!applied) queue.markNeedsRefresh();
+                },
+                (e: unknown) => {
+                  console.error('[timber] applyActionResult failed after server action', e);
+                }
+              )
+          );
+        }
+        return wrapper._action;
+      }
+
+      // revalidatePath was called but only for non-current paths —
+      // caches were already invalidated above, no refresh needed.
+      if (reval.paths) {
+        return decoded;
+      }
+
+      // No piggybacked revalidation — return the result to React NOW
+      // (it may be validation errors the form needs immediately) and hold
+      // the queue until the refresh commits so the next action captures a
+      // current epoch (codex on #1125).
+      if (router && epoch) {
+        hold(
+          router.applyActionResult(epoch).then(
+            (applied) => {
+              if (!applied) queue.markNeedsRefresh();
+            },
+            (e: unknown) => {
+              console.debug('[timber] action refresh failed', e instanceof Error ? e.message : e);
+            }
+          )
+        );
+      }
+
+      return decoded;
+    });
+  });
+}

package/src/client/browser-entry/action-queue.ts

@@ -0,0 +1,152 @@
+/**
+ * Sequential Action Queue — serialises server action dispatch.
+ *
+ * One action at a time. The next action's POST starts only after the
+ * previous one has settled AND its result has been applied (revalidation
+ * rendered or refresh awaited). Navigations do not enter the queue —
+ * they preempt via the NavigationEpoch. Queries (TIM-1415) bypass it
+ * entirely.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ * and design/19-client-navigation.md §State Update Invariants (TIM-1475).
+ */
+
+export interface ActionQueueDeps {
+  refreshWhenIdle: () => void;
+  /**
+   * Called once when an action's holds exceed `holdTimeoutMs`. The chain
+   * releases regardless; this is the recovery hook. It must not wait on
+   * the same thing the hold is stuck on — in dispatch the hold IS the
+   * router's own refresh/commit, so a deferred `refreshWhenIdle` would
+   * park forever. Dispatch forces a fresh `router.refresh()` instead,
+   * which supersedes the stuck owner (TIM-1485).
+   */
+  recoverStalledHold: () => void;
+  /**
+   * Maximum time (ms) the queue stays blocked on held promises after an
+   * action's result has been returned. A hung hold (e.g. a refresh commit
+   * awaiting a stalled flight stream) would otherwise brick the chain for
+   * the life of the page. `0` disables the guard. Default: 30s.
+   */
+  holdTimeoutMs?: number;
+}
+
+const DEFAULT_HOLD_TIMEOUT_MS = 30_000;
+
+const noop = (): void => {};
+
+/**
+ * Resolve when every hold settles, or when `timeoutMs` elapses — whichever
+ * comes first. Never rejects. `onTimeout` runs only if the timer wins.
+ * Same race-against-timer shape as `cache/singleflight.ts` (TIM-518),
+ * minus the AbortSignal: holds are fire-and-forget side effects with no
+ * cancellation contract.
+ */
+function awaitHolds(
+  holds: Promise<unknown>[],
+  timeoutMs: number,
+  onTimeout: () => void
+): Promise<void> {
+  const all = Promise.all(holds).then(noop);
+  if (holds.length === 0 || timeoutMs <= 0) return all;
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      onTimeout();
+      resolve();
+    }, timeoutMs);
+    void all.then(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Passed into `work` so it can return a result to React immediately
+ * while keeping the queue blocked on a side effect (e.g. a refresh
+ * that must commit before the next action captures its epoch).
+ */
+export interface ActionQueueRun {
+  hold: (p: Promise<unknown>) => void;
+}
+
+export interface ActionQueue {
+  /**
+   * Enqueue `work` to run after all preceding actions have settled.
+   * Returns `work`'s own promise so the caller (React) gets the action
+   * result or rejection. If the preceding action rejected, `work` still
+   * runs — errors do not break the chain.
+   *
+   * `work` receives a `hold` handle: calling `hold(promise)` keeps the
+   * queue blocked until that promise settles, independent of `work`'s
+   * return value. Use it for "return the result NOW, await the refresh
+   * commit for sequencing."
+   */
+  run: <T>(work: (q: ActionQueueRun) => Promise<T>) => Promise<T>;
+  /**
+   * Mark that a discarded action would have revalidated. When the queue
+   * drains, one refresh fires via `deps.refreshWhenIdle`. If the queue is
+   * already idle — a hold settling after its timeout released the chain —
+   * the refresh fires immediately rather than waiting for a future
+   * action's drain (TIM-1485).
+   */
+  markNeedsRefresh: () => void;
+}
+
+export function createActionQueue(deps: ActionQueueDeps): ActionQueue {
+  let tail: Promise<void> = Promise.resolve();
+  let needsRefresh = false;
+  let idle = true;
+  const holdTimeoutMs = deps.holdTimeoutMs ?? DEFAULT_HOLD_TIMEOUT_MS;
+
+  function drain(): void {
+    if (!needsRefresh) return;
+    needsRefresh = false;
+    deps.refreshWhenIdle();
+  }
+
+  // The caller's promise is untouched: React already has the action
+  // result. Recovery is delegated — the queue cannot know what the hold
+  // is stuck on, and a deferred drain refresh would wait on exactly that.
+  function onHoldTimeout(): void {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`[timber] action queue: hold exceeded ${holdTimeoutMs}ms — releasing chain`);
+    }
+    deps.recoverStalledHold();
+  }
+
+  function run<T>(work: (q: ActionQueueRun) => Promise<T>): Promise<T> {
+    const holds: Promise<unknown>[] = [];
+    const hold = (p: Promise<unknown>): void => {
+      holds.push(p.then(noop, noop));
+    };
+    // `p` is the caller-visible promise — it resolves/rejects with work's
+    // result (React sees this). `settled` is the chain link: work settled
+    // AND every held promise settled (or the hold timeout fired). It never
+    // rejects, so the chain never breaks and the next action always runs.
+    const p = tail.then(
+      () => work({ hold }),
+      () => work({ hold })
+    );
+    const settled = p.then(noop, noop).then(() => awaitHolds(holds, holdTimeoutMs, onHoldTimeout));
+    tail = settled;
+    idle = false;
+    // Drain when the queue empties: tail identity means nobody enqueued
+    // behind this action between its start and its settlement.
+    void settled.then(() => {
+      if (tail !== settled) return;
+      idle = true;
+      drain();
+    });
+    return p;
+  }
+
+  function markNeedsRefresh(): void {
+    needsRefresh = true;
+    // Nothing is queued to drain this — act now rather than strand the
+    // flag until an unrelated future action fires it.
+    if (idle) drain();
+  }
+
+  return { run, markNeedsRefresh };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+
+import type { RouterInstance } from '#client-internal';
+import {
+  setupServerLogReplay,
+  setupClientErrorForwarding,
+  showCompilingOverlay,
+  hideCompilingOverlay,
+} from '../browser-dev.ts';
+
+type HotApi = {
+  on(event: string, cb: (...args: unknown[]) => void): void;
+  send(event: string, data: unknown): void;
+};
+
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export function setupHmr(router: RouterInstance): void {
+  // Vite injects import.meta.hot in dev mode. Cast to access it without
+  // requiring vite/client types in the package tsconfig.
+  const hot = (import.meta as unknown as { hot?: HotApi }).hot;
+  if (!hot) return;
+
+  // ─── Compiling overlay: Vite client HMR updates ──────────────
+  // vite:beforeUpdate fires when Vite begins applying client-side
+  // module updates (React Fast Refresh, CSS hot update, etc.).
+  // vite:afterUpdate fires once all updates are applied.
+  hot.on('vite:beforeUpdate', () => {
+    showCompilingOverlay();
+  });
+  hot.on('vite:afterUpdate', () => {
+    hideCompilingOverlay();
+  });
+
+  // ─── RSC module invalidation ─────────────────────────────────
+  // rsc:update fires when a server component is edited.
+  // Show the compiling overlay while the RSC refresh is in flight.
+  hot.on('rsc:update', () => {
+    showCompilingOverlay();
+    void router.refresh().finally(() => {
+      hideCompilingOverlay();
+    });
+  });
+
+  // Listen for server console logs forwarded via WebSocket.
+  // Replays them in the browser console with a [SERVER] prefix
+  // so developers can see server output without switching to the terminal.
+  // See plugins/dev-logs.ts.
+  setupServerLogReplay(hot);
+
+  // Forward uncaught client errors to the server for the dev overlay.
+  // The server source-maps the stack and sends it back via Vite's
+  // error overlay protocol. See dev-server.ts §client error listener.
+  setupClientErrorForwarding(hot);
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Hydration — pre-hydration sequence and hydrating the React root.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrate the router's React root with the payload
+ * 2. No RSC payload: nothing — the root is created by the first render
+ *    (client/react-root.ts)
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()          — creates the global router so useRouter()
+ *                              works during render
+ *   2. setNavigationState()  — populates pathname/search so usePathname()
+ *                              returns correct values during hydration
+ *   3. hydrateRoot()         — synchronously executes component render
+ *                              functions that depend on steps 1-2
+ *
+ * Params are not part of this sequence. They arrive on the payload root and
+ * are published by `PayloadRoot` at the top of the tree, so
+ * `useSegmentParams()` is correct during hydration without anything having to
+ * run before it (TIM-1294, TIM-1297).
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+
+import { getRouterOrNull } from '#client-internal';
+import { getNavigationState, setNavigationState } from '../navigation-context.ts';
+import { isPageUnloading } from '../unload-guard.ts';
+import { locationSearch } from '../location-search.ts';
+import type { ReactRootHost } from '../react-root.ts';
+
+import type { RscStreamResult } from './rsc-stream.ts';
+import type { RouterInitResult } from './router-init.ts';
+
+let showHydrationError: ((error: unknown) => void) | null = null;
+let isHydrationError: ((error: unknown) => boolean) | null = null;
+let pendingHydrationErrors: unknown[] = [];
+
+// React 19 emits attribute-only hydration mismatches via console.error
+// with format substitution: console.error(fmt, link, diff). We must
+// intercept before hydrateRoot() to catch errors during initial hydration.
+const ATTR_MISMATCH_RE =
+  /A tree hydrated but some attributes of the server rendered HTML didn't match/;
+if (process.env.NODE_ENV !== 'production') {
+  const origConsoleError = console.error;
+  console.error = (...args: unknown[]) => {
+    origConsoleError.apply(console, args);
+    if (typeof args[0] === 'string' && ATTR_MISMATCH_RE.test(args[0])) {
+      const message = args
+        .slice(1)
+        .reduce<string>((s, arg) => s.replace('%s', String(arg)), args[0] as string);
+      queueOrShowHydrationError(new Error(message));
+    }
+  };
+  import('../../dev-tools/hydration-overlay.ts').then((m) => {
+    showHydrationError = m.showHydrationError;
+    isHydrationError = m.isHydrationError;
+    for (const err of pendingHydrationErrors) {
+      if (m.isHydrationError(err)) m.showHydrationError(err);
+    }
+    pendingHydrationErrors = [];
+  });
+}
+
+function queueOrShowHydrationError(error: unknown): void {
+  if (showHydrationError && isHydrationError) {
+    if (isHydrationError(error)) showHydrationError(error);
+  } else {
+    pendingHydrationErrors.push(error);
+  }
+}
+
+interface HydrateOptions {
+  /** RSC stream result (null if no inlined payload) */
+  rscResult: RscStreamResult | null;
+  /** The router's React root — the one every navigation renders through. */
+  reactRoot: ReactRootHost;
+  /** The router's wrapper chain — see `RouterInitResult.renderTree`. */
+  renderTree: RouterInitResult['renderTree'];
+}
+
+/**
+ * Run the pre-hydration sequence: set navigation state from the address bar.
+ * Must be called AFTER initRouter().
+ *
+ * Params are no longer seeded here. They used to arrive on two inline scripts
+ * that had to execute before `hydrateRoot()`, because hydration synchronously
+ * renders components that read them. They now ride the payload root, and the
+ * provider that publishes them renders before its own descendants — so the
+ * ordering the step existed to guarantee is now a property of the tree rather
+ * than of the bootstrap sequence (TIM-1294, TIM-1297).
+ */
+export function runPreHydration(): void {
+  setNavigationState({
+    pathname: window.location.pathname,
+    search: locationSearch(),
+  });
+}
+
+/**
+ * Hydrate the React tree when an RSC payload is available.
+ *
+ * Wraps the payload with the router's chain (NavigationProvider,
+ * TimberNuqsAdapter, the slot content cache, ...) and hydrates the router's
+ * React root with it, on the document.
+ *
+ * When no RSC payload is available (JS-only client) there is nothing to
+ * hydrate and nothing to do: the root must not be created at bootstrap —
+ * `createRoot(document).render()` would take React ownership of the entire
+ * document and blank the SSR HTML — so the router's first render, i.e. the
+ * first navigation or revalidation, creates it with the tree it renders
+ * (`createReactRoot`, TIM-600 / TIM-580).
+ */
+export function hydrateApp({ rscResult, reactRoot, renderTree }: HydrateOptions): void {
+  if (!rscResult) return;
+
+  // The chain is the router's own `renderTree`, not a copy: an element type
+  // that is present here and absent on the first navigation (or the
+  // reverse) changes the type at that position, and React remounts
+  // everything below it — losing the layout state partial navigation exists
+  // to preserve. Sharing the function makes that impossible by construction.
+  //
+  // `rscResult.params` is the payload's params promise, not a resolved
+  // record: the inlined Flight stream is still arriving and hydration cannot
+  // wait for it. PayloadRoot suspends on it exactly where React was going to
+  // suspend on `element` (TIM-1297).
+  const wrapped = renderTree(rscResult.element, getNavigationState(), rscResult.params);
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (!getRouterOrNull()) {
+      throw new Error('[timber] hydrateRoot called before initRouter() — bootstrap order violated');
+    }
+  }
+
+  reactRoot.hydrate(wrapped, {
+    // Suppress recoverable hydration errors from deny/error signals
+    // inside Suspense boundaries. The server already handled these
+    // (wrapStreamWithErrorHandling closes the stream cleanly after
+    // the shell is flushed). React replays the error during hydration
+    // but the server HTML is already correct — no recovery needed.
+    onRecoverableError(error: unknown) {
+      if (isPageUnloading()) return;
+      if (process.env.NODE_ENV === 'development') {
+        queueOrShowHydrationError(error);
+        console.debug('[timber] Hydration recoverable error:', error);
+      }
+    },
+  });
+}