@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/server/client-module-map.ts

@@ -1,58 +0,0 @@
-/**
- * Client module map — maps client reference IDs to their SSR module loaders.
- *
- * When the RSC stream contains a client component reference (from a
- * "use client" module), the SSR environment needs to resolve it to the
- * actual component module so it can render the component to HTML.
- *
- * The @vitejs/plugin-rsc SSR runtime handles this internally via its
- * setRequireModule hook — it imports client reference modules from the
- * SSR environment's module graph. This module provides the configuration
- * bridge between timber's entry system and the RSC plugin's runtime.
- *
- * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
- */
-
-/**
- * Client reference metadata used during SSR to resolve client components.
- *
- * The RSC plugin tracks these internally via `clientReferenceMetaMap`.
- * At SSR time, when `createFromReadableStream` encounters a client
- * reference in the RSC payload, it uses the module map to import the
- * actual component for server-side HTML rendering.
- */
-export interface ClientModuleEntry {
-  /** The module ID (Vite-resolved file path) */
-  id: string;
-  /** The export name (e.g., 'default', 'Counter') */
-  name: string;
-  /** Async module loader */
-  load: () => Promise<Record<string, unknown>>;
-}
-
-/**
- * Create a client module map for SSR resolution.
- *
- * In dev mode, the RSC plugin's SSR runtime (`@vitejs/plugin-rsc/ssr`)
- * handles client reference resolution automatically via its initialize()
- * function which sets up `setRequireModule` with dynamic imports through
- * Vite's dev server. No explicit module map is needed.
- *
- * In production builds, the RSC plugin generates a `virtual:vite-rsc/client-references`
- * module that maps client reference IDs to their chunk imports. The SSR
- * runtime reads this at startup.
- *
- * This function returns an empty map as a placeholder — the actual
- * resolution is handled by the RSC plugin's runtime internals.
- */
-export function createClientModuleMap(): Record<string, ClientModuleEntry> {
-  // The @vitejs/plugin-rsc SSR runtime handles client reference
-  // resolution internally. In dev mode, it uses Vite's module runner
-  // to dynamically import client modules. In production, it reads
-  // from the virtual:vite-rsc/client-references manifest.
-  //
-  // This empty map serves as the timber-side type contract. Framework
-  // code that needs to interact with client references at a higher
-  // level (e.g., collecting CSS deps, prefetch hints) can extend this.
-  return {};
-}

package/src/server/dev-fetch-instrumentation.ts

@@ -1,96 +0,0 @@
-/**
- * Dev-mode fetch instrumentation — patches globalThis.fetch to create OTEL
- * spans for every fetch call, giving visibility into async data fetching
- * in the dev request log tree.
- *
- * Only activated in dev mode — zero overhead in production.
- *
- * The spans are automatically children of the active OTEL context (e.g. a
- * timber.page or timber.layout span), so they appear nested under the
- * component that initiated the fetch in the dev log tree.
- *
- * Design ref: 17-logging.md §"Dev Logging", LOCAL-289
- */
-
-import * as api from '@opentelemetry/api';
-
-export type DevFetchCleanup = () => void;
-
-/**
- * Patch globalThis.fetch to wrap every call in an OTEL span.
- *
- * Returns a cleanup function that restores the original fetch.
- * Only call this in dev mode.
- */
-export function instrumentDevFetch(): DevFetchCleanup {
-  const originalFetch = globalThis.fetch;
-  const tracer = api.trace.getTracer('timber.js');
-
-  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-    const { method, url } = extractFetchInfo(input, init);
-
-    return tracer.startActiveSpan(
-      'timber.fetch',
-      {
-        attributes: {
-          'http.request.method': method,
-          'http.url': url,
-        },
-      },
-      async (span) => {
-        try {
-          const response = await originalFetch(input, init);
-
-          span.setAttribute('http.response.status_code', response.status);
-
-          // Surface cache status from standard headers
-          const cacheStatus =
-            response.headers.get('X-Cache') ?? response.headers.get('CF-Cache-Status');
-          if (cacheStatus) {
-            span.setAttribute('timber.cache_status', cacheStatus);
-          }
-
-          span.setStatus({ code: api.SpanStatusCode.OK });
-          span.end();
-          return response;
-        } catch (error) {
-          span.setStatus({ code: api.SpanStatusCode.ERROR });
-          if (error instanceof Error) {
-            span.setAttribute('timber.fetch_error', error.message);
-            span.recordException(error);
-          }
-          span.end();
-          throw error;
-        }
-      }
-    );
-  };
-
-  return () => {
-    globalThis.fetch = originalFetch;
-  };
-}
-
-/**
- * Extract method and URL from the various fetch() call signatures.
- */
-function extractFetchInfo(
-  input: RequestInfo | URL,
-  init?: RequestInit
-): { method: string; url: string } {
-  let method = init?.method ?? 'GET';
-  let url: string;
-
-  if (input instanceof Request) {
-    url = input.url;
-    if (!init?.method) {
-      method = input.method;
-    }
-  } else if (input instanceof URL) {
-    url = input.toString();
-  } else {
-    url = input;
-  }
-
-  return { method: method.toUpperCase(), url };
-}

