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

package/src/client/browser-dev.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -7,7 +8,7 @@
  * See design/21-dev-server.md §"HMR Wiring"
  */
 
-import { isPageUnloading } from './unload-guard.js';
+import { isPageUnloading } from './unload-guard.ts';
 
 // ─── HMR Hot Interface ──────────────────────────────────────────────
 
@@ -100,6 +101,132 @@ export function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void {
   });
 }
 
+// ─── Compiling Overlay ──────────────────────────────────────────
+
+/**
+ * Compiling overlay state.
+ *
+ * A small non-blocking indicator in the bottom-left corner that shows
+ * "Compiling..." during HMR/module updates. Uses a 200ms debounce so
+ * near-instant updates never flash the indicator.
+ *
+ * The overlay is lazily created on first show and reused thereafter.
+ * All styles are inline — no external CSS dependency.
+ */
+
+let overlayEl: HTMLDivElement | null = null;
+let showTimeoutId: ReturnType<typeof setTimeout> | null = null;
+let pendingUpdates = 0;
+
+/** Debounce delay before showing the overlay (ms). */
+const SHOW_DELAY_MS = 200;
+
+/**
+ * Get the effective debounce delay.
+ * Checks for a test override on `window.__timber_compiling_debounce`
+ * (number) to allow E2E tests to bypass the debounce.
+ */
+function getShowDelay(): number {
+  const win = window as unknown as { __timber_compiling_debounce?: number };
+  return typeof win.__timber_compiling_debounce === 'number'
+    ? win.__timber_compiling_debounce
+    : SHOW_DELAY_MS;
+}
+
+/**
+ * Lazily create the overlay DOM element.
+ * Appended to document.body with fixed positioning in the bottom-left.
+ */
+function getOrCreateOverlay(): HTMLDivElement {
+  if (overlayEl) return overlayEl;
+
+  const el = document.createElement('div');
+  el.setAttribute('data-timber-compiling-overlay', '');
+  Object.assign(el.style, {
+    position: 'fixed',
+    bottom: '16px',
+    left: '16px',
+    padding: '6px 12px',
+    background: 'rgba(0, 0, 0, 0.85)',
+    color: '#fff',
+    fontSize: '13px',
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    fontWeight: '500',
+    borderRadius: '6px',
+    zIndex: '2147483647',
+    pointerEvents: 'none',
+    opacity: '0',
+    transition: 'opacity 150ms ease',
+    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.3)',
+    lineHeight: '1',
+  });
+  el.textContent = 'Compiling…';
+  document.body.appendChild(el);
+  overlayEl = el;
+  return el;
+}
+
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export function showCompilingOverlay(): void {
+  pendingUpdates++;
+  if (pendingUpdates === 1) {
+    const delay = getShowDelay();
+    if (delay <= 0) {
+      // Synchronous show — no setTimeout race with hideCompilingOverlay().
+      // Used by E2E tests to guarantee the overlay is visible before
+      // the async HMR refresh begins its network roundtrip.
+      const el = getOrCreateOverlay();
+      el.style.opacity = '1';
+    } else {
+      // Production path — debounce to avoid flashing for fast updates
+      showTimeoutId = setTimeout(() => {
+        showTimeoutId = null;
+        const el = getOrCreateOverlay();
+        el.style.opacity = '1';
+      }, delay);
+    }
+  }
+}
+
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export function hideCompilingOverlay(): void {
+  const win = window as unknown as { __timber_hold_compiling_overlay?: boolean };
+  if (win.__timber_hold_compiling_overlay) return;
+
+  pendingUpdates = Math.max(0, pendingUpdates - 1);
+  if (pendingUpdates === 0) {
+    if (showTimeoutId !== null) {
+      clearTimeout(showTimeoutId);
+      showTimeoutId = null;
+    }
+    if (overlayEl) {
+      overlayEl.style.opacity = '0';
+    }
+  }
+}
+
 // ─── Client Error Forwarding ────────────────────────────────────────
 
 /**
@@ -108,16 +235,52 @@ export function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void {
  *
  * The server receives 'timber:client-error' events, and echoes them
  * back as Vite '{ type: "error" }' payloads to trigger the overlay.
+ *
+ * Errors that fire before the Vite HMR WebSocket has connected are
+ * buffered and flushed once the connection is established, so
+ * `hot.send()` never throws `SendBeforeConnectError`. See TIM-1509.
  */
