@timber-js/app 0.2.0-alpha.200 → 0.2.0-alpha.202

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

@@ -13,10 +13,54 @@
 
 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
@@ -41,7 +85,10 @@ export interface ActionQueue {
   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`.
+   * 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;
 }
@@ -49,6 +96,8 @@ export interface ActionQueue {
 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;
@@ -56,6 +105,16 @@ export function createActionQueue(deps: ActionQueueDeps): ActionQueue {
     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 => {
@@ -63,27 +122,30 @@ export function createActionQueue(deps: ActionQueueDeps): ActionQueue {
     };
     // `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. It never rejects, so the chain never
-    // breaks and the next action always runs.
+    // 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(() => Promise.all(holds))
-      .then(noop);
+    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) drain();
+      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/rsc-stream.ts

@@ -95,6 +95,8 @@ export function createRscPayloadStream(): RscStreamResult | null {
     },
   });
 
+  const debugChannel = createHmrDebugChannel();
+
   // Close the stream when the document finishes loading.
   // DOMContentLoaded fires after the HTML parser has processed all
   // inline scripts (including streamed Suspense replacements and
@@ -109,27 +111,6 @@ export function createRscPayloadStream(): RscStreamResult | null {
   function onDOMContentLoaded(): void {
     if (isPageUnloading()) return;
 
-    // In dev mode, do NOT close the stream. React's RSC renderer
-    // includes debug owner/stack references ($1, $14, etc.) in the
-    // Flight payload that point to rows delivered through the debug
-    // channel, not the main Flight stream. The browser Flight client
-    // tracks these as pending chunks. Closing the stream with
-    // unresolved chunks triggers reportGlobalError("Connection closed")
-    // which kills the entire React tree.
-    //
-    // Leaving the stream open is harmless: React has already received
-    // all data rows and can hydrate fully. The pending debug chunks
-    // just remain unresolved (they're only used for React DevTools
-    // component stacks, not rendering).
-    //
-    // In production, debug rows are not emitted, so closing is safe.
-    if (process.env.NODE_ENV === 'development') {
-      // Mark as flushed so no more data is buffered, but don't close.
-      streamFlushed = true;
-      dataBuffer = undefined;
-      return;
-    }
-
     if (streamWriter && !streamFlushed) {
       streamWriter.close();
       streamFlushed = true;
@@ -160,7 +141,82 @@ export function createRscPayloadStream(): RscStreamResult | null {
     queueMicrotask(onDOMContentLoaded);
   }
 
-  const { tree, params } = splitPayloadRoot(createFromReadableStream(rscPayload));
+  const options = debugChannel ? { debugChannel: { readable: debugChannel } } : {};
+
+  const { tree, params } = splitPayloadRoot(createFromReadableStream(rscPayload, options));
   // The stream is a thenable, so the split is asynchronous on both halves.
   return { element: tree, params: params as Promise<PublishedParams> };
 }
+
+/**
+ * Create a ReadableStream that receives RSC debug channel data via HMR.
+ *
+ * The server sends debug data (owner stacks, component info) over the
+ * Vite HMR WebSocket as 'timber:debug-data' events, tagged with a
+ * request ID embedded in the HTML as `self.__timber_debug_id`.
+ *
+ * Returns null in production or when no debug ID is present.
+ */
+function createHmrDebugChannel(): ReadableStream<Uint8Array> | null {
+  if (process.env.NODE_ENV === 'production') return null;
+
+  const debugId = (self as unknown as Record<string, string | undefined>).__timber_debug_id;
+  if (!debugId) return null;
+
+  const hot = (
+    import.meta as unknown as {
+      hot?: {
+        on(event: string, cb: (...args: unknown[]) => void): void;
+        send(event: string, data: unknown): void;
+      };
+    }
+  ).hot;
+  if (!hot) return null;
+
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  const pending: Uint8Array[] = [];
+  let done = false;
+
+  hot.on('timber:debug-data', (data: unknown) => {
+    const msg = data as { id: string; chunk?: string; done?: boolean };
+    if (msg.id !== debugId) return;
+
+    if (msg.done) {
+      done = true;
+      try {
+        controller?.close();
+      } catch {
+        /* already closed */
+      }
+      return;
+    }
+
+    if (msg.chunk && !done) {
+      const bytes = Uint8Array.from(atob(msg.chunk), (c) => c.charCodeAt(0));
+      if (controller) {
+        try {
+          controller.enqueue(bytes);
+        } catch {
+          /* stream closed */
+        }
+      } else {
+        pending.push(bytes);
+      }
+    }
+  });
+
+  // Subscribe to trigger replay of buffered debug chunks. The server
+  // buffers chunks during RSC render (before the browser connects) and
+  // replays them when this subscribe arrives. Vite's client.send()
+  // awaits the WebSocket connect promise, so this is safe at init time.
+  hot.send('timber:debug-subscribe', { id: debugId });
+
+  return new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      controller = ctrl;
+      for (const chunk of pending) ctrl.enqueue(chunk);
+      pending.length = 0;
+      if (done) ctrl.close();
+    },
+  });
+}

