@lumencast/runtime 0.7.0 → 0.9.0

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { ErrorCode } from "@lumencast/protocol";
+import type { ResolveCaptureDevice } from "./render/primitives/capture";
 export type LumencastMode = "broadcast" | "control" | "test";
 export type LumencastStatus = "disconnected" | "connecting" | "live";
 export interface LumencastTokenProvider {
@@ -53,6 +54,15 @@ export interface MountOptions {
      *  logs — `broadcast` builds stay console-silent. When omitted, the
      *  runtime falls back to a DEV-only console.warn. */
     onDiagnostic?: (diagnostic: LumencastDiagnostic) => void;
+    /** ADR 004 §A1.3 — host resolver for the `x-zab.capture` primitive's ACQUIRE
+     *  mode. Given the LOGICAL `(deviceRef, sourceKind)` from the bundle, return
+     *  `{ deviceId }` to pin a physical device, or `null` for the host's default
+     *  device. The runtime passes `deviceId` only as a live `getUserMedia`
+     *  constraint — it NEVER enters the bundle or the content hash. Omit it and
+     *  ACQUIRE uses the default device ("the cam traverses"), never throwing.
+     *  Only consulted on a capture-capable host (e.g. the Electron preview
+     *  webview) ; ignored on-air (CEF/Pulsar render the placeholder). */
+    resolveCaptureDevice?: ResolveCaptureDevice;
 }
 export interface LumencastHandle {
     /** Tear down the WS, unmount the React tree, release timers. Idempotent. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,eAAe,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;+BAE+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C;;;yDAGqD;IACrD,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,eAAe,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;+BAE+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C;;;yDAGqD;IACrD,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACzD;;;;;;;yEAOqE;IACrE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Browser runtime for Lumencast — mount(), LSDP/1 transport, leaf-grain store, LSML render, animations, overlays.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,7 +36,7 @@
     "framer-motion": "^12.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@lumencast/protocol": "0.7.0"
+    "@lumencast/protocol": "0.9.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
@@ -50,8 +50,8 @@
     "vite-plugin-dts": "^4.5.0",
     "vitest": "^4.1.5",
     "ws": "^8.18.0",
-    "@lumencast/dev-server": "0.7.0",
-    "@lumencast/server": "0.7.0"
+    "@lumencast/server": "0.9.0",
+    "@lumencast/dev-server": "0.9.0"
   },
   "scripts": {
     "dev": "vite",
@@ -60,6 +60,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
-    "check:bundle": "node scripts/check-bundle-size.mjs"
+    "check:bundle": "node scripts/check-bundle-size.mjs",
+    "check:no-fetch": "node scripts/check-no-fetch.mjs"
   }
 }

package/src/animate/keyframes.ts

@@ -151,7 +151,14 @@ function pullTransform(
     if (prop === "rotate") {
       out.rotate = values.map((n) => `${n}deg`);
     } else {
-      out[prop] = values;
+      // ADR 011 I7 live-bug fix (2nd half): framer-motion animates transform
+      // through its shorthand motion keys `x`/`y`, NOT `translateX`/`translateY`
+      // — emitting the authored names verbatim left framer with unknown keys
+      // it silently dropped, so the box never translated at the antenna (only
+      // the opacity fade survived). Map the translate channels onto the framer
+      // keys. `scale`/`rotate` already match framer's vocabulary.
+      const framerKey = prop === "translateX" ? "x" : prop === "translateY" ? "y" : prop;
+      out[framerKey] = values;
     }
   }
 }

package/src/app.tsx

@@ -18,6 +18,7 @@ import type { Store } from "./state/store.js";
 import type { RenderBundle } from "./render/bundle.js";
 import type { ConnectionStatus } from "./transport/ws.js";
 import { LumencastRuntimeProvider } from "./overlay/runtime-context.js";
+import type { ResolveCaptureDevice } from "./render/primitives/capture.js";
 import type { LumencastMode } from "./types.js";
 
 const LazyBroadcastMode = lazy(() =>
@@ -35,6 +36,8 @@ export interface LumencastAppProps {
   statusSignal: Signal<ConnectionStatus>;
   crossfadeKeySignal: Signal<string>;
   sendInput: (patches: Patch[]) => void;
+  /** ADR 004 §A1.3 — host resolver for `x-zab.capture` ACQUIRE mode. */
+  resolveCaptureDevice?: ResolveCaptureDevice;
 }
 
 export function LumencastApp({
@@ -44,6 +47,7 @@ export function LumencastApp({
   statusSignal,
   crossfadeKeySignal,
   sendInput,
+  resolveCaptureDevice,
 }: LumencastAppProps) {
   useSignals();
 
@@ -72,6 +76,7 @@ export function LumencastApp({
             bundle,
             status,
             sendInput,
+            ...(resolveCaptureDevice !== undefined ? { resolveCaptureDevice } : {}),
           }}
         >
           <Suspense fallback={null}>

package/src/index.ts

@@ -26,6 +26,11 @@ export {
 } from "./render/diagnostics.js";
 export { PRIMITIVE_PROP_ALLOWLIST } from "./render/prop-allowlist.js";
 
+// ADR 004 §A1.3 — host resolver type for the `x-zab.capture` ACQUIRE mode,
+// supplied via `MountOptions.resolveCaptureDevice`. Exported so the consuming
+// app (Prism/Solar) types its injected resolver against the runtime's contract.
+export type { ResolveCaptureDevice } from "./render/primitives/capture.js";
+
 // Bundle types are useful for hosts that want to typecheck pre-compiled scenes.
 export type {
   RenderBundle,
@@ -46,3 +51,27 @@ export {
   isAuthoringProfile,
   validateBundleProfiles,
 } from "./render/bundle.js";
+
+// Headless render (ADR 003) — render an already-compiled RenderBundle into a
+// live DOM node, no WS, ready when layout + fonts settle. Hosts (Solar headless
+// entry, ZabCanvas render worker, the zero-loss harness) screenshot the target
+// once `ready` resolves. The runtime does DOM + readiness only — no fetch, no
+// screenshot. Dynamically pulls BroadcastMode so it adds no eager weight to the
+// `mount`/broadcast path (RC6).
+export { renderBundleHeadless } from "./render/headless.js";
+export type { HeadlessRenderOptions, HeadlessRenderHandle } from "./render/headless.js";
+
+// Asset / font resolution helpers for headless hosts (ADR 003 §3.2). No-fetch:
+// they only rewrite a bundle's `src`s against a caller table and load fonts
+// from caller-supplied `data:` URIs. The host-allow gate stays the sole
+// authority. (`FontFace` is the public type name per ADR 003 RC5; it is the
+// spec object — distinct from the DOM `FontFace` constructor.)
+export {
+  resolveSrc,
+  rewriteLayoutSrcs,
+  rewriteDefaultsSrcs,
+  injectFonts,
+  type AssetTable,
+  type FontFaceSpec,
+  type FontFaceSpec as FontFace,
+} from "./render/asset-resolve.js";

package/src/mount.ts

@@ -118,6 +118,11 @@ export function mount(options: MountOptions): LumencastHandle {
       statusSignal,
       crossfadeKeySignal,
       sendInput: (patches) => ws.sendInput(patches),
+      // ADR 004 §A1.3 — thread the host capture resolver to the runtime context
+      // so the `x-zab.capture` primitive's ACQUIRE mode can pin a device.
+      ...(options.resolveCaptureDevice !== undefined
+        ? { resolveCaptureDevice: options.resolveCaptureDevice }
+        : {}),
     }),
   );
 

package/src/overlay/runtime-context.tsx

@@ -4,6 +4,7 @@ import type { Store } from "../state/store";
 import type { RenderBundle } from "../render/bundle";
 import type { ConnectionStatus } from "../transport/ws";
 import type { LumencastMode } from "../types";
+import type { ResolveCaptureDevice } from "../render/primitives/capture";
 
 export interface LumencastRuntime {
   mode: LumencastMode;
@@ -12,6 +13,10 @@ export interface LumencastRuntime {
   status: ConnectionStatus;
   /** Send LSDP/1 input patches to the server. */
   sendInput: (patches: Patch[]) => void;
+  /** ADR 004 §A1.3 — host-provided resolver mapping a LOGICAL `deviceRef` to a
+   *  physical `deviceId` for the `x-zab.capture` primitive's ACQUIRE mode.
+   *  Injected from `MountOptions`, NOT the bundle. Absent → default device. */
+  resolveCaptureDevice?: ResolveCaptureDevice;
 }
 
 const Ctx = createContext<LumencastRuntime | null>(null);
@@ -35,3 +40,12 @@ export function useLumencastRuntime(): LumencastRuntime {
   }
   return v;
 }
+
+/** Read the runtime context WITHOUT throwing when no provider is mounted.
+ *  Render primitives (e.g. `x-zab.capture`) may render via `<Tree>` directly —
+ *  embedded hosts, tooling, tests — outside `mount()`'s provider. They use this
+ *  to pick up mount-level host config (the capture resolver) when present and
+ *  fall back to defaults when not. */
+export function useOptionalLumencastRuntime(): LumencastRuntime | null {
+  return useContext(Ctx);
+}

package/src/render/asset-resolve.ts

@@ -0,0 +1,97 @@
+// Public asset + font resolution helpers for headless / host render (ADR 003 §3.2).
+//
+// These utilities let a HOST (Solar headless entry, a ZabCanvas render worker,
+// the zero-loss harness) resolve a bundle's content-addressed asset references
+// to concrete `data:` URIs and inject brand `@font-face`s BEFORE the first
+// frame — exactly as the zero-loss harness has always done (ADR 002 #J). They
+// are promoted here verbatim so every host resolves identically and exercises
+// the SAME host-allow gate the runtime applies internally.
+//
+// ── No-fetch contract (ADR 003 §3.2, D3, Bastion R2) ────────────────────────
+// NONE of these helpers performs a network fetch. They only rewrite a bundle's
+// `src` values against a caller-supplied table (`resolveSrc` /
+// `rewriteLayoutSrcs` / `rewriteDefaultsSrcs`) and load `@font-face`s from
+// caller-supplied `data:`/same-document URLs (`injectFonts`). The runtime never
+// reaches the network; the host owns where bytes come from. Both the input
+// table values and the font `src`s are expected to be `data:` (or otherwise
+// already host-allowed) URIs — substituting one already-admitted scheme for
+// another, so the deny-by-default `allowedHosts` gate stays the sole authority.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A table mapping a bundle `src` reference to its resolved `data:` URI.
+ *  Keys may be either the full `assets/<hash>.ext` path or a bare `<hash>`. */
+export type AssetTable = Readonly<Record<string, string>>;
+
+/** Resolve a single `src` value against a table. Non-string or unmatched values
+ *  pass through unchanged. Matches both `assets/<hash>.ext` and bare `<hash>`. */
+export function resolveSrc(src: unknown, table: AssetTable): unknown {
+  if (typeof src !== "string") return src;
+  if (table[src]) return table[src];
+  const m = /^assets\/([A-Za-z0-9]+)\.[A-Za-z0-9]+$/.exec(src);
+  if (m && m[1] !== undefined && table[m[1]]) return table[m[1]];
+  return src;
+}
+
+/** Deep-rewrite every `src` (image-fill, mask source) in a layout subtree,
+ *  in place, against the supplied asset table. */
+export function rewriteLayoutSrcs(node: unknown, table: AssetTable): void {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const n of node) rewriteLayoutSrcs(n, table);
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if ("src" in obj) obj["src"] = resolveSrc(obj["src"], table);
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === "object") rewriteLayoutSrcs(v, table);
+  }
+}
+
+/** Rewrite the `__lit.image.*` defaults (image-primitive `bind.src` targets)
+ *  against the asset table, returning a new defaults object. */
+export function rewriteDefaultsSrcs(
+  defaults: Record<string, unknown>,
+  table: AssetTable,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...defaults };
+  for (const [k, v] of Object.entries(out)) {
+    if (k.startsWith("__lit.image.")) out[k] = resolveSrc(v, table);
+  }
+  return out;
+}
+
+/** A brand `@font-face` to inject before render. `src` is a `data:` URI (or any
+ *  same-document URL) so no network/host-allow surface is involved. */
+export interface FontFaceSpec {
+  family: string;
+  weight: number | string;
+  style?: string;
+  /** `url(data:font/woff2;base64,…)` content (the value inside `src:`). */
+  src: string;
+}
+
+/** Inject `@font-face` rules and block until the faces are loaded, so the very
+ *  first painted frame already uses the brand glyphs (no fallback-font flash).
+ *  Returns the families that successfully loaded. Loads only from the supplied
+ *  `src` (expected `data:`); never fetches a remote host on its own behalf. */
+export async function injectFonts(faces: readonly FontFaceSpec[]): Promise<string[]> {
+  const loaded: string[] = [];
+  for (const f of faces) {
+    try {
+      const face = new FontFace(f.family, f.src, {
+        weight: String(f.weight),
+        style: f.style ?? "normal",
+      });
+      await face.load();
+      (document as Document & { fonts: FontFaceSet }).fonts.add(face);
+      loaded.push(f.family);
+    } catch {
+      // A font that fails to load is a documented gap, not a render-breaker:
+      // the fallback glyphs paint and the host can detect the missing family
+      // in the returned list. Never throw (would abort an otherwise-good
+      // render) and never log the value (R9) — the absent family name is in
+      // `f.family`, which the caller already holds.
+    }
+  }
+  return loaded;
+}

