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

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

@@ -0,0 +1,166 @@
+/**
+ * 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;
+
+    // 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;
+      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>
+  );
+}