package/src/client/error-boundary.tsx

@@ -5,7 +5,7 @@
  *
  * Catches errors thrown by children and renders a fallback component
  * with the appropriate props based on error type:
- *   - DenySignal (4xx) → { status, dangerouslyPassData }
+ *   - DenySignal (4xx) → { status, data }
  *   - RenderError (5xx) → { error, digest, reset }
  *   - Unhandled error → { error, digest: null, reset }
  *
@@ -82,15 +82,6 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
   fallbackComponent?: (...args: unknown[]) => ReactNode;
-  /**
-   * Pre-rendered fallback element. Used for MDX status files which are server
-   * components and cannot be passed as function props across the RSC→client
-   * boundary. When set, rendered directly instead of calling fallbackComponent.
-   *
-   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
-   * files are server components by default (zero client JS).
-   */
-  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
@@ -345,16 +336,10 @@ export class TimberErrorBoundary extends Component<
     }
 
     // Report DenySignal handling so the pipeline skips the redundant
-    // renderDenyPage() re-render — but ONLY when this boundary can fully
-    // handle the deny in-tree:
-    //
-    // ✅ TSX boundaries (fallbackComponent) — can receive runtime props
-    //    (status, dangerouslyPassData) dynamically in render()
-    // ❌ MDX boundaries (fallbackElement) — pre-rendered at tree-build time,
-    //    cannot receive runtime deny props. Must fall through to re-render.
+    // renderDenyPage() re-render.
     //
-    // For qualifying segment boundaries: also set the HTTP status code from
-    // the DenySignal so the Response has the correct 4xx status. This runs
+    // For segment boundaries: also set the HTTP status code from the
+    // DenySignal so the Response has the correct 4xx status. This runs
     // synchronously during Fizz rendering, BEFORE onShellReady.
     //
     // For slot boundaries: set _denyHandledByBoundary but do NOT change
