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

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.ts';
+import { MemoryCacheHandler } from '../../cache/index.ts';
+import { getDeploymentId } from '../version-skew.ts';
+import { buildTagIndex, type SeedKeyInfo } from './manifest-tag-index.ts';
+import type { PrebuiltManifest } from './payload-source.ts';
+import { ensureManifestLoaded } from './payload-source.ts';
+
+/** 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'));
+}

package/src/server/prebuilt/payload-source.ts

@@ -0,0 +1,202 @@
+/**
+ * Prebuilt payload source — the adapter seam through which the runtime
+ * reads build-time flight artifacts (`.timber/dist/prebuilt/`).
+ *
+ * The runtime never touches the filesystem directly: adapters register a
+ * source at startup (Node: fs reads; Cloudflare: the assets binding —
+ * design/44-render-at-build-time.md §Adapter Integration). Artifacts are
+ * produced by the post-build capture pass (TIM-1119, prebuilt-builder.ts);
+ * adapter registration of the source is TIM-1122. Until a source is
+ * registered (adapter not wired yet, dev mode, no artifacts built), every
+ * lookup misses and cache.component wrappers render live — the designed
+ * dynamic-fallback behavior.
+ *
+ * Phase 3 (design/45 runtime tier) inserts the CacheHandler overlay lookup
+ * in front of `lookupPrebuiltPayload` — overlay first, then artifact. The
+ * single-lookup-function shape here is that seam.
+ */
+
+import { initTagIndex, resetTagIndex } from './overlay.ts';
+import type { CoercedParams } from '../../shared/param-value.ts';
+
+export interface PrebuiltManifestEntry {
+  /** Segment params this entry was captured under. */
+  params: CoercedParams;
+  /** Payload path relative to the prebuilt/ directory. */
+  file: string;
+  /** Payload size in bytes (build report / diagnostics). */
+  bytes?: number;
+  /** Runtime invalidation tags (design/45 ISR tier). */
+  tags?: string[];
+  /** Epoch ms when this entry was captured (seed freshness for ISR). */
+  buildTimestamp?: number;
+}
+
+export interface PrebuiltManifest {
+  [componentId: string]: {
+    entries: Record<string, PrebuiltManifestEntry>;
+    /** When true, the component does not read segment params — the cache key uses `{}`. */
+    paramIndependent?: boolean;
+  };
+}
+
+export interface PrebuiltPayloadSource {
+  /** Load prebuilt/manifest.json. Null when no artifacts exist. */
+  loadManifest(): Promise<PrebuiltManifest | null>;
+  /** Read a `.flight` payload by manifest file path. Null when missing. */
+  readPayload(file: string): Promise<Uint8Array | null>;
+}
+
+let source: PrebuiltPayloadSource | null = null;
+let manifestPromise: Promise<PrebuiltManifest | null> | null = null;
+
+/**
+ * Ceiling on the memoized manifest load. Without it, a stalled
+ * `loadManifest()` would leave `manifestPromise` pending forever and every
+ * subsequent cache.component render would await the same hung promise —
+ * the coalesced-promise deadlock class from design/13-security.md (A5).
+ * On expiry the load memoizes as null (permanent dynamic fallback, same
+ * policy as a failed load) and callers proceed immediately.
+ */
+const MANIFEST_LOAD_TIMEOUT_MS = 5_000;
+
+/**
+ * Per-read ceiling on payload reads. The read is awaited inside a server
+ * component render — a stalled adapter promise would otherwise hang the
+ * RSC stream until the render timeout kills the whole page, when the
+ * correct degradation is a miss → live render (codex review round 4 on
+ * PR #835).
+ */
+const PAYLOAD_READ_TIMEOUT_MS = 5_000;
+
+/** Race a source promise against a timeout that resolves to `fallback`. */
+async function withTimeout<T>(
+  work: Promise<T>,
+  timeoutMs: number,
+  fallback: T,
+  onTimeout: () => void
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise<T>((resolve) => {
+        timer = setTimeout(() => {
+          onTimeout();
+          resolve(fallback);
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function loadManifestWithTimeout(
+  src: PrebuiltPayloadSource
+): Promise<PrebuiltManifest | null> {
+  let manifest: PrebuiltManifest | null;
+  try {
+    manifest = await withTimeout(src.loadManifest(), MANIFEST_LOAD_TIMEOUT_MS, null, () => {
+      console.error(
+        `[timber] prebuilt manifest load exceeded ${MANIFEST_LOAD_TIMEOUT_MS}ms — all cache.component lookups will render dynamically`
+      );
+    });
+  } catch (error) {
+    console.error(
+      '[timber] failed to load prebuilt manifest — all cache.component lookups will miss:',
+      error
+    );
+    return null;
+  }
+  if (manifest) {
+    initTagIndex(manifest);
+  }
+  return manifest;
+}
+
+/**
+ * Register the payload source. Called once at server startup by the
+ * adapter/entry wiring (TIM-1122); tests inject fakes. Passing null
+ * unregisters (and drops the memoized manifest).
+ */
+export function setPrebuiltPayloadSource(next: PrebuiltPayloadSource | null): void {
+  source = next;
+  manifestPromise = null;
+  if (!next) resetTagIndex();
+}
+
+/**
+ * Whether a source is registered — the gate for both marker emission and
+ * splice-transform installation. False means zero prebuilt overhead.
+ */
+export function hasPrebuiltPayloadSource(): boolean {
+  return source !== null;
+}
+
+/**
+ * Ensure the manifest is loaded (and the tag index initialized). No-op
+ * when no source is registered. Used by the tombstone path to avoid
+ * skipping tombstones on cold processes where the first request is an
+ * action rather than a page render.
+ */
+export async function ensureManifestLoaded(): Promise<void> {
+  if (source === null) return;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  await manifestPromise;
+}
+
+/**
+ * Look up a manifest entry (metadata only, no payload read).
+ * Used by the overlay to check seed existence and freshness.
+ */
+export async function isParamIndependent(componentId: string): Promise<boolean> {
+  if (source === null) return false;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  return manifest?.[componentId]?.paramIndependent === true;
+}
+
+export async function getManifestEntry(
+  componentId: string,
+  cacheKey: string
+): Promise<PrebuiltManifestEntry | null> {
+  if (source === null) return null;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  return manifest?.[componentId]?.entries?.[cacheKey] ?? null;
+}
+
+/**
+ * Look up a cached payload: manifest entry → payload bytes.
+ * Null on any miss or read failure — callers fall back to live render.
+ *
+ * The manifest is loaded once and memoized (design/44 §manifest.json:
+ * loaded at startup, held in memory; payloads read on demand). A failed
+ * manifest load is memoized as null rather than retried per-request — a
+ * broken artifact should degrade to dynamic rendering, not add a failing
+ * read to every request.
+ */
+export async function lookupPrebuiltPayload(
+  componentId: string,
+  cacheKey: string
+): Promise<Uint8Array | null> {
+  if (source === null) return null;
+  manifestPromise ??= loadManifestWithTimeout(source);
+  const manifest = await manifestPromise;
+  const entry = manifest?.[componentId]?.entries?.[cacheKey];
+  if (!entry) return null;
+  try {
+    return await withTimeout(source.readPayload(entry.file), PAYLOAD_READ_TIMEOUT_MS, null, () => {
+      console.error(
+        `[timber] prebuilt payload read for "${entry.file}" exceeded ${PAYLOAD_READ_TIMEOUT_MS}ms — rendering dynamically`
+      );
+    });
+  } catch (error) {
+    console.error(
+      `[timber] failed to read prebuilt payload "${entry.file}" for ${componentId} — rendering dynamically:`,
+      error
+    );
+    return null;
+  }
+}

package/src/server/prebuilt/slots.ts

@@ -0,0 +1,202 @@
+/**
+ * Slot-component helpers for cache.component (TIM-1173).
+ *
+ * A `slots: ['children', ...]` declaration caches the component's output
+ * as a shell with a stable <SlotOutlet slot={name} /> client-reference
+ * hole per declared slot prop; live slot content composes in per instance
+ * at request time via SlotsProvider/SlotContext. This generalizes the
+ * TIM-1181 layout mechanism to explicitly declared, named slots on any
+ * cached component. Layouts use the same mechanism with a `children` slot.
+ *
+ * Both the production wrapper (cache path) and the dev wrapper (no cache,
+ * same tree shape for dev/prod parity) build their render from these
+ * helpers. See design/45-cache-lifetimes.md §Slot Components.
+ */
+
+import { createElement } from 'react';
+
+import type { SlotValues } from '../../client/slot-context.ts';
+import { SlotOutlet } from '../../client/slot-outlet.tsx';
+import { SlotsProvider } from '../../client/slot-provider.tsx';
+import { splitSlotProps } from './cache-key.ts';
+import { hasRuntimeLifetime } from './lifetime.ts';
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+
+/**
+ * Framework-internal slot name for layout children. Uses a prefix that
+ * cannot collide with user-declared slot names (which are React prop
+ * names). Layout children flow through SlotsProvider/SlotOutlet with
+ * this key instead of the bare "children" key, so a cached component
+ * with `slots: ['children']` inside a layout never shadows the layout's
+ * own children delivery.
+ *
+ * Defined here (a server module) rather than in `client/slot-context.ts`
+ * (`'use client'`) because RSC's client-reference proxying would replace
+ * the string value with a proxy object in the server environment. The
+ * client-side SlotOutlet receives this value via props, so it doesn't
+ * need the constant. See TIM-1191.
+ */
+export const LAYOUT_CHILDREN_SLOT = '\0timber:children';
+
+/**
+ * Is this value the framework-injected layout children slot outlet
+ * (`<SlotOutlet slot={LAYOUT_CHILDREN_SLOT} />`)? Layout components
+ * receive this as their `children` prop — a stable client reference
+ * whose cache key is stripped so layout `cache.component` hits work
+ * (design/45 §Layout Propagation).
+ *
+ * Uses a framework-reserved slot name (LAYOUT_CHILDREN_SLOT) that
+ * cannot collide with user-declared slot names, preventing context
+ * shadowing when a cached component with its own SlotsProvider is
+ * nested inside a layout. See TIM-1191.
+ *
+ * Total: the probes run against a user-controlled value, and a Proxy
+ * trap can throw — that must classify as "not the outlet" (the
+ * canonicalizer then rejects the value as unkeyable → live render), not
+ * abort the request (codex P2 on PR #890).
+ */
+export function isChildrenSlotOutletElement(value: unknown): boolean {
+  try {
+    if (value == null || typeof value !== 'object') return false;
+    if (!('type' in value)) return false;
+    const el = value as { type: unknown; props?: { slot?: unknown } };
+    return el.type === SlotOutlet && el.props?.slot === LAYOUT_CHILDREN_SLOT;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `props` without the framework-injected children outlet — the key props
+ * of a render. The outlet is the same client reference on every request,
+ * so it never varies the cache key; user-provided children stay (and
+ * leave the props unkeyable). See design/45 §Layout Propagation, TIM-1181.
+ */
+export function withoutChildrenOutlet(props: Record<string, unknown>): Record<string, unknown> {
+  if (!isChildrenSlotOutletElement(props.children)) return props;
+  const { children: _children, ...rest } = props;
+  return rest;
+}
+
+/**
+ * Outcome of validating a `slots` declaration at registration time.
+ *
+ * - `none` — not declared (or an empty array): plain non-slot component.
+ * - `disabled` — declared but unusable (malformed shape, or missing the
+ *   required runtime lifetime): warned once here (module load); the
+ *   component falls back WHOLESALE to non-slot semantics — the caller
+ *   strips `slots` from the options and every other option (including
+ *   `prerender`) keeps its normal meaning. Safe by construction:
+ *   element-valued props are unkeyable on the non-slot path, so renders
+ *   with slot content go live. Slower, never wrong.
+ * - `active` — usable slot names.
+ */
+export type SlotResolution = { kind: 'none' | 'disabled' } | { kind: 'active'; slots: string[] };
+
+/**
+ * Dense array of non-empty strings — no holes, no non-string entries.
+ * Total: the reads run against a user-controlled value at module load,
+ * and a throwing Proxy trap must classify as invalid, not crash startup.
+ */
+function isDenseStringArray(value: unknown): value is string[] {
+  try {
+    if (!Array.isArray(value)) return false;
+    for (let i = 0; i < value.length; i++) {
+      if (!Object.hasOwn(value, i)) return false; // sparse hole
+      const entry: unknown = value[i];
+      if (typeof entry !== 'string' || entry.length === 0) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate the `slots` option. Both the production and dev wrappers gate
+ * on this — slot substitution is active in dev exactly when it would be
+ * active in production, so the tree shape a component sees never
+ * diverges between the two.
+ */
+export function resolveSlotNames(id: string, options: PrebuiltComponentOptions): SlotResolution {
+  const slots = options.slots;
+  if (slots === undefined) return { kind: 'none' };
+  // Shape first — a non-array (null, object, …) must not reach a .length
+  // or iteration and crash module load over an option typo. Explicit
+  // index walk with Object.hasOwn: Array.prototype.every skips sparse
+  // holes, which would let `slots[1] = 'children'` on an empty array pass
+  // as active and flow an undefined slot into the shell (codex P2 on
+  // PR #890).
+  if (!isDenseStringArray(slots)) {
+    console.warn(
+      `[timber] cache.component "${id}": invalid slots declaration — expected ` +
+        `an array of non-empty prop-name strings. Slot caching is disabled.`
+    );
+    return { kind: 'disabled' };
+  }
+  if (slots.length === 0) return { kind: 'none' };
+  if (!hasRuntimeLifetime(options)) {
+    console.warn(
+      `[timber] cache.component "${id}": slots require a runtime lifetime ` +
+        `(ttl and/or tags). Slot caching is disabled.`
+    );
+    return { kind: 'disabled' };
+  }
+  return { kind: 'active', slots };
+}
+
+export interface SlotRender {
+  /** Props the shell renders with: data props + a SlotOutlet per slot. */
+  shellProps: Record<string, unknown>;
+  /** Non-slot props — the only props that participate in the cache key. */
+  dataProps: Record<string, unknown>;
+  /** Live slot content, keyed by slot name, for the SlotsProvider. */
+  slotValues: Record<string, unknown>;
+}
+
+/**
+ * Split the live props into the cacheable shell render (data props plus a
+ * deterministic SlotOutlet placeholder per declared slot — identical
+ * whether or not the caller passed the slot) and the per-instance live
+ * slot values.
+ *
+ * Null when the props object itself is unkeyable at the top level
+ * (accessors, hidden properties, exotic prototype — see splitSlotProps):
+ * the caller must render live with the original props.
+ */
+export function prepareSlotRender(
+  props: Record<string, unknown>,
+  slots: readonly string[]
+): SlotRender | null {
+  const split = splitSlotProps(props ?? {}, slots);
+  if (split === null) return null;
+  const { dataProps, slotValues } = split;
+  // Spread + defineProperty, not assignment: a slot named `__proto__`
+  // must become an own property, not mutate the shell props' prototype
+  // (spread uses CreateDataProperty, so it is already safe).
+  const shellProps: Record<string, unknown> = { ...dataProps };
+  for (const slot of slots) {
+    Object.defineProperty(shellProps, slot, {
+      value: createElement(SlotOutlet, { slot }),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return { shellProps, dataProps, slotValues };
+}
+
+/**
+ * Wrap a rendered shell (revived payload or live element) in a
+ * per-instance SlotsProvider feeding the live values to its outlets.
+ */
+export function wrapInSlotsProvider(
+  shell: unknown,
+  slotValues: Record<string, unknown>
+): React.ReactElement {
+  // children passed as a prop, not a JSX child — the shell is `unknown`
+  // to the type system. Same pattern as route-element-builder's `h` alias
+  // for SlotsProvider.
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+  return h(SlotsProvider, { values: slotValues as SlotValues, children: shell });
+}