@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/client/link-pending-store.ts

@@ -1,116 +0,0 @@
-/**
- * Link Pending Store — per-link pending state.
- *
- * Tracks which link instance is currently navigating so that only the
- * clicked link shows pending. Uses useState in Link — the pending
- * state is set as an urgent update (outside startTransition) so it
- * shows immediately, then reset inside the transition so it commits
- * atomically with the new tree.
- *
- * Flow:
- * 1. Link click → setLinkForCurrentNavigation(instance) stores the ref
- * 2. NavigationRoot → activateLinkPending() calls
- *    instance.setIsPending(LINK_PENDING) as an urgent update
- * 3. Inside startTransition → resetLinkPending() commits with new tree
- *
- * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys because
- * the RSC client bundler can duplicate this module across chunks.
- *
- * See design/19-client-navigation.md §"Per-Link Pending State"
- */
-
-import type { LinkStatus } from './use-link-status.js';
-
-// ─── Types ───────────────────────────────────────────────────────
-
-export interface LinkPendingInstance {
-  setIsPending: (status: LinkStatus) => void;
-}
-
-// ─── Constants ───────────────────────────────────────────────────
-
-const LINK_PENDING_KEY = Symbol.for('__timber_link_pending');
-
-/** Status object: link navigation in flight */
-export const LINK_PENDING: LinkStatus = { isPending: true };
-
-/** Status object: link idle */
-export const LINK_IDLE: LinkStatus = { isPending: false };
-
-// ─── Singleton Storage ───────────────────────────────────────────
-
-function getStore(): { current: LinkPendingInstance | null } {
-  const g = globalThis as Record<symbol, unknown>;
-  if (!g[LINK_PENDING_KEY]) {
-    g[LINK_PENDING_KEY] = { current: null };
-  }
-  return g[LINK_PENDING_KEY] as { current: LinkPendingInstance | null };
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Register the link instance that initiated the current navigation.
- * Called from Link's click handler. Does NOT call setIsPending —
- * that happens via activateLinkPending() called from NavigationRoot.
- *
- * Resets the previous link to idle immediately if a different link
- * is being registered (handles overlapping link clicks).
- */
-export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
-  const store = getStore();
-  if (store.current && store.current !== link) {
-    store.current.setIsPending(LINK_IDLE);
-  }
-  store.current = link;
-}
-
-/**
- * Activate pending state on the current link instance.
- * Called as an urgent update (outside startTransition) so the link
- * shows pending immediately. The corresponding resetLinkPending()
- * is called inside the transition so it commits atomically with
- * the new tree.
- */
-export function activateLinkPending(): void {
-  const store = getStore();
-  store.current?.setIsPending(LINK_PENDING);
-}
-
-/**
- * Reset the current link's pending state and clear the store.
- * Call inside startTransition so the reset commits atomically
- * with the new tree (no frame where pending=false but old content
- * is still visible).
- */
-export function resetLinkPending(): void {
-  const store = getStore();
-  if (store.current) {
-    store.current.setIsPending(LINK_IDLE);
-    store.current = null;
-  }
-}
-
-/**
- * @deprecated No longer needed with useOptimistic. Kept for callers.
- */
-export function getCurrentNavId(): number {
-  return 0;
-}
-
-/**
- * Clean up the link pending store entirely.
- */
-export function clearLinkPendingSetter(): void {
-  getStore().current = null;
-}
-
-/**
- * Unmount a link instance from navigation tracking.
- */
-export function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {
-  const store = getStore();
-  if (store.current === link) {
-    store.current = null;
-  }
-}

package/src/client/nav-link-store.ts

@@ -1,37 +0,0 @@
-/**
- * Navigation Link Store — passes per-link metadata from Link's onClick
- * to the Navigation API's navigate event handler.
- *
- * Used for external navigations (plain <a> tags intercepted by the
- * Navigation API). Link components drive navigation directly via
- * router.navigate() and don't use this store.
- *
- * See design/19-client-navigation.md §"Navigation API Integration"
- */
-
-export interface NavLinkMetadata {
-  /** Whether to scroll to top after navigation. Default: true. */
-  scroll: boolean;
-}
-
-let pendingMetadata: NavLinkMetadata | null = null;
-
-/**
- * Store metadata from Link's onClick for the next navigate event.
- * Called synchronously in the click handler — the navigate event
- * fires synchronously after onClick returns.
- */
-export function setNavLinkMetadata(metadata: NavLinkMetadata): void {
-  pendingMetadata = metadata;
-}
-
-/**
- * Consume the stored metadata. Returns null if no Link onClick
- * preceded this navigation (e.g., plain <a> tag, programmatic nav).
- * Clears the store after reading.
- */
-export function consumeNavLinkMetadata(): NavLinkMetadata | null {
-  const metadata = pendingMetadata;
-  pendingMetadata = null;
-  return metadata;
-}