@@ -362,15 +347,11 @@ export class TimberErrorBoundary extends Component<
     //
     // See TIM-664, LOCAL-298.
     if (parsed?.type === 'deny') {
-      const canHandleInTree = this.props.fallbackElement == null;
-
-      if (canHandleInTree || this.props.isSlotBoundary) {
-        const ssrData = getSsrData();
-        if (ssrData?._navContext) {
-          ssrData._navContext._denyHandledByBoundary = true;
-          if (!this.props.isSlotBoundary) {
-            ssrData._navContext.statusCode = parsed.status;
-          }
+      const ssrData = getSsrData();
+      if (ssrData?._navContext) {
+        ssrData._navContext._denyHandledByBoundary = true;
+        if (!this.props.isSlotBoundary) {
+          ssrData._navContext.statusCode = parsed.status;
         }
       }
     }
@@ -381,23 +362,16 @@ export class TimberErrorBoundary extends Component<
   /**
    * 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
+   * data }`, `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.
+   * an error.tsx reading error.message crashes on deny fall-through, TIM-1081).
    */
   private renderFallback(parsed: ParsedDigest | null, error: Error): ReactNode {
-    if (this.props.fallbackElement != null) {
-      return this.props.fallbackElement;
-    }
-
     if (parsed?.type === 'deny') {
       if (this.props.status != null) {
         return createElement(this.props.fallbackComponent as never, {
           status: parsed.status,
-          dangerouslyPassData: parsed.data,
+          data: parsed.data,
         });
       }
       return createElement(this.props.fallbackComponent as never, {
@@ -405,7 +379,7 @@ export class TimberErrorBoundary extends Component<
         digest: null,
         reset: this.reset,
         status: parsed.status,
-        dangerouslyPassData: parsed.data,
+        data: parsed.data,
       });
     }
 

package/src/client/error-reconstituter.tsx

@@ -33,7 +33,7 @@ export interface SerializableError {
  * - digest: plain JSON or null
  * - reset: undefined (only meaningful on client after boundary catch)
  * - component: client module reference (RSC Flight serializes as opaque ref)
- * - status / dangerouslyPassData: set only when error.tsx serves a deny()
+ * - status / data: set only when error.tsx serves a deny()
  *   as the last entry in the 4xx fallback chain — forwarded so dual-shape
  *   error.tsx implementations can branch on the deny status (TIM-1081)
  */
@@ -46,10 +46,10 @@ interface ErrorReconstituterProps {
     digest: { code: string; data: unknown } | null;
     reset: (() => void) | undefined;
     status?: number;
-    dangerouslyPassData?: unknown;
+    data?: unknown;
   }>;
   status?: number;
-  dangerouslyPassData?: unknown;
+  data?: unknown;
 }
 
 /**
@@ -62,7 +62,7 @@ export function ErrorReconstituter({
   reset,
   component,
   status,
-  dangerouslyPassData,
+  data,
 }: ErrorReconstituterProps): ReactNode {
   // Reconstitute a real Error so instanceof checks work in user code
   const error = Object.assign(new Error(serialized.message), {
@@ -74,6 +74,6 @@ export function ErrorReconstituter({
     error,
     digest,
     reset,
-    ...(status != null ? { status, dangerouslyPassData } : {}),
+    ...(status != null ? { status, data } : {}),
   });
 }

package/src/dev-tools/debug-channel.ts

@@ -0,0 +1,151 @@
+/**
+ * Dev-mode RSC debug channel transport — pipes Flight debug data to
+ * the browser via Vite's HMR WebSocket.
+ *
+ * React Flight writes debug rows (component info, owner stacks, $E
+ * source entries) to a debug channel writable. This module reads
+ * from the paired readable and buffers chunks until the browser
+ * subscribes via 'timber:debug-subscribe'. Chunks are then replayed
+ * and live-forwarded to that specific client (never broadcast).
+ *
+ * This matches the approach used by Next.js and Waku — debug data
+ * travels out-of-band via WebSocket, not inline in the HTML response.
+ *
+ * Design ref: 13-security.md §7, TIM-1507
+ */
+
+import { randomUUID } from 'node:crypto';
+import { parseDebugRows, type DebugComponentEntry } from '../server/rsc-entry/helpers.ts';
+
+export const DEBUG_CHANNEL_EVENT = 'timber:debug-data';
+export const DEBUG_SUBSCRIBE_EVENT = 'timber:debug-subscribe';
+
+export interface DebugChannelMessage {
+  id: string;
+  chunk?: string;
+  done?: boolean;
+}
+
+/** Per-client send function (Vite's HotChannelClient shape). */
+export type ClientSendFn = (event: string, payload: unknown) => void;
+
+/** Stored session for a single render's debug channel. */
+interface DebugSession {
+  chunks: string[];
+  done: boolean;
+  client?: ClientSendFn;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const SESSION_TTL_MS = 60_000;
+
+/**
+ * Registry of active debug channel sessions. The dev-server plugin
+ * creates one instance and wires it into the HMR handlers.
+ */
+export class DebugChannelRegistry {
+  private sessions = new Map<string, DebugSession>();
+
+  /** Called by pipeToTransport when a chunk arrives from the RSC render. */
+  push(id: string, chunk: string): void {
+    const session = this.sessions.get(id);
+    if (!session) return;
+    session.chunks.push(chunk);
+    if (session.client) {
+      session.client(DEBUG_CHANNEL_EVENT, { id, chunk } satisfies DebugChannelMessage);
+    }
+  }
+
+  /** Called by pipeToTransport when the debug channel stream ends. */
+  finish(id: string): void {
+    const session = this.sessions.get(id);
+    if (!session) return;
+    session.done = true;
+    if (session.client) {
+      session.client(DEBUG_CHANNEL_EVENT, { id, done: true } satisfies DebugChannelMessage);
+      this.evict(id);
+    }
+  }
+
+  /** Called by the HMR subscribe handler when the browser requests its debug data. */
+  subscribe(id: string, clientSend: ClientSendFn): void {
+    const session = this.sessions.get(id);
+    if (!session) {
+      // Unknown ID (stale page, expired session) — close the browser readable.
+      clientSend(DEBUG_CHANNEL_EVENT, { id, done: true } satisfies DebugChannelMessage);
+      return;
+    }
+    session.client = clientSend;
+    // Replay buffered chunks.
+    for (const chunk of session.chunks) {
+      clientSend(DEBUG_CHANNEL_EVENT, { id, chunk } satisfies DebugChannelMessage);
+    }
+    if (session.done) {
+      clientSend(DEBUG_CHANNEL_EVENT, { id, done: true } satisfies DebugChannelMessage);
+      this.evict(id);
+    }
+  }
+
+  /** Parse buffered debug rows into component entries for the error overlay. */
+  getComponents(id: string): DebugComponentEntry[] {
+    const session = this.sessions.get(id);
+    if (!session) return [];
+    const text = session.chunks.map((b64) => Buffer.from(b64, 'base64').toString('utf-8')).join('');
+    return parseDebugRows(text);
+  }
+
+  /** Create a new session for a render request. Returns the requestId. */
+  create(): string {
+    const id = randomUUID();
+    const timer = setTimeout(() => this.evict(id), SESSION_TTL_MS);
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+    this.sessions.set(id, { chunks: [], done: false, timer });
+    return id;
+  }
+
+  private evict(id: string): void {
+    const session = this.sessions.get(id);
+    if (session) {
+      // Notify a subscribed client so its debug readable closes and
+      // Flight's streamDoneCount can reach 2.
+      if (session.client && !session.done) {
+        session.client(DEBUG_CHANNEL_EVENT, { id, done: true } satisfies DebugChannelMessage);
+      }
+      clearTimeout(session.timer);
+      this.sessions.delete(id);
+    }
+  }
+}
+
+/**
+ * Create a debug channel for a single render request.
+ *
+ * Returns `{ writable }` for Flight's renderToReadableStream, plus a
+ * `requestId` to embed in the HTML so the browser can correlate.
+ */
+export function createDevDebugChannel(registry: DebugChannelRegistry): {
+  writable: WritableStream;
+  requestId: string;
+  getComponents: () => DebugComponentEntry[];
+} {
+  const requestId = registry.create();
+  // Plain WritableStream sink — React's Flight server `pipeTo`s into
+  // this. No TransformStream, no reader.read(), no cancel race.
+  // Matches Next.js's createWebDebugChannel pattern.
+  const writable = new WritableStream<Uint8Array>({
+    write(chunk) {
+      registry.push(requestId, Buffer.from(chunk).toString('base64'));
+    },
+    close() {
+      registry.finish(requestId);
+    },
+    abort() {
+      registry.finish(requestId);
+    },
+  });
+  return {
+    writable,
+    requestId,
+    getComponents: () => registry.getComponents(requestId),
+  };
+}

package/src/index.ts

@@ -490,18 +490,14 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // payloads) reads the same value. See TIM-1261.
       ctx.base = resolved.base;
 
-      // Register all timber config file candidates as Vite config file
-      // dependencies so Vite's built-in restart-on-change handles them
-      // (including atomic writes that emit unlink+add instead of change).
-      // All candidates are registered — not just the one that exists — so
-      // that creating a config file after server start also triggers a
-      // restart. The watcher.add() call in dev-server.ts ensures all
-      // candidates are in the watch set.
-      // See design/21-dev-server.md §HMR Wiring.
-      const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-      for (const name of configNames) {
-        resolved.configFileDependencies.push(resolve(resolved.root, name));
-      }
+      // timber.config.* files are NOT registered as configFileDependencies.
+      // Vite's in-process restart cannot bust Node's require cache for ESM
+      // modules loaded via require(), so the restarted server would serve
+      // stale config. Instead, timber-dev-server watches these files and
+      // calls process.exit(RESTART_EXIT_CODE) so the CLI supervisor
+      // respawns a fresh process. See TIM-1444.
+      // The watcher.add() call in dev-server.ts ensures the files are
+      // watched even if created after server start.
 
       // Sync buildDir from Vite's resolved build.outDir. Vite keeps
       // outDir as-is (may be relative), so resolve against root.

package/src/plugins/dev-server.ts

@@ -29,6 +29,7 @@ import {
 import { generateDevErrorPage } from '../dev-tools/error-page.ts';
 import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.ts';
 import { addVirtualModuleContext } from '../config-validation.ts';
+import { DebugChannelRegistry, DEBUG_SUBSCRIBE_EVENT } from '../dev-tools/debug-channel.ts';
 import { registerDevDiscovery } from './dev-discovery.ts';
 import {
   createGraphEndpointMiddleware,
@@ -46,6 +47,14 @@ import type { RouteTree } from '../routing/types.ts';
 
 const RSC_ENTRY_ID = 'virtual:timber-rsc-entry';
 
+/**
+ * Exit code used to signal the CLI supervisor that the dev server needs
+ * a full process restart (e.g. timber.config.ts changed). The supervisor
+ * in cli.ts respawns the worker on this code. 75 = EX_TEMPFAIL (sysexits).
+ * See TIM-1444.
+ */
+export const RESTART_EXIT_CODE = 75;
+
 /**
  * Config file names that trigger a full dev server restart when changed.
  * See 21-dev-server.md §HMR Wiring — config is loaded once at startup.
@@ -120,15 +129,32 @@ export function timberDevServer(ctx: PluginContext): Plugin {
      * filtered out explicitly and passed through to Vite.
      */
     async configureServer(server: ViteDevServer) {
-      // Ensure config files are in the watch set. Vite's watcher covers
-      // the project root, but `server.watcher.add()` is a no-op for files
-      // already watched, and ensures newly-created config files (e.g. from
-      // create-timber-app) are picked up. The actual restart logic is
-      // handled by Vite's built-in configFileDependencies check — see the
-      // configResolved hook in index.ts where we register the config path.
-      // See 21-dev-server.md §HMR Wiring.
+      // Watch config files for changes. When running under the CLI
+      // supervisor (__TIMBER_DEV_WORKER), exit the process so the
+      // supervisor respawns with a fresh require cache. When running
+      // via `vite dev` directly (no supervisor), fall back to Vite's
+      // in-process server.restart() — it serves stale config, but at
+      // least the server stays alive. See TIM-1444.
       const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
       server.watcher.add(configPaths);
+      const configPathSet = new Set(configPaths);
+      const hasSupervisor = Boolean(process.env.__TIMBER_DEV_WORKER);
+      const onConfigChange = (filePath: string) => {
+        if (!configPathSet.has(filePath)) return;
+        if (hasSupervisor) {
+          console.log(`\n[timber] ${basename(filePath)} changed — restarting dev server...\n`);
+          process.exit(RESTART_EXIT_CODE);
+        } else {
+          console.log(
+            `\n[timber] ${basename(filePath)} changed — restarting dev server...` +
+              `\n[timber] Run \`timber dev\` instead of \`vite dev\` for guaranteed fresh config on restart.\n`
+          );
+          server.restart();
+        }
+      };
+      server.watcher.on('change', onConfigChange);
+      server.watcher.on('add', onConfigChange);
+      server.watcher.on('unlink', onConfigChange);
 
       // Listen for client-side errors forwarded from the browser.
       // The browser entry sends 'timber:client-error' events via HMR
@@ -235,6 +261,27 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
   // a correct WebSocket URL (TIM-789).
   const hmrOptions = extractHmrOptions(server.config);
 
+  // Debug channel registry: buffers RSC debug rows per request and replays
+  // them when the browser subscribes via HMR. Created ONCE per server, not
+  // per request — the middleware below re-imports the RSC entry on every
+  // request, and a per-request registry + listener would leak a stale
+  // listener per request. Each stale listener answers a subscribe with
+  // `done: true` (unknown ID), closing the browser's debug readable before
+  // the real replay arrives, which blocks Flight's root on unresolved owner
+  // refs and prevents hydration entirely. See TIM-1507.
+  const debugRegistry = new DebugChannelRegistry();
+  server.hot.on(
+    DEBUG_SUBSCRIBE_EVENT,
+    (data: unknown, client: { send: (event: string, payload: unknown) => void }) => {
+      const msg = data as { id?: string };
+      if (msg?.id) {
+        debugRegistry.subscribe(msg.id, (event, payload) => {
+          client.send(event, payload);
+        });
+      }
+    }
+  );
+
   return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
     const url = req.url;
     if (!url) {
@@ -308,6 +355,7 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
               }>
             ) => void;
             devHmrOptions?: DevErrorHmrOptions;
+            devDebugRegistry?: DebugChannelRegistry;
           }
         | undefined;
       if (config) {
@@ -325,6 +373,9 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
         // but its dev 404 page and fallback error page need the HMR endpoint
         // (including Vite 8's required WS token) for auto-reload (TIM-1067).
         config.devHmrOptions = hmrOptions;
+        // Server-lifetime debug channel registry (created above). Re-assigned
+        // per request because the RSC module may be re-evaluated on HMR.
+        config.devDebugRegistry = debugRegistry;
       }
 
       // Wire source-map handler so error pages show original positions.