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

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

package/src/server/prebuilt/overlay.ts

@@ -0,0 +1,256 @@
+/**
+ * Component cache overlay — runtime CacheHandler layer for ISR.
+ *
+ * Sits in front of the immutable build artifact (`.flight` files) and
+ * stores replacement payloads and tombstones via the configured
+ * CacheHandler. Overlay entries are per-deploy namespaced:
+ *   `timber:c:{deploymentId}:{componentId}:{hash}`
+ *
+ * The CacheHandler contract is untouched — tombstones and the tag index
+ * live above the interface as value conventions. Redis, KV, and custom
+ * handlers work unmodified.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+
+import { getCacheHandler, isCacheHandlerConfigured } from '../../cache/handler-store.js';
+import { MemoryCacheHandler } from '../../cache/index.js';
+import { getDeploymentId } from '../version-skew.js';
+import { buildTagIndex, type SeedKeyInfo } from './manifest-tag-index.js';
+import type { PrebuiltManifest } from './payload-source.js';
+import { ensureManifestLoaded } from './payload-source.js';
+
+/** Default ceiling TTL for tag-only entries (24 hours), in seconds. */
+const CEILING_TTL_SECONDS = 24 * 60 * 60;
+
+/** Deploy-long physical TTL for seed-backed overlay records (90 days). */
+const DEPLOY_LONG_TTL_SECONDS = 90 * 24 * 60 * 60;
+
+// ─── Overlay record shapes (value conventions above CacheHandler) ────────
+
+/**
+ * A cached component flight payload stored in the overlay.
+ * The `_t` discriminant distinguishes this from a tombstone.
+ */
+export interface ComponentOverlayRecord {
+  _t: 'co';
+  /** Base64-encoded flight payload bytes. */
+  p: string;
+  /** Logical freshness deadline (Date.now() + ttl * 1000). */
+  fu: number;
+  /** Whether a build-artifact seed exists for this key. */
+  s: boolean;
+}
+
+/**
+ * A tombstone marking a build seed as invalidated.
+ * Written by revalidateTag for seeds carrying the invalidated tag.
+ */
+export interface ComponentTombstoneRecord {
+  _t: 'ct';
+}
+
+type OverlayValue = ComponentOverlayRecord | ComponentTombstoneRecord;
+
+export function isOverlayRecord(v: unknown): v is ComponentOverlayRecord {
+  return v !== null && typeof v === 'object' && (v as Record<string, unknown>)._t === 'co';
+}
+
+export function isTombstone(v: unknown): v is ComponentTombstoneRecord {
+  return v !== null && typeof v === 'object' && (v as Record<string, unknown>)._t === 'ct';
+}
+
+// ─── Overlay key generation ──────────────────────────────────────────────
+
+export function overlayKey(componentId: string, cacheKey: string): string {
+  const deploymentId = getDeploymentId() ?? 'dev';
+  return `timber:c:${deploymentId}:${componentId}:${cacheKey}`;
+}
+
+// ─── Overlay read ────────────────────────────────────────────────────────
+
+export interface OverlayLookupResult {
+  kind: 'fresh' | 'stale' | 'tombstone';
+  /** The overlay value (null for tombstones). */
+  record: ComponentOverlayRecord | null;
+  /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
+  payload: Uint8Array | null;
+}
+
+/**
+ * Look up an overlay entry in the cache handler.
+ * Returns null on a clean miss (no overlay entry at all).
+ */
+export async function lookupOverlay(
+  componentId: string,
+  cacheKey: string
+): Promise<OverlayLookupResult | null> {
+  const handler = getCacheHandler();
+  const key = overlayKey(componentId, cacheKey);
+  const result = await handler.get(key);
+  if (!result) return null;
+
+  const value = result.value as OverlayValue;
+  if (isTombstone(value)) {
+    return { kind: 'tombstone', record: null, payload: null };
+  }
+  if (isOverlayRecord(value)) {
+    const logicallyStale = Date.now() > value.fu;
+    return {
+      kind: logicallyStale ? 'stale' : 'fresh',
+      record: value,
+      payload: base64ToBytes(value.p),
+    };
+  }
+  // Unknown value shape — treat as miss (forward compatibility).
+  return null;
+}
+
+// ─── Overlay write ───────────────────────────────────────────────────────
+
+/**
+ * Resolve the effective TTL for a component's runtime lifetime.
+ * Tag-only entries (no explicit ttl) get the ceiling TTL (design/45
+ * §Tag-only entries carry a ceiling TTL).
+ */
+export function effectiveTtl(ttl: number | undefined): number {
+  return ttl ?? CEILING_TTL_SECONDS;
+}
+
+/**
+ * Store a component flight payload in the overlay.
+ */
+export async function storeOverlayEntry(
+  componentId: string,
+  cacheKey: string,
+  payloadBytes: Uint8Array,
+  opts: {
+    ttl?: number;
+    tags: string[];
+    hasSeed: boolean;
+  }
+): Promise<void> {
+  const handler = getCacheHandler();
+  const key = overlayKey(componentId, cacheKey);
+  const logicalTtl = effectiveTtl(opts.ttl);
+  const physicalTtl = opts.hasSeed ? DEPLOY_LONG_TTL_SECONDS : logicalTtl;
+
+  const record: ComponentOverlayRecord = {
+    _t: 'co',
+    p: bytesToBase64(payloadBytes),
+    fu: Date.now() + logicalTtl * 1000,
+    s: opts.hasSeed,
+  };
+
+  await handler.set(key, record, { ttl: physicalTtl, tags: opts.tags });
+}
+
+// ─── Tombstone writes ────────────────────────────────────────────────────
+
+let tagIndex: Map<string, SeedKeyInfo[]> | null = null;
+
+/**
+ * Initialize the tag index from the prebuilt manifest. Called once when the
+ * manifest is loaded. Without a manifest (no prebuilt components), this is
+ * never called and revalidateTag skips the tombstone path entirely.
+ */
+export function initTagIndex(manifest: PrebuiltManifest): void {
+  tagIndex = buildTagIndex(manifest);
+  emitIsrDiagnosticIfNeeded(manifest);
+}
+
+/**
+ * Get the tag index, if initialized.
+ * @internal — exported for testing.
+ */
+export function getTagIndex(): Map<string, SeedKeyInfo[]> | null {
+  return tagIndex;
+}
+
+/**
+ * Reset the tag index (for tests).
+ * @internal
+ */
+export function resetTagIndex(): void {
+  tagIndex = null;
+}
+
+/**
+ * Write tombstones for all seed entries carrying the given tag.
+ * Called from cache.invalidate (cache-api.ts) AFTER the handler's own
+ * invalidation clears overlay entries.
+ *
+ * The tombstone prevents the immutable seed from being served after
+ * invalidation — without it, a handler.invalidate that clears the overlay
+ * would expose the (now-stale) build artifact on the next request.
+ *
+ * Ensures the manifest is loaded first so cold-process actions that
+ * invalidate before any page render still write tombstones.
+ */
+export async function writeTombstonesForTag(tag: string): Promise<void> {
+  if (!tagIndex) {
+    await ensureManifestLoaded();
+  }
+  if (!tagIndex) return;
+  const seeds = tagIndex.get(tag);
+  if (!seeds || seeds.length === 0) return;
+
+  const handler = getCacheHandler();
+  const tombstone: ComponentTombstoneRecord = { _t: 'ct' };
+
+  await Promise.all(
+    seeds.map((seed) => {
+      const key = overlayKey(seed.componentId, seed.cacheKey);
+      return handler.set(key, tombstone, {
+        ttl: DEPLOY_LONG_TTL_SECONDS,
+        tags: [tag],
+      });
+    })
+  );
+}
+
+// ─── ISR build diagnostic ────────────────────────────────────────────────
+
+let isrDiagnosticEmitted = false;
+
+function emitIsrDiagnosticIfNeeded(manifest: PrebuiltManifest): void {
+  if (isrDiagnosticEmitted) return;
+
+  const handler = getCacheHandler();
+  const isMemoryBased = handler instanceof MemoryCacheHandler || !isCacheHandlerConfigured();
+  if (!isMemoryBased) return;
+
+  for (const [, component] of Object.entries(manifest)) {
+    if (!component || typeof component !== 'object' || !('entries' in component)) continue;
+    for (const [, entry] of Object.entries(component.entries)) {
+      if (entry.tags && entry.tags.length > 0) {
+        isrDiagnosticEmitted = true;
+        console.warn(
+          '[timber] tag revalidation of prerendered components requires a shared cache ' +
+            'handler in multi-instance deployments. The current MemoryCacheHandler is ' +
+            'per-process — revalidateTag on one instance will not purge the build seed ' +
+            'on others. Configure a shared handler (Redis, KV) for production ISR.'
+        );
+        return;
+      }
+    }
+  }
+}
+
+/**
+ * Reset the diagnostic flag (for tests).
+ * @internal
+ */
+export function resetIsrDiagnostic(): void {
+  isrDiagnosticEmitted = false;
+}
+
+// ─── Encoding helpers ────────────────────────────────────────────────────
+
+function bytesToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64'));
+}