package/src/dev-tools/warnings.ts

@@ -1,238 +0,0 @@
-/**
- * Dev-mode warnings for common timber.js misuse patterns.
- *
- * These fire in development only and are stripped from production builds.
- * Each warning targets a specific misuse identified during design review.
- *
- * Warnings are deduplicated by warningId:filePath:line so the same warning
- * is only emitted once per dev session (per unique source location).
- *
- * Warnings are written to stderr and, when a Vite dev server is available,
- * forwarded to the browser console via Vite's WebSocket.
- *
- * See design/21-dev-server.md §"Dev-Mode Warnings"
- * See design/11-platform.md §"Dev Mode"
- */
-
-import type { ViteDevServer } from 'vite';
-import { isDebug } from '../server/debug.js';
-
-// ─── Warning IDs ───────────────────────────────────────────────────────────
-
-export const WarningId = {
-  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',
-  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',
-  REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',
-  REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',
-  STATIC_REQUEST_API: 'STATIC_REQUEST_API',
-  SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',
-} as const;
-
-export type WarningId = (typeof WarningId)[keyof typeof WarningId];
-
-// ─── Configuration ──────────────────────────────────────────────────────────
-
-/** Configuration for dev warning behavior. */
-export interface DevWarningConfig {
-  /** Threshold in ms for "slow slot" warnings. Default: 200. */
-  slowSlotThresholdMs?: number;
-}
-
-// ─── Deduplication & Server ─────────────────────────────────────────────────
-
-const _emitted = new Set<string>();
-
-/** Vite dev server for forwarding warnings to browser console. */
-let _viteServer: ViteDevServer | null = null;
-
-/**
- * Register the Vite dev server for browser console forwarding.
- * Called by timber-dev-server during configureServer.
- */
-export function setViteServer(server: ViteDevServer | null): void {
-  _viteServer = server;
-}
-
-function isDev(): boolean {
-  return isDebug();
-}
-
-/**
- * Emit a warning only once per dedup key.
- *
- * Writes to stderr and forwards to browser console via Vite WebSocket.
- * Returns true if emitted (not deduplicated).
- */
-function emitOnce(
-  warningId: WarningId,
-  location: string,
-  level: 'warn' | 'error',
-  message: string
-): boolean {
-  if (!isDev()) return false;
-
-  const dedupKey = `${warningId}:${location}`;
-  if (_emitted.has(dedupKey)) return false;
-  _emitted.add(dedupKey);
-
-  // Write to stderr
-  const prefix = level === 'error' ? '\x1b[31m[timber]\x1b[0m' : '\x1b[33m[timber]\x1b[0m';
-  process.stderr.write(`${prefix} ${message}\n`);
-
-  // Forward to browser console via Vite WebSocket
-  if (_viteServer?.hot) {
-    _viteServer.hot.send('timber:dev-warning', {
-      warningId,
-      level,
-      message: `[timber] ${message}`,
-    });
-  }
-
-  return true;
-}
-
-// ─── Warning Functions ──────────────────────────────────────────────────────
-
-/**
- * Warn when a layout wraps {children} in <Suspense>.
- *
- * This defers the page content — the primary resource — behind a fallback.
- * The page's data fetches won't affect the HTTP status code because they
- * resolve after onShellReady. If the page calls deny(404), the status code
- * is already committed as 200.
- *
- * @param layoutFile - Relative path to the layout file (e.g., "app/(dashboard)/layout.tsx")
- */
-export function warnSuspenseWrappingChildren(layoutFile: string): void {
-  emitOnce(
-    WarningId.SUSPENSE_WRAPS_CHILDREN,
-    layoutFile,
-    'warn',
-    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +
-      'This prevents child pages from setting HTTP status codes. ' +
-      'Use usePendingNavigation() for loading states instead.'
-  );
-}
-
-/**
- * Warn when deny() is called inside a Suspense boundary.
- *
- * After the shell has flushed and the status code is committed, deny()
- * cannot change the HTTP response. The signal will be caught by the nearest
- * error boundary instead of producing a correct status code.
- *
- * @param file - Relative path to the file
- * @param line - Line number where deny() was called
- */
-export function warnDenyInSuspense(file: string, line?: number): void {
-  const location = line ? `${file}:${line}` : file;
-  emitOnce(
-    WarningId.DENY_IN_SUSPENSE,
-    location,
-    'error',
-    `deny() called inside <Suspense> at ${location}. ` +
-      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +
-      'Move deny() outside <Suspense> for correct HTTP semantics.'
-  );
-}
-
-/**
- * Warn when redirect() is called inside a Suspense boundary.
- *
- * This will perform a client-side navigation instead of an HTTP redirect.
- *
- * @param file - Relative path to the file
- * @param line - Line number where redirect() was called
- */
-export function warnRedirectInSuspense(file: string, line?: number): void {
-  const location = line ? `${file}:${line}` : file;
-  emitOnce(
-    WarningId.REDIRECT_IN_SUSPENSE,
-    location,
-    'error',
-    `redirect() called inside <Suspense> at ${location}. ` +
-      'This will perform a client-side navigation instead of an HTTP redirect.'
-  );
-}
-
-/**
- * Warn when redirect() is called in a slot's access.ts.
- *
- * Slots use deny() for graceful degradation. Redirecting from a slot would
- * redirect the entire page, breaking the contract that slot failure is
- * isolated to the slot.
- *
- * @param accessFile - Relative path to the access.ts file
- * @param line - Line number where redirect() was called
- */
-export function warnRedirectInAccess(accessFile: string, line?: number): void {
-  const location = line ? `${accessFile}:${line}` : accessFile;
-  emitOnce(
-    WarningId.REDIRECT_IN_ACCESS,
-    location,
-    'error',
-    `redirect() called in access.ts at ${location}. ` +
-      'Only deny() is valid in slot access checks. ' +
-      'Use deny() to block access or move redirect() to middleware.ts.'
-  );
-}
-
-/**
- * Warn when getCookies() or getHeaders() is called during a static build.
- *
- * In output: 'static' mode, there is no per-request context — these APIs
- * read build-time values only. This is almost always a mistake.
- *
- * @param api - The dynamic API name ("cookies" or "headers")
- * @param file - Relative path to the file calling the API
- */
-export function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {
-  emitOnce(
-    WarningId.STATIC_REQUEST_API,
-    `${api}:${file}`,
-    'error',
-    `${api}() called during static generation of ${file}. ` +
-      'Dynamic request APIs are not available during prerendering.'
-  );
-}
-
-// NOTE: warnCacheRequestProps removed — 'use cache' directive is a future feature.
-// See design/06-caching.md.
-
-/**
- * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
- *
- * A slow slot without Suspense blocks onShellReady — and therefore the
- * status code commit — for the entire page. Wrapping it in <Suspense>
- * lets the shell flush without waiting for the slot.
- *
- * @param slotName - The slot name (e.g., "@admin")
- * @param durationMs - How long the slot took to resolve
- */
-export function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {
-  emitOnce(
-    WarningId.SLOW_SLOT_NO_SUSPENSE,
-    slotName,
-    'warn',
-    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +
-      'Consider wrapping to avoid blocking the flush.'
-  );
-}
-
-// ─── Testing ────────────────────────────────────────────────────────────────
-
-/**
- * Reset emitted warnings. For testing only.
- * @internal
- */
-export function _resetWarnings(): void {
-  _emitted.clear();
-}
-
-/**
- * Get the set of emitted dedup keys. For testing only.
- * @internal
- */
-export function _getEmitted(): ReadonlySet<string> {
-  return _emitted;
-}

