@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/src/server/form-data.ts

@@ -41,8 +41,9 @@ export function parseFormData(formData: FormData): Record<string, unknown> {
     if (processed.length === 1) {
       flat[key] = processed[0];
     } else {
-      // Filter out undefined entries from multi-value fields
-      flat[key] = processed.filter((v) => v !== undefined);
+      // Filter out undefined (empty Files) and empty strings from multi-value fields.
+      // Multi-value fields (e.g. tags=js&tags=&tags=ts) should not include blanks.
+      flat[key] = processed.filter((v) => v !== undefined && v !== '');
     }
   }
 
@@ -52,15 +53,13 @@ export function parseFormData(formData: FormData): Record<string, unknown> {
 
 /**
  * Normalize a single FormData entry value.
- * - Empty strings → undefined (enables .optional() semantics)
  * - Empty File objects (no selection) → undefined
+ * - Strings pass through as-is (empty strings stay as empty strings so
+ *   schema validators like `z.string().min(1, 'Required')` can produce
+ *   their custom error messages instead of a generic type mismatch)
  * - Everything else passes through as-is
  */
 function normalizeValue(value: FormDataEntryValue): unknown {
-  if (typeof value === 'string') {
-    return value === '' ? undefined : value;
-  }
-
   // File input with no selection: browsers submit a File with name="" and size=0
   if (value instanceof File && value.size === 0 && value.name === '') {
     return undefined;
@@ -149,6 +148,23 @@ const DANGEROUS_KEYS = new Set(['__proto__']);
  * ```
  */
 export const coerce = {
+  /**
+   * Coerce an empty string to undefined for optional text fields.
+   * Use with `.optional()` schemas where an empty input means "not provided".
+   *
+   * ```ts
+   * // Zod
+   * z.unknown().transform(coerce.text).pipe(z.string().optional())
+   * // Valibot
+   * v.pipe(v.unknown(), v.transform(coerce.text), v.optional(v.string()))
+   * ```
+   */
+  text(value: unknown): string | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value === 'string') return value;
+    return undefined;
+  },
+
   /**
    * Coerce a string to a number.
    * - `"42"` → `42`

package/src/server/html-injectors.ts

@@ -409,12 +409,20 @@ export function buildClientScripts(runtimeConfig: {
   output: string;
   clientJavascript: { disabled: boolean; enableHMRInDev: boolean };
   dev: boolean;
+  devBrowserLogs?: string;
   buildManifest?: import('./build-manifest.js').BuildManifest;
 }): ClientBootstrapConfig {
   if (runtimeConfig.clientJavascript.disabled) {
-    // When client JS is disabled but enableHMRInDev is true in dev mode,
-    // inject only the Vite HMR client for hot reloading CSS, etc.
-    if (runtimeConfig.dev && runtimeConfig.clientJavascript.enableHMRInDev) {
+    // When client JS is disabled, import /@vite/client in dev mode if
+    // any dev feature needs it: HMR for CSS (enableHMRInDev) or
+    // forwardConsole for browser→terminal log forwarding (devBrowserLogs
+    // not 'none'). Without /@vite/client, server.forwardConsole's
+    // client-side console patching never activates. When both features
+    // are off, honor the zero-JS opt-out. See TIM-1152.
+    const needsViteClient =
+      runtimeConfig.clientJavascript.enableHMRInDev ||
+      (runtimeConfig.devBrowserLogs ?? 'warn') !== 'none';
+    if (runtimeConfig.dev && needsViteClient) {
       return {
         bootstrapScriptContent: 'import("/@vite/client")',
         preloadLinks: '',

package/src/server/internal.ts

@@ -101,7 +101,7 @@ export {
   resolveMetadataUrls,
   renderMetadataToElements,
 } from './metadata.js';
-export type { SegmentMetadataEntry, ResolveMetadataOptions, HeadElement } from './metadata.js';
+export type { SegmentMetadataEntry, ResolveMetadataOptions } from './metadata.js';
 
 // ── Metadata Routes ──────────────────────────────────────────────────────
 export {
@@ -163,3 +163,19 @@ export type { RouteModule, RouteHandler, HttpMethod } from './route-handler.js';
 // ── Render Timeout ───────────────────────────────────────────────────────
 export { RenderTimeoutError } from './render-timeout.js';
 export type { RenderTimeout } from './render-timeout.js';
+
+// ── Prebuilt Components (cache.component transform targets) ─────────────
+export {
+  __prebuilt,
+  __prebuiltDev,
+  getPrebuiltRegistration,
+  getPrebuiltRegistry,
+} from './prebuilt-runtime.js';
+export type { PrebuiltComponentOptions, PrebuiltRegistration } from './prebuilt-runtime.js';
+export { setPrebuiltPayloadSource, hasPrebuiltPayloadSource } from './prebuilt/payload-source.js';
+export type {
+  PrebuiltManifest,
+  PrebuiltManifestEntry,
+  PrebuiltPayloadSource,
+} from './prebuilt/payload-source.js';
+export { computeComponentCacheKey } from './prebuilt/cache-key.js';

package/src/server/prebuilt/cache-key.ts

@@ -0,0 +1,224 @@
+/**
+ * Component cache-key hashing for prebuilt (cache.component) entries.
+ *
+ * Key: `sha256(canonicalJson({ props, params })).slice(0, 16)` — see
+ * design/44-render-at-build-time.md §Cache Key. Both the request-time
+ * lookup (prebuilt-runtime.ts) and the post-build capture pass (TIM-1119)
+ * MUST use this exact function, or build artifacts become unaddressable.
+ *
+ * THE IDENTITY CONTRACT (design/44 §Cache Key): cache identity is **JSON
+ * value semantics** — two inputs are the same entry iff they are the same
+ * JSON value. This is an ALLOWLIST, not a denylist: a value participates
+ * in caching iff it is plain JSON data — null, boolean, finite number,
+ * string, dense array, or a plain `Object.prototype` object with only
+ * enumerable string-keyed data properties — plus `undefined` and `-0`,
+ * which hash as distinct sentinels because flight preserves them. Every
+ * value outside that domain (functions, symbols, bigints, accessors,
+ * hidden or symbol-keyed properties, non-`Object.prototype` prototypes
+ * including null, aliased references, sparse arrays, cycles, non-finite
+ * numbers) is UNKEYABLE by definition: `computeComponentCacheKey` returns
+ * null and the caller renders live — slower, never wrong.
+ *
+ * The line between rejected and declared-out-of-domain: values are
+ * REJECTED when the JSON projection itself would be ambiguous or lossy
+ * (hidden/symbol/non-enumerable properties, accessors, exotic
+ * prototypes). Observable state that leaves the projection intact — key
+ * order, reference identity, descriptor metadata (writable/configurable,
+ * frozen/sealed/extensible), proxy behavior — is DECLARED outside
+ * cache.component's supported input domain rather than rejected:
+ * key-order insensitivity is required for determinism, and rejecting
+ * frozen objects would unkey ubiquitous legitimate inputs
+ * (Object.freeze'd config props) to defend against components that
+ * render differently based on property attributes.
+ *
+ * Two hard rules for this walk itself: it must be TOTAL (never throw
+ * anything but UnkeyableValueError) and SIDE-EFFECT-FREE (descriptor
+ * reads only; never invoke user code such as getters).
+ *
+ * Object keys sort recursively so `{a, b}` and `{b, a}` hash identically
+ * (design/13-security.md checklist #14 — cache key determinism; key order
+ * is deliberately NOT part of identity).
+ */
+
+import { createHash } from 'node:crypto';
+
+class UnkeyableValueError extends Error {}
+
+function canonicalize(value: unknown, seen: Set<object>): string {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isFinite(value)) throw new UnkeyableValueError('non-finite number');
+      // -0 is distinct: flight preserves it ("$-0"), and String(-0) would
+      // collapse it to "0" (codex review round 4 on PR #835).
+      return Object.is(value, -0) ? '-0' : String(value);
+    case 'object':
+      break;
+    case 'undefined':
+      // Distinct sentinel, NOT collapsed to null or omitted: flight
+      // serialization preserves `undefined` ("$undefined"), so a component
+      // can render [undefined] differently from [null] and {a: undefined}
+      // differently from {}. Bare `undefined` cannot collide with any
+      // other canonical output (strings are always quoted). Codex review
+      // round 3 on PR #835.
+      return 'undefined';
+    default:
+      // function, symbol, bigint
+      throw new UnkeyableValueError(`unsupported type: ${typeof value}`);
+  }
+  const obj = value as object;
+  // Any REPEATED reference — cycle or alias — is unkeyable. Flight
+  // preserves reference identity (the second occurrence serializes as a
+  // row reference), so a component can observe `props.a === props.b`;
+  // hashing an aliased shape identically to a structurally-equal
+  // non-aliased one could splice the wrong subtree (codex review round 5
+  // on PR #835). Objects are never removed from `seen`: revisiting one
+  // anywhere in the walk throws.
+  if (seen.has(obj)) throw new UnkeyableValueError('repeated object reference (cycle or alias)');
+  seen.add(obj);
+  // Hidden own properties — symbol keys and non-enumerable props — are
+  // readable by a live-rendered component but invisible to this walk, so
+  // two observably different inputs would collide on one key (codex
+  // review on PR #835). Unkeyable.
+  if (Object.getOwnPropertySymbols(obj).length > 0) {
+    throw new UnkeyableValueError('symbol-keyed property');
+  }
+  {
+    if (Array.isArray(obj)) {
+      // Dense-array own names are exactly ['0'..'n-1', 'length'] — anything
+      // else is a custom expando property this walk would silently drop.
+      if (Object.getOwnPropertyNames(obj).length !== obj.length + 1) {
+        throw new UnkeyableValueError('non-index array property');
+      }
+      const parts: string[] = [];
+      for (let i = 0; i < obj.length; i++) {
+        // Sparse holes are unkeyable: a server component receiving the
+        // original array can observe `i in arr`, which no canonical form
+        // survives faithfully. (An explicit undefined element is fine —
+        // handled by the sentinel above.)
+        const desc = Object.getOwnPropertyDescriptor(obj, i);
+        if (desc === undefined) throw new UnkeyableValueError('sparse array hole');
+        // Accessors are rejected WITHOUT invoking them — a getter may
+        // throw or side-effect, and the key walk must never alter a
+        // render (codex review on PR #835).
+        if (desc.get !== undefined || desc.set !== undefined) {
+          throw new UnkeyableValueError('accessor property');
+        }
+        // Non-enumerable elements are invisible to Object.keys/spread/
+        // JSON.stringify — the JSON projection would be ambiguous, same
+        // rule as the object branch's keys-vs-names check.
+        if (!desc.enumerable) throw new UnkeyableValueError('non-enumerable array element');
+        parts.push(canonicalize(desc.value, seen));
+      }
+      return '[' + parts.join(',') + ']';
+    }
+    // Allowlist: exactly Object.prototype. Dates, Maps, class instances —
+    // and null-prototype objects, which a component can distinguish from
+    // literals via Object.getPrototypeOf — are all outside the JSON
+    // domain.
+    if (Object.getPrototypeOf(obj) !== Object.prototype) {
+      throw new UnkeyableValueError('non-plain object');
+    }
+    const keys = Object.keys(obj).sort();
+    if (keys.length !== Object.getOwnPropertyNames(obj).length) {
+      throw new UnkeyableValueError('non-enumerable property');
+    }
+    const parts: string[] = [];
+    for (const key of keys) {
+      // Descriptor read, not property read: accessors are rejected WITHOUT
+      // invoking them — a getter may throw or side-effect, and the key
+      // walk must never alter a render (codex review on PR #835).
+      const desc = Object.getOwnPropertyDescriptor(obj, key)!;
+      if (desc.get !== undefined || desc.set !== undefined) {
+        throw new UnkeyableValueError('accessor property');
+      }
+      parts.push(JSON.stringify(key) + ':' + canonicalize(desc.value, seen));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+}
+
+/**
+ * Canonicalize a single value, or null if it is unkeyable. The ONE
+ * definition of "faithfully comparable" — every prebuilt code path that
+ * needs value equality (cache keys, slot-param divergence) goes through
+ * this, so the unkeyable rules (accessors, hidden props, aliases,
+ * bigints, …) live in exactly one place.
+ */
+export function tryCanonicalize(value: unknown): string | null {
+  try {
+    return canonicalize(value, new Set());
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+}
+
+/**
+ * Totality by construction: ANY throw from the walk means the input is
+ * outside the keyable domain. The walk touches only user-controlled
+ * values through reflection ops — and a Proxy trap can throw arbitrary
+ * errors from any of them (codex review on PR #835) — so converting only
+ * UnkeyableValueError would let hostile/exotic inputs abort a render
+ * that plain live rendering would have served fine. Unexpected error
+ * types are logged for visibility (they would indicate either a proxy
+ * trap or a canonicalizer bug) but still degrade to unkeyable.
+ */
+function toUnkeyable(error: unknown): null {
+  if (!(error instanceof UnkeyableValueError)) {
+    console.error(
+      '[timber] cache key canonicalization threw — treating input as unkeyable:',
+      error
+    );
+  }
+  return null;
+}
+
+/**
+ * Compute the cache-entry hash for a component render:
+ * `sha256({props, params}).slice(0, 16)` over canonical JSON.
+ *
+ * Returns null when props (or params) contain unkeyable values — the
+ * caller must fall back to dynamic rendering.
+ */
+export function computeComponentCacheKey(
+  props: Record<string, unknown>,
+  params: Record<string, string | string[]>
+): string | null {
+  let canonical: string;
+  try {
+    // One shared `seen` set: an object aliased between params and props is
+    // just as observable as one aliased within either.
+    const seen = new Set<object>();
+    // The params RECORD is framework-produced: coerceSegmentParams builds
+    // it with Object.create(null) as a prototype-pollution defense
+    // (design/13 checklist #36b), uniformly on every request — its
+    // prototype is an implementation detail, not user-observable input
+    // variation, so the record is normalized to a plain object before the
+    // walk (codex P1 on PR #835: rejecting it made every real request
+    // unkeyable). Nested VALUES still face the full allowlist, and user
+    // props stay strict — a null-prototype prop object remains unkeyable.
+    canonical =
+      '{"params":' +
+      canonicalize({ ...params }, seen) +
+      ',"props":' +
+      canonicalize(props, seen) +
+      '}';
+  } catch (error) {
+    return toUnkeyable(error);
+  }
+  // NOTE(hash choice — DECIDED, TIM-1119): 64 bits of truncated sha256 is
+  // the SHIPPED artifact format; the capture pass writes .flight files and
+  // manifest entries named by this hash, so changing the width is now a
+  // build-artifact format break. The width is adequate: entries are
+  // namespaced per component AND per deploy, so birthday odds need ~2^32
+  // entries under ONE component to matter, and design/13 #24 already
+  // accepts 64-bit non-crypto FNV-1a for data-cache keys on the same
+  // namespacing argument. Only revisit (with a format migration) if the
+  // phase-3 runtime tier ever stores attacker-influenced keys more
+  // aggressively.
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/src/server/prebuilt/capture-state.ts

@@ -0,0 +1,89 @@
+/**
+ * Build-time capture state — the channel between the post-build capture
+ * pass (server/prebuilt-builder.ts) and the `__prebuilt` wrapper
+ * (server/prebuilt-runtime.ts).
+ *
+ * During capture, a wrapped component's subtree may render OTHER wrapped
+ * components. With no payload source registered (the capture pass runs
+ * before artifacts exist), those inner wrappers render live and their
+ * output is baked flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The capture
+ * pass is the designated detection point for that clamp, so the wrapper
+ * reports every render that happens while a capture is active:
+ *
+ * - **Cycle**: the inner wrapper IS the component being captured (directly
+ *   or transitively — the transitive case still renders the outer's own
+ *   wrapper, so the identity check catches both). Left alone this recurses
+ *   until the render times out; instead the wrapper throws
+ *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
+ *   the cycle while the build continues (doc 44 skip-and-report policy).
+ * - **Nesting**: any other wrapper render is recorded as an (outer, inner)
+ *   pair. The builder warns after the entry completes when the inner
+ *   declares a refresh channel the outer cannot honor (doc 45 clamp rule).
+ *
+ * Captures run strictly sequentially (one entry at a time), so a single
+ * module-level slot is sufficient — there is never a second active capture
+ * to confuse renders between. At request time `active` is null and
+ * `noteWrapperRender` is a single null-check.
+ */
+
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.js';
+
+/** A wrapped component that rendered inside an active capture. */
+export interface NestedWrapperRender {
+  innerId: string;
+  options: PrebuiltComponentOptions;
+}
+
+/** Thrown by the wrapper when a capture renders its own component. */
+export class PrebuiltCaptureCycleError extends Error {
+  constructor(componentId: string) {
+    super(
+      `[timber] cache.component "${componentId}" renders itself (directly or through ` +
+        `other components) — prerendering it would recurse forever. Remove the cycle ` +
+        `or drop { prerender: true } on this component.`
+    );
+    this.name = 'PrebuiltCaptureCycleError';
+  }
+}
+
+let active: { outerId: string; nested: Map<string, PrebuiltComponentOptions> } | null = null;
+
+/**
+ * Mark a capture as active. The builder calls this immediately before
+ * rendering an entry and MUST pair it with `endCapture()` in a finally.
+ */
+export function beginCapture(outerId: string): void {
+  active = { outerId, nested: new Map() };
+}
+
+/**
+ * End the active capture and return the wrapped components that rendered
+ * inside it (first options object wins per inner ID).
+ */
+export function endCapture(): NestedWrapperRender[] {
+  const nested = active?.nested;
+  active = null;
+  if (!nested) return [];
+  return Array.from(nested, ([innerId, options]) => ({ innerId, options }));
+}
+
+/** Whether a build-time capture is currently rendering. */
+export function isCaptureActive(): boolean {
+  return active !== null;
+}
+
+/**
+ * Called by the `__prebuilt` wrapper on every render. No-op unless a
+ * capture is active. Throws `PrebuiltCaptureCycleError` when the wrapper
+ * belongs to the component currently being captured.
+ */
+export function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions): void {
+  if (active === null) return;
+  if (innerId === active.outerId) {
+    throw new PrebuiltCaptureCycleError(innerId);
+  }
+  if (!active.nested.has(innerId)) {
+    active.nested.set(innerId, options);
+  }
+}

package/src/server/prebuilt/manifest-tag-index.ts

@@ -0,0 +1,46 @@
+/**
+ * Manifest tag index — maps tags to seed cache keys for tombstone writes.
+ *
+ * When `revalidateTag(tag)` fires, the framework must write tombstones for
+ * every build-seed entry carrying that tag. The manifest records tags per
+ * entry; this module inverts the index at startup so the lookup is O(1) per
+ * tag instead of a full manifest scan per invalidation.
+ *
+ * The index is built lazily on first access and cached for the process
+ * lifetime — the manifest is immutable within a deploy.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+
+import type { PrebuiltManifest } from './payload-source.js';
+
+export interface SeedKeyInfo {
+  componentId: string;
+  cacheKey: string;
+}
+
+/**
+ * Build the inverted tag → seed key index from the manifest.
+ *
+ * Returns a Map where each tag maps to the set of (componentId, cacheKey)
+ * pairs whose manifest entries carry that tag. Only entries with non-empty
+ * `tags` arrays participate.
+ */
+export function buildTagIndex(manifest: PrebuiltManifest): Map<string, SeedKeyInfo[]> {
+  const index = new Map<string, SeedKeyInfo[]>();
+  for (const [componentId, component] of Object.entries(manifest)) {
+    if (!component || typeof component !== 'object' || !('entries' in component)) continue;
+    for (const [cacheKey, entry] of Object.entries(component.entries)) {
+      if (!entry.tags || entry.tags.length === 0) continue;
+      for (const tag of entry.tags) {
+        let list = index.get(tag);
+        if (!list) {
+          list = [];
+          index.set(tag, list);
+        }
+        list.push({ componentId, cacheKey });
+      }
+    }
+  }
+  return index;
+}