package/src/render/bundle.ts

@@ -25,7 +25,11 @@ export type RenderKind =
   | "shape"
   | "media"
   | "repeat"
-  | "instance";
+  | "instance"
+  // Zab vendor primitive (RFC-0001, §17.1) — a transparent capture
+  // placeholder. Recognised by the Zab-plugin runtime ; reserves a box and
+  // renders nothing.
+  | "x-zab.capture";
 
 export interface RenderNode {
   kind: RenderKind;
@@ -139,6 +143,10 @@ export interface RenderBundle {
  */
 export const SUPPORTED_PROFILES: ReadonlySet<string> = new Set<string>([
   "x-lumencast.color-srgb-1.0",
+  // RFC-0001 / ADR 004 — this runtime ships the Zab capture plugin, so a
+  // bundle declaring `x-zab.capture/1` in `profiles[]` is compatible (it is
+  // NOT rejected as BUNDLE_INCOMPATIBLE, §17.3.1).
+  "x-zab.capture/1",
 ]);
 
 // LSML 1.1 §17.5.1 + ADR 001 RC#14 — authoring-profile detection.

package/src/render/headless.tsx

@@ -0,0 +1,129 @@
+// Public headless render entry — render an already-compiled `RenderBundle`
+// into a live DOM node, no WebSocket, ready when layout + fonts have settled
+// (ADR 003 §3.1). The host (Playwright / Chromium / a CEF offscreen surface)
+// screenshots `target` once `ready` resolves. The runtime does DOM + readiness
+// ONLY — no screenshot, no fetch (ADR 003 D5/D3).
+//
+// This is the zero-loss harness (ADR 002 #J) generalised: it mounts the EXACT
+// production seam —
+//   LumencastRuntimeProvider{ mode:"broadcast", status:"live" } > BroadcastMode
+// — into a real `createRoot(target)`, NOT `renderToStaticMarkup` (which yields
+// unlaid-out markup: unmeasured fonts, uncomposited masks → an infidel PNG,
+// ADR 003 §3.1). `BroadcastMode` is dynamically imported so the headless
+// function adds no weight to the eager `mount`/broadcast path (ADR 003 §4,
+// RC6); the heavy render code already lives in the broadcast/tree chunks.
+//
+// Asset resolution is the HOST's job, done in the bundle BEFORE this call
+// (ADR 003 §3.2): the runtime renders the bundle as-is, gating every remaining
+// `src` through the unchanged deny-by-default host-allow gate inside
+// `BroadcastMode` (`AllowedHostsProvider`). A `src` on a host not in the
+// bundle's `allowedHosts` is omitted + a diagnostic is emitted — never faked
+// (ADR 002 borne, D4). Use `render/asset-resolve` helpers to pre-resolve.
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { createStore } from "../state/store.js";
+import { LumencastRuntimeProvider } from "../overlay/runtime-context.js";
+import { addDiagnosticsHandler, type DiagnosticHandler } from "./diagnostics.js";
+import type { RenderBundle } from "./bundle.js";
+
+/** Default stage size — the Figma 817:3 cover frame, the SSIM reference. */
+const DEFAULT_STAGE = { width: 1920, height: 1080 } as const;
+
+export interface HeadlessRenderOptions {
+  /** Already-compiled bundle (via `@lumencast/compiler` on the host side). */
+  bundle: RenderBundle;
+  /** A live, mounted DOM node. Its size is set from `stage` unless the host
+   *  has already dimensioned it (see `stage`). */
+  target: HTMLElement;
+  /** Initial leaf-grain store state (`store.reset(defaults)`) — the bound
+   *  values the bundle reads (`__lit.*`, score, names…). */
+  defaults?: Record<string, unknown>;
+  /** Stage dimensions in CSS px. Defaults to 1920×1080. Applied to `target`
+   *  as `width`/`height`/`position:relative`/`overflow:hidden` so the
+   *  screenshot frame matches the reference exactly. */
+  stage?: { width: number; height: number };
+  /** Anti-drop diagnostics channel (ADR 001 §3.4): omitted assets, unhonoured
+   *  fields surface here as `{ nodeId, field, reason }` (never a value — R9).
+   *  Wired to the same global channel `mount()` uses. */
+  onDiagnostic?: DiagnosticHandler;
+}
+
+export interface HeadlessRenderHandle {
+  /** Resolves after the scene has rendered, two animation frames have passed
+   *  AND `document.fonts.ready` (ADR 003 §3.3) — i.e. the DOM is laid out and
+   *  fonts are loaded, so a screenshot taken now is fidelity-faithful. */
+  ready: Promise<void>;
+  /** Tear down the React root and detach the diagnostics handler. */
+  unmount(): void;
+}
+
+const noop = (): void => {};
+
+/**
+ * Render `bundle` into `target` through the production broadcast path and
+ * resolve `ready` once it is settled. The runtime performs NO network fetch and
+ * takes NO screenshot — it produces a settled live DOM and a readiness signal,
+ * nothing more (ADR 003 D5).
+ */
+export function renderBundleHeadless(opts: HeadlessRenderOptions): HeadlessRenderHandle {
+  const stage = opts.stage ?? DEFAULT_STAGE;
+  const target = opts.target;
+  // Pose the stage so the screenshot frame is exact (mirrors harness.html).
+  target.style.position ||= "relative";
+  target.style.width = `${stage.width}px`;
+  target.style.height = `${stage.height}px`;
+  target.style.overflow = "hidden";
+
+  const removeDiagnostics = opts.onDiagnostic
+    ? addDiagnosticsHandler(opts.onDiagnostic)
+    : undefined;
+
+  const store = createStore();
+  store.reset(opts.defaults ?? {});
+
+  const root = createRoot(target);
+
+  const ready = new Promise<void>((resolve) => {
+    // BroadcastMode is dynamically imported so its (and the tree's) weight is
+    // not pulled into the eager `mount` entry chunk (RC6). It is already a
+    // separate chunk reused from the broadcast path.
+    void import("../modes/broadcast.js").then(({ BroadcastMode }) => {
+      root.render(
+        <StrictMode>
+          <LumencastRuntimeProvider
+            value={{
+              mode: "broadcast",
+              store,
+              bundle: opts.bundle,
+              status: "live",
+              sendInput: noop,
+            }}
+          >
+            <BroadcastMode />
+          </LumencastRuntimeProvider>
+        </StrictMode>,
+      );
+
+      // Settle: two animation frames (layout) AND fonts loaded (ADR 003 §3.3).
+      // Both must complete before `ready` resolves, so a screenshot taken on
+      // `ready` uses the brand glyphs, not the fallback font (no FOUT freeze).
+      const framesSettled = new Promise<void>((res) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => res()));
+      });
+      const fontsReady =
+        typeof document !== "undefined" && document.fonts
+          ? document.fonts.ready.then(() => undefined)
+          : Promise.resolve();
+      void Promise.all([framesSettled, fontsReady]).then(() => resolve());
+    });
+  });
+
+  return {
+    ready,
+    unmount() {
+      removeDiagnostics?.();
+      root.unmount();
+    },
+  };
+}

package/src/render/keyframe-player.tsx

@@ -64,7 +64,20 @@ export function KeyframePlayer({
   return (
     <motion.div
       key={replayTokenRef.current}
-      style={{ display: "contents" }}
+      // A `display:contents` element generates NO box, so the browser
+      // never composites the animated `transform`/`opacity`/`filter` this
+      // player writes — they are silently dropped and the subtree renders
+      // dead at its child's default origin (ADR 011 I7 live bug). The
+      // player must be a REAL compositing box. `position:absolute; inset:0`
+      // overlays the parent without disturbing sibling layout, and — being
+      // positioned — becomes the containing block for the absolutely-
+      // positioned primitive nested beneath it (Frame is `position:absolute;
+      // left:0; top:0`), so the child's authored `x`/`y` resolve against the
+      // player's (0,0) exactly as they did against the grandparent under
+      // `display:contents`. The animated channels now composite onto a live
+      // box and the whole subtree (the nested target's geometry + fill)
+      // moves and fades with the keyframes.
+      style={{ position: "absolute", inset: 0 }}
       initial={firstFrame(compiled.animate)}
       animate={compiled.animate}
       transition={transition}