@lumencast/runtime 0.8.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.8.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.8.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.8.0",
-    "@lumencast/server": "0.8.0"
+    "@lumencast/server": "0.9.0",
+    "@lumencast/dev-server": "0.9.0"
   },
   "scripts": {
     "dev": "vite",

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,

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/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/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}

package/src/render/primitives/capture.tsx

@@ -0,0 +1,210 @@
+import { useEffect, useRef, useState } from "react";
+import type { PrimitiveProps } from "./index";
+import { useOptionalLumencastRuntime } from "../../overlay/runtime-context";
+
+/** `x-zab.capture` — context-aware capture primitive (Zab vendor primitive,
+ *  RFC-0001 / ADR 004 §Amendment 1).
+ *
+ *  The primitive reserves a box of the declared geometry so downstream layout
+ *  (siblings, masks, stacks, grids) is unaffected — exactly as an `image` of
+ *  the same geometry, in BOTH modes below. It picks a mode by **capability
+ *  detection at mount** (feature detection, not an env flag) :
+ *
+ *   - **ACQUIRE** (capable host, e.g. the Electron preview webview with
+ *     auto-granted media permissions) : it acquires a live stream itself via
+ *     `getUserMedia` (webcam/mic) or `getDisplayMedia` (screen/window) per
+ *     `x-zab.sourceKind`, and renders it in a `<video>` for visual kinds
+ *     (audio kinds stay visually empty). The physical device is resolved from
+ *     the LOGICAL `x-zab.deviceRef` through a host-provided resolver
+ *     (`resolveCaptureDevice`, §A1.3) — never a bundle-baked id. Any failure
+ *     (no resolver, no device, permission denied, acquisition error) falls
+ *     back to PLACEHOLDER WITHOUT throwing or blanking the surrounding tree.
+ *
+ *   - **PLACEHOLDER** (non-capable host, e.g. CEF/Pulsar on-air) : the box is
+ *     fully transparent, acquires nothing, reaches no device — the original
+ *     §3.2 behaviour. The consuming app composites a native source behind it
+ *     (ON-AIR PATH UNCHANGED).
+ *
+ *  A stream-less box is a valid mode, not an error : NO diagnostic is emitted
+ *  for PLACEHOLDER mode or for an ACQUIRE→PLACEHOLDER fallback.
+ *
+ *  Geometry is the only layout input. `width`/`height` are the
+ *  compiler-flattened `size:{w,h}` ; universal props (visible/opacity/
+ *  position) are applied by the Tree's UniversalWrapper. An audio-only
+ *  capture (`media.mic` / `media.app_audio`) may omit `size` → a zero-area
+ *  box that never paints. */
+export function Capture({ resolved }: PrimitiveProps) {
+  const width = dimOr(resolved.width, "100%");
+  const height = dimOr(resolved.height, "100%");
+  const sourceKind = typeof resolved["x-zab.sourceKind"] === "string"
+    ? (resolved["x-zab.sourceKind"] as string)
+    : "";
+  const deviceRef = typeof resolved["x-zab.deviceRef"] === "string"
+    ? (resolved["x-zab.deviceRef"] as string)
+    : "";
+
+  // §A1.3 — the host-provided resolver, injected at mount through the runtime
+  // context (NOT the bundle, NOT the LSDP wire). Absent when the tree renders
+  // outside a host (direct embedding, tooling, tests) → the default-device
+  // path applies.
+  const runtime = useOptionalLumencastRuntime();
+  const resolveCaptureDevice = runtime?.resolveCaptureDevice;
+
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  // `null` → PLACEHOLDER (non-capable, or ACQUIRE→PLACEHOLDER fallback).
+  // A `MediaStream` → ACQUIRE succeeded and a visual stream is mounted.
+  const [stream, setStream] = useState<MediaStream | null>(null);
+
+  useEffect(() => {
+    // §A1.2(2) — capability detection at mount. A non-capable host (no
+    // `getUserMedia`, e.g. CEF/Pulsar on-air, or jsdom without a mock) stays
+    // in PLACEHOLDER : acquire nothing, no diagnostic.
+    if (!isCaptureCapable()) return;
+
+    let cancelled = false;
+    let acquired: MediaStream | null = null;
+
+    void (async () => {
+      try {
+        const media = await acquireStream(sourceKind, deviceRef, resolveCaptureDevice);
+        if (media === null) return; // unknown/unsupported kind → PLACEHOLDER
+        if (cancelled) {
+          // Unmounted (or scene-changed) during acquisition — stop immediately
+          // so we never leave a camera light on (RC11).
+          stopStream(media);
+          return;
+        }
+        acquired = media;
+        setStream(media);
+      } catch {
+        // §A1.2(2)(a) — any acquisition failure (permission denied, no device,
+        // getUserMedia rejected) falls back to PLACEHOLDER, no throw, no
+        // diagnostic.
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      // RC11 — stop the tracks at unmount / scene change. Clearing state is
+      // unnecessary (the component is gone) but stopping the device is not.
+      if (acquired !== null) stopStream(acquired);
+    };
+    // Re-acquire when the logical source identity changes (a scene switch can
+    // reuse the node with a new sourceKind/deviceRef).
+  }, [sourceKind, deviceRef, resolveCaptureDevice]);
+
+  // Attach / detach the live stream to the <video> element imperatively —
+  // `srcObject` is not a serialisable attribute.
+  useEffect(() => {
+    const el = videoRef.current;
+    if (el === null) return;
+    el.srcObject = stream;
+    return () => {
+      if (el !== null) el.srcObject = null;
+    };
+  }, [stream]);
+
+  // ACQUIRE with a visual stream → render the <video>. Audio-only kinds keep
+  // the transparent box (no visible element) even when acquired.
+  if (stream !== null && isVisualKind(sourceKind)) {
+    return (
+      <video
+        ref={videoRef}
+        data-lumencast-capture
+        autoPlay
+        muted
+        playsInline
+        style={{ width, height, objectFit: "cover", pointerEvents: "none" }}
+      />
+    );
+  }
+
+  // PLACEHOLDER (or audio-only ACQUIRE) — fully transparent, inert box.
+  return (
+    <div
+      aria-hidden
+      data-lumencast-capture
+      style={{ width, height, opacity: 0, pointerEvents: "none" }}
+    />
+  );
+}
+
+/** Resolver injected by the consuming app (ADR 004 §A1.3). Maps the LOGICAL
+ *  `deviceRef` to a physical `deviceId` for a live `getUserMedia` constraint.
+ *  The result NEVER enters the bundle or the content hash. */
+export type ResolveCaptureDevice = (
+  deviceRef: string,
+  sourceKind: string,
+) => { deviceId?: string } | null;
+
+/** §A1.2(2) — capture-capable iff `navigator.mediaDevices.getUserMedia`
+ *  exists and is callable in the current context. Feature detection only ;
+ *  CEF/Pulsar on-air and jsdom (without a mock) report non-capable. */
+function isCaptureCapable(): boolean {
+  return (
+    typeof navigator !== "undefined" &&
+    typeof navigator.mediaDevices?.getUserMedia === "function"
+  );
+}
+
+/** Visual kinds render a `<video>` ; audio kinds stay visually empty. */
+function isVisualKind(sourceKind: string): boolean {
+  return (
+    sourceKind === "media.webcam" ||
+    sourceKind === "media.screen" ||
+    sourceKind === "media.window"
+  );
+}
+
+/** Acquire a live stream for `sourceKind`, applying a host-resolved `deviceId`
+ *  when available. Returns `null` for an unsupported/unknown kind (→
+ *  PLACEHOLDER) ; throws are caught by the caller (→ PLACEHOLDER fallback). */
+async function acquireStream(
+  sourceKind: string,
+  deviceRef: string,
+  resolveCaptureDevice: ResolveCaptureDevice | undefined,
+): Promise<MediaStream | null> {
+  const md = navigator.mediaDevices;
+
+  // §A1.3 — a resolver maps the LOGICAL deviceRef to a physical deviceId. No
+  // resolver / `null` result → default constraints (no deviceId), so "the cam
+  // traverses" on the first pass. The deviceId is a live constraint only.
+  const resolved = resolveCaptureDevice?.(deviceRef, sourceKind) ?? null;
+  const deviceId = resolved?.deviceId;
+
+  switch (sourceKind) {
+    case "media.webcam":
+      return md.getUserMedia({ video: deviceConstraint(deviceId) });
+    case "media.mic":
+      return md.getUserMedia({ audio: deviceConstraint(deviceId) });
+    case "media.app_audio":
+      return md.getUserMedia({ audio: deviceConstraint(deviceId) });
+    case "media.screen":
+    case "media.window":
+      // Display capture has no deviceId constraint (the picker selects the
+      // surface). The resolver is consulted but its id is not applicable here.
+      return md.getDisplayMedia({ video: true });
+    default:
+      return null;
+  }
+}
+
+/** A `getUserMedia` track constraint : a specific `deviceId` when resolved,
+ *  else `true` (the host's default device). */
+function deviceConstraint(deviceId: string | undefined): MediaTrackConstraints | boolean {
+  return typeof deviceId === "string" && deviceId.length > 0 ? { deviceId } : true;
+}
+
+/** Stop every track of a stream (RC11 — release the camera/mic, kill the
+ *  device light). */
+function stopStream(stream: MediaStream): void {
+  for (const track of stream.getTracks()) track.stop();
+}
+
+/** A render dimension: a finite number → px, a non-empty string → verbatim,
+ *  anything else → the fallback (matches the `image` primitive's helper). */
+function dimOr(v: unknown, fallback: string): string {
+  if (typeof v === "number" && Number.isFinite(v)) return `${v}px`;
+  if (typeof v === "string" && v.length > 0) return v;
+  return fallback;
+}

package/src/render/primitives/index.ts

@@ -13,6 +13,7 @@ import { Image } from "./image";
 import { Shape } from "./shape";
 import { Media } from "./media";
 import { Instance } from "./instance";
+import { Capture } from "./capture";
 // `repeat` is dispatched specially in the tree (it iterates a bound
 // array and provides a path scope to its children) ; it does not
 // appear here as a regular primitive.
@@ -48,4 +49,6 @@ export const PRIMITIVES: Partial<Record<RenderKind, ComponentType<PrimitiveProps
   shape: Shape,
   media: Media,
   instance: Instance,
+  // RFC-0001 / ADR 004 — Zab vendor capture placeholder (transparent, inert).
+  "x-zab.capture": Capture,
 };

package/src/render/prop-allowlist.ts

@@ -99,6 +99,11 @@ export const PRIMITIVE_PROP_ALLOWLIST: Readonly<Record<RenderKind, ReadonlySet<s
   ]),
   media: allow(["src", "loop", "mute", "autoplay", "fit"]),
   instance: allow(["scene_id", "scene_version", "size", "position"]),
+  // RFC-0001 / ADR 004 — vendor capture placeholder. `width`/`height` are the
+  // flattened geometry (universal) ; the `x-zab.*` props are carried as
+  // metadata (the renderer reserves the box, ignores deviceRef). Listed so
+  // they are NOT flagged as silent drops by the anti-drop audit.
+  "x-zab.capture": allow(["x-zab.sourceKind", "x-zab.deviceRef", "width", "height"]),
   // `repeat` is dispatched specially by the tree ; its only consumed
   // binding is `items`.
   repeat: new Set(["items"]),

package/src/types.ts

@@ -1,6 +1,7 @@
 // Public types of @lumencast/runtime — must align with RUNTIME-API.md.
 
 import type { ErrorCode } from "@lumencast/protocol";
+import type { ResolveCaptureDevice } from "./render/primitives/capture";
 
 export type LumencastMode = "broadcast" | "control" | "test";
 
@@ -69,6 +70,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 {