@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.73

package/src/segment-params/define.ts

@@ -22,30 +22,30 @@ import {
 } from '../schema-bridge.js';
 
 // ---------------------------------------------------------------------------
-// Server-only ALS reference for .load()
+// Server-only ALS reference for .get()
 // ---------------------------------------------------------------------------
 
 // Same pattern as search-params: eagerly registered at server startup
 // to avoid dynamic imports that lose ALS context. See TIM-523.
-let _rawSegmentParams: (() => Promise<Record<string, string | string[]>>) | undefined;
+let _getSegmentParamsFn: (() => Promise<Record<string, string | string[]>>) | undefined;
 
 /**
- * Register the rawSegmentParams function. Called once at module load time
+ * Register the getSegmentParams function. Called once at module load time
  * from request-context.ts to avoid dynamic import at call time.
  * @internal
  */
-export function _setRawSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {
-  _rawSegmentParams = fn;
+export function _setGetSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void {
+  _getSegmentParamsFn = fn;
 }
 
-function getRawSegmentParams(): Promise<Record<string, string | string[]>> {
-  if (!_rawSegmentParams) {
+function getSegmentParamsFromAls(): Promise<Record<string, string | string[]>> {
+  if (!_getSegmentParamsFn) {
     throw new Error(
-      '[timber] segmentParams.load() is only available on the server. ' +
+      '[timber] segmentParams.get() is only available on the server. ' +
         'Use useSegmentParams() on the client.'
     );
   }
-  return _rawSegmentParams();
+  return _getSegmentParamsFn();
 }
 
 // ---------------------------------------------------------------------------
@@ -75,9 +75,9 @@ export interface ParamsDefinition<T extends Record<string, unknown>> {
   serialize(values: T): Record<string, string>;
 
   /**
-   * Load typed segment params from the current request context (ALS).
+   * Get typed segment params from the current request context (ALS).
    *
-   * Server-only. Reads rawSegmentParams() from ALS and coerces through
+   * Server-only. Reads getSegmentParams() from ALS and coerces through
    * this definition's codecs, returning fully typed params.
    *
    * ```ts
@@ -87,11 +87,11 @@ export interface ParamsDefinition<T extends Record<string, unknown>> {
    * // app/products/[id]/page.tsx
    * import { segmentParams } from './params'
    * export default async function Page() {
-   *   const { id } = await segmentParams.load() // id: number
+   *   const { id } = await segmentParams.get() // id: number
    * }
    * ```
    */
-  load(): Promise<T>;
+  get(): Promise<T>;
 
   /** Read-only codec map. */
   codecs: { [K in keyof T]: Codec<T[K]> };
@@ -248,7 +248,7 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
     return result;
   }
 
-  // ---- load ----
+  // ---- get ----
   // ALS-backed: reads segment params from the current request context.
   // Server-only — throws on client.
   //
@@ -257,13 +257,13 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
   // We return those directly instead of re-parsing, because codecs may
   // not be idempotent (e.g., a codec that only accepts raw strings would
   // throw if given an already-parsed value). See TIM-574.
-  async function load(): Promise<T> {
+  async function get(): Promise<T> {
     if (typeof window !== 'undefined') {
       throw new Error(
-        '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'
+        '[timber] segmentParams.get() is server-only. ' + 'Use useSegmentParams() on the client.'
       );
     }
-    const params = await getRawSegmentParams();
+    const params = await getSegmentParamsFromAls();
     // params are already coerced by the pipeline — return as-is.
     return params as unknown as T;
   }
@@ -271,7 +271,7 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
   const definition: ParamsDefinition<T> = {
     parse,
     serialize,
-    load,
+    get,
     codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
   };
 

package/src/segment-params/index.ts

@@ -17,7 +17,8 @@ export { defineSearchParams } from '../search-params/define.js';
 // Codec bridges moved to @timber-js/app/codec
 // Import fromSchema / fromArraySchema from '@timber-js/app/codec' instead.
 export { withDefault, withUrlKey } from '../search-params/wrappers.js';
-export type { Codec } from '../codec.js';
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
 export type {
   SearchParamCodec,
   SearchParamsDefinition,

package/src/server/action-handler.ts

@@ -123,7 +123,7 @@ export async function handleActionRequest(
     return new Response(null, { status: limitsResult.status });
   }
 
-  // Run inside request context so headers(), cookies() work in actions.
+  // Run inside request context so getHeaders(), getCookies() work in actions.
   // Actions are a mutable context — they can set cookies (design/29-cookies.md).
   return runWithRequestContext(req, async () => {
     setMutableCookieContext(true);

package/src/server/als-registry.ts

@@ -24,7 +24,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 
 // ─── Request Context ──────────────────────────────────────────────────────
-// Used by: request-context.ts (headers(), cookies(), searchParams())
+// Used by: request-context.ts (getHeaders(), getCookies(), getSearchParams())
 // Design doc: design/04-authorization.md
 
 /** @internal — import via request-context.ts public API */
@@ -54,7 +54,7 @@ export interface RequestContextStore {
    * Promise resolving to the coerced segment params for the current request.
    * Set by the pipeline after route matching and param coercion, before
    * middleware and rendering. Pages and layouts read params via
-   * `rawSegmentParams()` instead of receiving them as a prop.
+   * `getSegmentParams()` instead of receiving them as a prop.
    *
    * See design/07-routing.md §"params.ts — Convention File for Typed Params"
    */
@@ -88,7 +88,7 @@ export interface CookieEntry {
 }
 
 // ─── Tracing ──────────────────────────────────────────────────────────────
-// Used by: tracing.ts (traceId(), spanId())
+// Used by: tracing.ts (getTraceId(), getSpanId())
 // Design doc: design/17-logging.md
 
 export interface TraceStore {

package/src/server/dev-holding-server.ts

@@ -0,0 +1,185 @@
+/**
+ * Dev holding server — serves a loading page while Vite initializes.
+ *
+ * When `timber dev` (or `vite dev`) starts, Vite takes several seconds
+ * to initialize all plugins, scan routes, and boot the RSC environment.
+ * During this window, the port is unbound and browsers get
+ * ERR_CONNECTION_REFUSED.
+ *
+ * This module creates a lightweight HTTP server that binds the port
+ * immediately and serves a branded holding page with auto-refresh.
+ * Once Vite is ready, the holding server is closed and Vite's server
+ * takes over the port.
+ *
+ * The holding server is started in rootSync's config() hook (the
+ * earliest Vite plugin lifecycle point where we know the port) and
+ * closed in timber-dev-server's configureServer() hook (the last
+ * plugin, right before Vite calls server.listen()).
+ *
+ * Browser requests (Accept: text/html) get the HTML holding page.
+ * API requests (Accept: application/json) get a 503 JSON response.
+ * All responses include Retry-After: 1.
+ *
+ * See design/21-dev-server.md, TIM-665.
+ */
+
+import http from 'node:http';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface HoldingServer {
+  /**
+   * Start listening on the given port.
+   * Returns the actual bound port (useful when port is 0 for OS assignment).
+   */
+  listen(port: number): Promise<number>;
+
+  /** Gracefully close the server and stop accepting connections. */
+  close(): Promise<void>;
+}
+
+// ─── Holding Page HTML ────────────────────────────────────────────────────
+
+/**
+ * Minimal self-contained HTML holding page.
+ *
+ * Matches the timber.js docs site theme:
+ * - Light mode: warm stone/grain background, timber/bark text
+ * - Dark mode: stone-900 background, stone-200 text
+ * - 🪵 timber.js branding
+ *
+ * Uses meta-refresh (1s) for auto-reload — works without JavaScript.
+ * Inline CSS only, no external dependencies.
+ */
+const HOLDING_PAGE_HTML = [
+  '<!DOCTYPE html>',
+  '<html lang="en">',
+  '<head>',
+  '  <meta charset="utf-8">',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+  '  <meta http-equiv="refresh" content="2">',
+  '  <title>timber — starting...</title>',
+  '  <style>',
+  '    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }',
+  '    body {',
+  '      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;',
+  '      background: #fafaf9;',
+  '      color: #44403c;',
+  '      display: flex;',
+  '      align-items: center;',
+  '      justify-content: center;',
+  '      min-height: 100vh;',
+  '      -webkit-font-smoothing: antialiased;',
+  '    }',
+  '    @media (prefers-color-scheme: dark) {',
+  '      body { background: #1c1917; color: #e7e5e4; }',
+  '      .message { color: #a8a29e; }',
+  '      .spinner { border-color: #57534e; border-top-color: #a1887f; }',
+  '      .logo { color: #e7e5e4; }',
+  '    }',
+  '    .container { text-align: center; padding: 2rem; }',
+  '    .logo {',
+  '      font-size: 1.5rem;',
+  '      font-weight: 700;',
+  '      letter-spacing: -0.02em;',
+  '      color: #5c3d2e;',
+  '      margin-bottom: 1.5rem;',
+  '    }',
+  '    .message {',
+  '      font-size: 0.95rem;',
+  '      color: #78716c;',
+  '      margin-bottom: 2rem;',
+  '    }',
+  '    .spinner {',
+  '      width: 24px;',
+  '      height: 24px;',
+  '      border: 2.5px solid #d7ccc8;',
+  '      border-top-color: #6d4c41;',
+  '      border-radius: 50%;',
+  '      animation: spin 0.8s linear infinite;',
+  '      margin: 0 auto;',
+  '    }',
+  '    @keyframes spin { to { transform: rotate(360deg); } }',
+  '  </style>',
+  '</head>',
+  '<body>',
+  '  <div class="container">',
+  '    <div class="logo">\u{1FAB5} timber.js</div>',
+  '    <p class="message">Dev server starting&hellip;</p>',
+  '    <div class="spinner"></div>',
+  '  </div>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a holding HTTP server that serves a loading page during startup.
+ *
+ * Usage (inside Vite plugin):
+ * ```ts
+ * // In config() hook — earliest point where port is known
+ * const holding = createHoldingServer();
+ * holding.listen(config.server?.port ?? 5173);
+ *
+ * // In last plugin's configureServer() — wrap listen for seamless handoff
+ * const originalListen = server.listen.bind(server);
+ * server.listen = async (...args) => {
+ *   await holding.close();
+ *   return originalListen(...args);
+ * };
+ * ```
+ */
+export function createHoldingServer(): HoldingServer {
+  const server = http.createServer((req, res) => {
+    const accept = req.headers.accept ?? '';
+
+    // API requests: JSON 503
+    if (accept.includes('application/json') && !accept.includes('text/html')) {
+      res.writeHead(503, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Retry-After': '1',
+        'Cache-Control': 'no-store',
+      });
+      res.end(
+        JSON.stringify({
+          error: 'Service Unavailable',
+          message: 'timber dev server is starting — please retry shortly',
+        })
+      );
+      return;
+    }
+
+    // Browser and other requests: HTML holding page
+    res.writeHead(503, {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Retry-After': '1',
+      'Cache-Control': 'no-store',
+    });
+    res.end(HOLDING_PAGE_HTML);
+  });
+
+  return {
+    listen(port: number): Promise<number> {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+          server.removeListener('error', reject);
+          const addr = server.address();
+          const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+          resolve(boundPort);
+        });
+      });
+    },
+
+    close(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+  };
+}

package/src/server/dev-warnings.ts

@@ -110,7 +110,7 @@ export function warnSuspenseWrappingChildren(layoutFile: string): void {
     'warn',
     `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +
       'This prevents child pages from setting HTTP status codes. ' +
-      'Use useNavigationPending() for loading states instead.'
+      'Use usePendingNavigation() for loading states instead.'
   );
 }
 
@@ -178,7 +178,7 @@ export function warnRedirectInAccess(accessFile: string, line?: number): void {
 }
 
 /**
- * Warn when cookies() or headers() is called during a static build.
+ * 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.
@@ -219,25 +219,6 @@ export function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number
   );
 }
 
-// ─── 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 ────────────────────────────────────────────────────────────────
 
 /**

package/src/server/html-injectors.ts

@@ -504,7 +504,7 @@ export interface ClientBootstrapConfig {
   preloadLinks: string;
 }
 
-/** Find a manifest entry by matching the key suffix (e.g. 'client/browser-entry.ts'). */
+/** Find a manifest entry by matching the key suffix (e.g. 'client/browser-entry/index.ts'). */
 function findManifestEntry(map: Record<string, string>, suffix: string): string | undefined {
   for (const [key, value] of Object.entries(map)) {
     if (key.endsWith(suffix)) return value;
@@ -585,7 +585,7 @@ export function buildClientScripts(runtimeConfig: {
   // a monorepo). Match by suffix to handle both cases.
   const manifest = runtimeConfig.buildManifest;
   const browserEntryUrl = manifest
-    ? findManifestEntry(manifest.js, 'client/browser-entry.ts')
+    ? findManifestEntry(manifest.js, 'client/browser-entry/index.ts')
     : undefined;
 
   let preloadLinks = '';
@@ -595,7 +595,7 @@ export function buildClientScripts(runtimeConfig: {
     // Modulepreload hints for browser entry dependencies
     const preloads =
       (manifest
-        ? findManifestEntryArray(manifest.modulepreload, 'client/browser-entry.ts')
+        ? findManifestEntryArray(manifest.modulepreload, 'client/browser-entry/index.ts')
         : undefined) ?? [];
     for (const url of preloads) {
       preloadLinks += `<link rel="modulepreload" href="${url}">`;

package/src/server/index.ts

@@ -1,130 +1,45 @@
 // @timber-js/app/server — Server-side primitives
 // These are the primary imports for server components, middleware, and access files.
+//
+// Framework-internal pipeline plumbing is in #server-internal (Node package import).
+// Design doc: design/triage/api-naming-spike.md §8.5
 
 export type { AccessContext } from './types';
 export type { MiddlewareContext } from './types';
 export type { RouteContext } from './types';
 export type { Metadata, MetadataRoute } from './types';
 
-// Request Context — ALS-backed headers(), cookies(), and rawSearchParams()
+// Request Context — ALS-backed getHeaders(), getCookies(), and getSearchParams()
 // Design doc: design/04-authorization.md §"AccessContext does not include cookies or headers"
 // Design doc: design/23-search-params.md §"Server Integration"
 export {
-  headers,
-  cookies,
-  rawSearchParams,
-  rawSegmentParams,
-  setSegmentParams,
-  runWithRequestContext,
-  setMutableCookieContext,
-  markResponseFlushed,
-  getSetCookieHeaders,
+  getHeaders,
+  getHeader,
+  getCookies,
+  getCookie,
+  getSearchParams,
+  getSegmentParams,
 } from './request-context';
 export type { ReadonlyHeaders, RequestCookies, CookieOptions } from './request-context';
 
 // Runtime primitives
 export {
   deny,
-  notFound,
   redirect,
-  permanentRedirect,
   redirectExternal,
   RedirectType,
-  RenderError,
   waitUntil,
-  DenySignal,
-  RedirectSignal,
+  type DenyOptions,
   type RedirectOptions,
 } from './primitives';
+// RenderError removed from public exports per TIM-724.
+// Use deny({ status: 500, data: ... }) instead. RenderError stays in
+// #server-internal for pipeline catch logic.
 export type { RenderErrorDigest, WaitUntilAdapter } from './primitives';
-export type { JsonSerializable } from './types';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
 
-// Pipeline
-export { createPipeline } from './pipeline';
-export type {
-  PipelineConfig,
-  RouteMatch,
-  RouteMatcher,
-  RouteRenderer,
-  EarlyHintsEmitter,
-} from './pipeline';
-
-// Early Hints
-export { collectEarlyHintHeaders, formatLinkHeader } from './early-hints';
-export type { EarlyHint } from './early-hints';
-
-// Early Hints 103 Sender — ALS bridge for platform adapters
-export { runWithEarlyHintsSender, sendEarlyHints103 } from './early-hints-sender';
-export type { EarlyHintsSenderFn } from './early-hints-sender';
-
-// Canonicalization
-export { canonicalize } from './canonicalize';
-export type { CanonicalizeResult } from './canonicalize';
-
-// Proxy
-export { runProxy } from './proxy';
-export type { ProxyFn, ProxyExport } from './proxy';
-
-// Middleware
-export { runMiddleware } from './middleware-runner';
-export type { MiddlewareFn } from './middleware-runner';
-
-// Tree Builder
-export { buildElementTree } from './tree-builder';
-export type {
-  TreeBuilderConfig,
-  TreeBuildResult,
-  LoadedModule,
-  ModuleLoader,
-  AccessGateProps,
-  SlotAccessGateProps,
-  ErrorBoundaryProps,
-} from './tree-builder';
-
-// Access Gates
-export { AccessGate, SlotAccessGate } from './access-gate';
-
-// Status-Code Resolver
-export { resolveStatusFile, resolveSlotDenied } from './status-code-resolver';
-export type {
-  StatusFileResolution,
-  StatusFileKind,
-  StatusFileFormat,
-  SlotDeniedResolution,
-  SlotDeniedKind,
-} from './status-code-resolver';
-
-// Flush Controller
-export { flushResponse } from './flush';
-export type { FlushOptions, FlushResult, RenderFn, RenderResult } from './flush';
-
-// CSRF Protection
-export { validateCsrf } from './csrf';
-export type { CsrfConfig, CsrfResult } from './csrf';
-
-// Body Limits
-export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits';
-export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits';
-
-// Metadata
-export {
-  resolveMetadata,
-  resolveTitle,
-  resolveMetadataUrls,
-  renderMetadataToElements,
-} from './metadata';
-export type { SegmentMetadataEntry, ResolveMetadataOptions, HeadElement } from './metadata';
-
-// Metadata Routes
-export {
-  classifyMetadataRoute,
-  getMetadataRouteServePath,
-  getMetadataRouteAutoLink,
-  METADATA_ROUTE_CONVENTIONS,
-} from './metadata-routes';
-export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes';
-
-// Server Actions
+// Server Actions — user-facing action client and validation
 export { createActionClient, ActionError, validated } from './action-client';
 export type {
   ActionResult,
@@ -144,84 +59,14 @@ export { parseFormData, coerce } from './form-data';
 export { getFormFlash } from './form-flash';
 export type { FormFlashData } from './form-flash';
 
-// Revalidation
-export {
-  revalidatePath,
-  revalidateTag,
-  executeAction,
-  buildNoJsResponse,
-  isRscActionRequest,
-} from './actions';
-export type {
-  RevalidateRenderer,
-  RevalidationState,
-  ActionHandlerConfig,
-  ActionHandlerResult,
-} from './actions';
+// Revalidation — user-facing revalidation APIs
+export { revalidatePath, revalidateTag } from './actions';
 
-// Tracing — per-request trace ID via ALS
+// Tracing — per-request trace ID via ALS (user-facing accessors)
 // Design doc: design/17-logging.md §"trace_id is Always Set"
-export {
-  traceId,
-  spanId,
-  generateTraceId,
-  runWithTraceId,
-  replaceTraceId,
-  withSpan,
-  addSpanEvent,
-} from './tracing';
-export type { TraceStore } from './tracing';
-
-// Logger — structured logging
-// Design doc: design/17-logging.md §"Production Logging"
-export { setLogger, getLogger } from './logger';
-export {
-  logRequestCompleted,
-  logRequestReceived,
-  logSlowRequest,
-  logMiddlewareShortCircuit,
-  logMiddlewareError,
-  logRenderError,
-  logProxyError,
-  logWaitUntilUnsupported,
-  logWaitUntilRejected,
-  logSwrRefetchFailed,
-  logCacheMiss,
-} from './logger';
-export type { TimberLogger } from './logger';
-
-// Instrumentation — instrumentation.ts file convention
-// Design doc: design/17-logging.md §"instrumentation.ts"
-export { loadInstrumentation, callOnRequestError, hasOnRequestError } from './instrumentation';
-export type {
-  InstrumentationOnRequestError,
-  InstrumentationRequestInfo,
-  InstrumentationErrorContext,
-} from './instrumentation';
-
-// Dev Warnings — dev-mode misuse detection
-// Design doc: design/21-dev-server.md §"Dev-Mode Warnings", design/11-platform.md §"Dev Mode"
-export {
-  warnSuspenseWrappingChildren,
-  warnDenyInSuspense,
-  warnRedirectInSuspense,
-  warnRedirectInAccess,
-  warnStaticRequestApi,
-  warnSlowSlotWithoutSuspense,
-  setViteServer,
-  WarningId,
-  // Legacy aliases
-  warnDynamicApiInStaticBuild,
-  warnRedirectInSlotAccess,
-  warnDenyAfterFlush,
-} from './dev-warnings';
-export type { DevWarningConfig } from './dev-warnings';
-
-// Route Handler — route.ts API endpoints
-// Design doc: design/07-routing.md §"route.ts — API Endpoints"
-export { handleRouteRequest, resolveAllowedMethods } from './route-handler';
-export type { RouteModule, RouteHandler, HttpMethod } from './route-handler';
+export { getTraceId, getSpanId, withSpan, addSpanEvent } from './tracing';
 
-// Render timeout — design doc: 02-rendering-pipeline.md §"Streaming Constraints"
-export { RenderTimeoutError } from './render-timeout';
-export type { RenderTimeout } from './render-timeout';
+// Segment params — typed route param coercion for params.ts convention files.
+// Moved from @timber-js/app/segment-params to here per TIM-723.
+export { defineSegmentParams } from '../segment-params/define.js';
+export type { ParamsDefinition, InferParamField, ParamField } from '../segment-params/define.js';