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

package/src/search-params/registry.ts

@@ -1,31 +0,0 @@
-/**
- * Runtime registry for route-scoped search params definitions.
- *
- * When a route's modules load, the framework registers its search-params
- * definition here. useQueryStates('/route') resolves codecs from this map.
- *
- * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
- */
-
-import type { SearchParamsDefinition } from './create.js';
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const registry = new Map<string, SearchParamsDefinition<any>>();
-
-/**
- * Register a route's search params definition.
- * Called by the generated route manifest loader when a route's modules load.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {
-  registry.set(route, definition);
-}
-
-/**
- * Look up a route's search params definition.
- * Returns undefined if the route hasn't been loaded yet.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {
-  return registry.get(route);
-}

package/src/server/asset-headers.ts

@@ -1,81 +0,0 @@
-/**
- * Static asset cache header utilities.
- *
- * Hashed assets (e.g. /assets/layout-abc123.css) are immutable — the hash
- * changes when content changes. These get long-lived cache headers:
- *   Cache-Control: public, max-age=31536000, immutable
- *
- * Unhashed assets (e.g. /favicon.ico) get a shorter cache with revalidation:
- *   Cache-Control: public, max-age=3600, must-revalidate
- *
- * This is applied automatically by the framework for static assets served
- * from the build output. Page responses are NOT affected — those are
- * controlled by the developer via middleware.ts or proxy.ts.
- *
- * Design docs: 18-build-system.md, 06-caching.md
- */
-
-/**
- * Regex matching Vite-hashed asset filenames.
- *
- * Vite's default naming: `[name]-[hash].[ext]` where hash is 8+ hex chars.
- * Also matches `[name].[hash].[ext]` pattern.
- *
- * Examples:
- *   /assets/layout-a1b2c3d4.css  → match
- *   /assets/page-e5f6g7h8.js     → match
- *   /assets/chunk.a1b2c3d4.js    → match
- *   /favicon.ico                  → no match
- *   /index.html                   → no match
- */
-const HASHED_ASSET_RE = /[-.][\da-f]{8,}\.\w+$/;
-
-/** One year in seconds (365 days). */
-const ONE_YEAR = 31_536_000;
-
-/** One hour in seconds. */
-const ONE_HOUR = 3_600;
-
-/** Cache-Control value for hashed (immutable) assets. */
-export const IMMUTABLE_CACHE = `public, max-age=${ONE_YEAR}, immutable`;
-
-/** Cache-Control value for unhashed static assets. */
-export const STATIC_CACHE = `public, max-age=${ONE_HOUR}, must-revalidate`;
-
-/**
- * Check if a URL path looks like a hashed asset.
- */
-export function isHashedAsset(pathname: string): boolean {
-  return HASHED_ASSET_RE.test(pathname);
-}
-
-/**
- * Get the appropriate Cache-Control header for a static asset path.
- *
- * Returns `immutable` for hashed assets, short-lived for unhashed.
- */
-export function getAssetCacheControl(pathname: string): string {
-  return isHashedAsset(pathname) ? IMMUTABLE_CACHE : STATIC_CACHE;
-}
-
-/**
- * Generate a `_headers` file for static asset cache control.
- *
- * The `_headers` file is a platform convention supported by Cloudflare Workers
- * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
- * HTTP response headers.
- *
- * Vite places all hashed chunks under `/assets/` — these get immutable caching.
- * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
- */
-export function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}

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;
-}