package/src/server/flush.ts

@@ -1,183 +0,0 @@
-/**
- * Flush controller for timber.js rendering.
- *
- * Holds the response until `onShellReady` fires, then commits the HTTP status
- * code and flushes the shell. Render-phase signals (deny, redirect, unhandled
- * throws) caught before flush produce correct HTTP status codes.
- *
- * See design/02-rendering-pipeline.md §"The Flush Point" and §"The Hold Window"
- */
-
-import { DenySignal, RedirectSignal, RenderError } from './primitives.js';
-import { logRenderError } from './logger.js';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-/** The readable stream from React's renderToReadableStream. */
-export interface ReactRenderStream {
-  /** The underlying ReadableStream of HTML bytes. */
-  readable: ReadableStream<Uint8Array>;
-  /** Resolves when the shell has finished rendering (all non-Suspense content). */
-  allReady?: Promise<void>;
-}
-
-/** Options for the flush controller. */
-export interface FlushOptions {
-  /** Response headers to include (from middleware.ts, proxy.ts, etc.). */
-  responseHeaders?: Headers;
-  /** Default status code when rendering succeeds. Default: 200. */
-  defaultStatus?: number;
-}
-
-/** Result of the flush process. */
-export interface FlushResult {
-  /** The final HTTP Response. */
-  response: Response;
-  /** The status code committed. */
-  status: number;
-  /** Whether the response was a redirect. */
-  isRedirect: boolean;
-  /** Whether the response was a denial. */
-  isDenial: boolean;
-}
-
-// ─── Render Function Type ────────────────────────────────────────────────────
-
-/**
- * A function that performs the React render.
- *
- * The flush controller calls this, catches any signals thrown during the
- * synchronous shell render (before onShellReady), and produces the
- * correct HTTP response.
- *
- * Must return an object with:
- * - `stream`: The ReadableStream from renderToReadableStream
- * - `shellReady`: A Promise that resolves when onShellReady fires
- */
-export interface RenderResult {
-  /** The HTML byte stream. */
-  stream: ReadableStream<Uint8Array>;
-  /** Resolves when the shell is ready (all non-Suspense content rendered). */
-  shellReady: Promise<void>;
-}
-
-export type RenderFn = () => RenderResult | Promise<RenderResult>;
-
-// ─── Flush Controller ────────────────────────────────────────────────────────
-
-/**
- * Execute a render and hold the response until the shell is ready.
- *
- * The flush controller:
- * 1. Calls the render function to start renderToReadableStream
- * 2. Waits for shellReady (onShellReady)
- * 3. If a render-phase signal was thrown (deny, redirect, error), produces
- *    the correct HTTP status code
- * 4. If the shell rendered successfully, commits the status and streams
- *
- * Render-phase signals caught before flush:
- * - `DenySignal` → HTTP 4xx with appropriate status code
- * - `RedirectSignal` → HTTP 3xx with Location header
- * - `RenderError` → HTTP status from error (default 500)
- * - Unhandled error → HTTP 500
- *
- * @param renderFn - Function that starts the React render.
- * @param options - Flush configuration.
- * @returns The committed HTTP Response.
- */
-export async function flushResponse(
-  renderFn: RenderFn,
-  options: FlushOptions = {}
-): Promise<FlushResult> {
-  const { responseHeaders = new Headers(), defaultStatus = 200 } = options;
-
-  let renderResult: RenderResult;
-
-  // Phase 1: Start the render. The render function may throw synchronously
-  // if there's an immediate error before React even starts.
-  try {
-    renderResult = await renderFn();
-  } catch (error) {
-    return handleSignal(error, responseHeaders);
-  }
-
-  // Phase 2: Wait for onShellReady. Render-phase signals (deny, redirect,
-  // throws outside Suspense) are caught here.
-  try {
-    await renderResult.shellReady;
-  } catch (error) {
-    return handleSignal(error, responseHeaders);
-  }
-
-  // Phase 3: Shell rendered successfully. Commit status and stream.
-  responseHeaders.set('Content-Type', 'text/html; charset=utf-8');
-
-  return {
-    response: new Response(renderResult.stream, {
-      status: defaultStatus,
-      headers: responseHeaders,
-    }),
-    status: defaultStatus,
-    isRedirect: false,
-    isDenial: false,
-  };
-}
-
-// ─── Signal Handling ─────────────────────────────────────────────────────────
-
-/**
- * Handle a render-phase signal and produce the correct HTTP response.
- */
-function handleSignal(error: unknown, responseHeaders: Headers): FlushResult {
-  // Redirect signal → HTTP 3xx
-  if (error instanceof RedirectSignal) {
-    responseHeaders.set('Location', error.location);
-    return {
-      response: new Response(null, {
-        status: error.status,
-        headers: responseHeaders,
-      }),
-      status: error.status,
-      isRedirect: true,
-      isDenial: false,
-    };
-  }
-
-  // Deny signal → HTTP 4xx
-  if (error instanceof DenySignal) {
-    return {
-      response: new Response(null, {
-        status: error.status,
-        headers: responseHeaders,
-      }),
-      status: error.status,
-      isRedirect: false,
-      isDenial: true,
-    };
-  }
-
-  // RenderError → HTTP status from error
-  if (error instanceof RenderError) {
-    return {
-      response: new Response(null, {
-        status: error.status,
-        headers: responseHeaders,
-      }),
-      status: error.status,
-      isRedirect: false,
-      isDenial: false,
-    };
-  }
-
-  // Unknown error → HTTP 500
-  logRenderError({ method: '', path: '', error });
-  return {
-    response: new Response(null, {
-      status: 500,
-      headers: responseHeaders,
-    }),
-    status: 500,
-    isRedirect: false,
-    isDenial: false,
-  };
-}