package/src/server/dev-span-processor.ts

@@ -1,78 +0,0 @@
-/**
- * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
- *
- * Collects completed spans per-request (correlated by trace ID). When the
- * root span (http.server.request) ends, all child spans are already collected
- * (child spans end before parent in OTEL). The processor formats the span
- * tree and writes it to stderr.
- *
- * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
- * now the single source of truth for dev logging — no more parallel event
- * systems that can drift.
- *
- * Design doc: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
- */
-
-import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import type { Span, Context } from '@opentelemetry/api';
-import {
-  formatSpanTree,
-  formatSpanSummary,
-  formatJson,
-  type DevLogMode,
-  type DevLoggerConfig,
-} from './dev-logger.js';
-
-export class DevSpanProcessor implements SpanProcessor {
-  private spansByTrace = new Map<string, ReadableSpan[]>();
-  private mode: DevLogMode;
-  private config: DevLoggerConfig;
-
-  constructor(config: DevLoggerConfig) {
-    this.config = config;
-    this.mode = config.mode ?? 'tree';
-  }
-
-  onStart(_span: Span, _context: Context): void {
-    // No action needed on span start — we collect on end.
-  }
-
-  onEnd(span: ReadableSpan): void {
-    const traceId = span.spanContext().traceId;
-
-    let spans = this.spansByTrace.get(traceId);
-    if (!spans) {
-      spans = [];
-      this.spansByTrace.set(traceId, spans);
-    }
-    spans.push(span);
-
-    // Root span signals request completion — all child spans are already
-    // collected because OTEL ends child spans before parent spans.
-    if (span.name === 'http.server.request') {
-      const output = this.format(spans);
-      if (output) {
-        process.stderr.write(output);
-      }
-      this.spansByTrace.delete(traceId);
-    }
-  }
-
-  private format(spans: ReadableSpan[]): string {
-    if (this.mode === 'quiet') return '';
-    if (this.mode === 'json') return formatJson(spans);
-    if (this.mode === 'summary') return formatSpanSummary(spans, this.config);
-    // Both 'tree' and 'verbose' use the tree formatter.
-    // verbose will show additional detail (every component render) once
-    // component-level spans are wired.
-    return formatSpanTree(spans, this.config);
-  }
-
-  async shutdown(): Promise<void> {
-    this.spansByTrace.clear();
-  }
-
-  async forceFlush(): Promise<void> {
-    // Nothing to flush — output happens synchronously in onEnd.
-  }
-}

package/src/server/dev-warnings.ts

@@ -1,283 +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 './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',
-  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',
-  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 useNavigationPending() 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 cookies() or headers() 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.'
-  );
-}
-
-/**
- * Warn when a "use cache" component receives request-specific props.
- *
- * Cached components should not depend on per-request data — a userId or
- * sessionId in the props means the cache will either be ineffective
- * (key per user) or dangerous (serve one user's data to another).
- *
- * @param componentName - Name of the cached component
- * @param propName - Name of the suspicious prop
- * @param file - Relative path to the component file
- * @param line - Line number
- */
-export function warnCacheRequestProps(
-  componentName: string,
-  propName: string,
-  file: string,
-  line?: number
-): void {
-  const location = line ? `${file}:${line}` : file;
-  emitOnce(
-    WarningId.CACHE_REQUEST_PROPS,
-    `${componentName}:${propName}:${location}`,
-    'warn',
-    `Cached component ${componentName} receives prop "${propName}" which appears request-specific. ` +
-      'Cached components should not depend on per-request data.'
-  );
-}
-
-/**
- * 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.'
-  );
-}
-
-// ─── Legacy aliases ─────────────────────────────────────────────────────────
-
-/** @deprecated Use warnStaticRequestApi instead */
-export const warnDynamicApiInStaticBuild = warnStaticRequestApi;
-
-/** @deprecated Use warnRedirectInAccess instead */
-export function warnRedirectInSlotAccess(slotName: string): void {
-  warnRedirectInAccess(`${slotName}/access.ts`);
-}
-
-/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
-export function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {
-  if (signal === 'deny') {
-    warnDenyInSuspense('unknown');
-  } else {
-    warnRedirectInSuspense('unknown');
-  }
-}
-
-// ─── 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,182 +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';
-
-// ─── 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
-  console.error('[timber] Unhandled render-phase error:', error);
-  return {
-    response: new Response(null, {
-      status: 500,
-      headers: responseHeaders,
-    }),
-    status: 500,
-    isRedirect: false,
-    isDenial: false,
-  };
-}