-export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): void {
+export function setupClientErrorForwarding(hot: HotInterface): void {
+  // Track WS connection state ourselves because Vite's HMRClient.send()
+  // is fire-and-forget: it catches transport rejections internally via
+  // .catch(err => logger.error(err)), so a pre-connect send doesn't throw
+  // into our code — it just logs a noisy SendBeforeConnectError. Buffering
+  // here prevents that noise entirely.
+  //
+  // The vite:ws:connect listener always fires AFTER registration because
+  // WebSocket.onopen is a macrotask and this code runs synchronously during
+  // module execution (setupHmr → setupClientErrorForwarding in browser-entry).
+  let connected = false;
+  const buffer: Array<{ event: string; data: unknown }> = [];
+
+  function send(event: string, data: unknown): void {
+    if (connected) {
+      hot.send(event, data);
+    } else {
+      buffer.push({ event, data });
+    }
+  }
+
+  hot.on('vite:ws:connect', () => {
+    connected = true;
+    for (const queued of buffer) {
+      hot.send(queued.event, queued.data);
+    }
+    buffer.length = 0;
+  });
+
   window.addEventListener('error', (event: ErrorEvent) => {
     // Skip errors without useful information
     if (!event.error && !event.message) return;
     // Skip errors during page unload — these are abort-related, not application errors
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny) — these are control-flow
+    // signals, not application errors. They should never surface as dev
+    // overlays even if they escape an error boundary. See TIM-838.
+    if (isFrameworkSignalError(event.error)) return;
 
     const error = event.error;
-    hot.send('timber:client-error', {
+    send('timber:client-error', {
       message: error?.message ?? event.message,
       stack: error?.stack ?? '',
       componentStack: error?.componentStack ?? null,
@@ -129,14 +292,38 @@ export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): voi
     if (!reason) return;
     // Skip rejections during page unload — aborted fetches/streams cause these
     if (isPageUnloading()) return;
+    // Skip framework signal digests (redirect/deny). See TIM-838.
+    if (isFrameworkSignalError(reason)) return;
 
     const message = reason instanceof Error ? reason.message : String(reason);
     const stack = reason instanceof Error ? (reason.stack ?? '') : '';
 
-    hot.send('timber:client-error', {
+    send('timber:client-error', {
       message,
       stack,
       componentStack: null,
     });
   });
 }
+
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ *
+ * See also: isControlFlowSignal() in server/signal-identity.ts (server-side,
+ * handles both instanceof and digest detection).
+ */
+export function isFrameworkSignalError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const digest = (error as { digest?: unknown }).digest;
+  if (typeof digest !== 'string') return false;
+  try {
+    const parsed = JSON.parse(digest) as { type?: unknown } | null;
+    if (!parsed || typeof parsed !== 'object') return false;
+    return parsed.type === 'redirect' || parsed.type === 'deny';
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,237 @@
+/**
+ * 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 { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../../shared/csrf-reject.ts';
+import { createActionQueue } from './action-queue.ts';
+
+/**
+ * Wait for a navigation or refresh to both settle (promise resolved) AND
+ * commit (pushState / the navigation'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({ transitionType: 'revalidate' }));
+    },
+    // 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({ transitionType: 'revalidate' });
+    },
+  });
+
+  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;
+      let invalidated = false;
+
+      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');
+        }
+        // A CSRF 403 has a plain-text body; handing it to createFromFetch
+        // would surface as an opaque Flight decode error (TIM-1459).
+        if (res.headers.get(CSRF_REJECT_HEADER) === CSRF_REJECT_VALUE) {
+          throw new Error(
+            'Server action rejected: CSRF origin check failed (403). ' + 'The server log says why.'
+          );
+        }
+        hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
+        hasRedirect = res.headers.get('X-Timber-Redirect') != null;
+        invalidated = res.headers.get('X-Timber-Invalidated') === '1';
+        return res;
+      });
+
+      const decoded = await createFromFetch(response);
+
+      // The mutation happened server-side, and the next thing on screen is
+      // not a full render of the current page: revalidatePath named only
+      // other pages (TIM-1454), or the action redirected — from its body, or
+      // from a current-page revalidation whose render redirected (TIM-1461).
+      // Cached payloads go with the eviction below; this covers the mounted
+      // shared layouts the segment cache would otherwise let the server skip
+      // on the next navigation (TIM-1466). The tree and refresh branches
+      // re-render every layout, so they need neither.
+      if (router && (invalidated || hasRedirect)) {
+        router.suppressSegmentReuse();
+      }
+
+      // TIM-1476: Evict all prefetch cache entries and history stack
+      // payloads after every action — the mutation may affect data any route
+      // reads, not just the paths the server named, and an action that
+      // revalidated nothing still mutated (TIM-1518). Placed before every
+      // branch: before the redirect so an internal redirect via
+      // router.navigate() cannot consume a stale prefetch (codex on #1131),
+      // and synchronously before applyActionResult's hold so a navigation
+      // that supersedes the refresh cannot either. In-flight prefetch
+      // singleflights are fenced by the eviction generation and will not
+      // repopulate the cache.
+      if (router) {
+        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) {
+                    // Synchronous eviction already ran above — only
+                    // the refresh flag needs deferral (TIM-1518).
+                    queue.markNeedsRefresh();
+                  }
+                },
+                (e: unknown) => {
+                  console.error('[timber] applyActionResult failed after server action', e);
+                }
+              )
+          );
+        }
+        return wrapper._action;
+      }
+
+      // revalidatePath was called but only for other pages —
+      // caches were already invalidated above, so no refresh is needed
+      // unless a navigation ran while this action was in flight. That
+      // navigation may have consumed a pre-mutation prefetch before the
+      // eviction above, or fetched before the mutation landed, and it is
+      // now on screen. The other branches catch this through
+      // applyActionResult's epoch check; this one must check itself
+      // (TIM-1483).
+      if (invalidated) {
+        if (router && epoch && !router.isEpochCurrent(epoch)) {
+          queue.markNeedsRefresh();
+        }
+        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 };
+}