@lumencast/runtime 0.8.0 → 0.10.0

package/src/mount.ts

@@ -118,6 +118,22 @@ 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 }
+        : {}),
+      // ADR 006 #4 — thread the host peer-stream resolver (supplied by the
+      // WebRTC viewer #3) so the `media` primitive's LIVE mode can render a
+      // peer's MediaStream in `srcObject`.
+      ...(options.resolvePeerStream !== undefined
+        ? { resolvePeerStream: options.resolvePeerStream }
+        : {}),
+      // ADR 006 #3 — reactive variant : the LIVE `media` node re-renders when a
+      // peer connects/leaves mid-show. `createPeerViewer()` supplies it.
+      ...(options.subscribePeerStream !== undefined
+        ? { subscribePeerStream: options.subscribePeerStream }
+        : {}),
     }),
   );
 

package/src/overlay/runtime-context.tsx

@@ -4,6 +4,8 @@ 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";
+import type { ResolvePeerStream, SubscribePeerStream } from "../render/primitives/media";
 
 export interface LumencastRuntime {
   mode: LumencastMode;
@@ -12,6 +14,19 @@ 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;
+  /** ADR 006 #4 — host-provided resolver mapping a LOGICAL `peerLabel` to the
+   *  live `MediaStream` of a `meet.peer`, for the `media` primitive's LIVE mode.
+   *  Injected from `MountOptions` (supplied by the WebRTC viewer #3), NOT the
+   *  bundle. Absent → the live `media` node is a stream-less box. */
+  resolvePeerStream?: ResolvePeerStream;
+  /** ADR 006 #3 — reactive variant : the viewer pushes a peer's stream on
+   *  connect and `null` on leave, so a LIVE `media` node re-renders when its
+   *  peer joins mid-show. Preferred over `resolvePeerStream` when present. */
+  subscribePeerStream?: SubscribePeerStream;
 }
 
 const Ctx = createContext<LumencastRuntime | null>(null);
@@ -35,3 +50,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,21 @@ export type RenderKind =
   | "shape"
   | "media"
   | "repeat"
-  | "instance";
+  | "instance"
+  // ADR 006 §3.3/§3.5 — the unified source kind. Every source crossing the
+  // Prism export arrives as a `meet.peer` node ; the runtime resolves its
+  // `peer_label → MediaStream` (WebRTC viewer) and renders it in `srcObject`.
+  | "meet.peer"
+  // 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"
+  // Zab vendor primitive (ADR Blue 009 §3.1, Amendment 2) — a transparent
+  // meet-peer SLOT placeholder. Declares only a logical `x-zab.slotRef` (which
+  // slot receives a meet peer) + geometry ; carries NO cam/peer identity. The
+  // runtime resolves `slotRef → peer_label` from stream-level ZabCam state and
+  // renders the bound peer ; an unbound slot renders a transparent box.
+  | "x-zab.meet-peer";
 
 export interface RenderNode {
   kind: RenderKind;
@@ -139,6 +153,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,255 @@
+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" }}
+    />
+  );
+}
+
+/** A resolved physical device for a live capture constraint, or `null` when the
+ *  host could not bind the logical `deviceRef`. */
+export type ResolvedCaptureDevice = {
+  deviceId?: string;
+  captureSourceId?: string;
+} | null;
+
+/** Resolver injected by the consuming app (ADR 004 §A1.3). Maps the LOGICAL
+ *  `deviceRef` to a physical `deviceId`/`captureSourceId` for a live
+ *  `getUserMedia` constraint. The result NEVER enters the bundle or the content
+ *  hash. MAY be async: physical ids (e.g. getUserMedia `deviceId`) are salted
+ *  per origin/partition, so the host often must re-resolve a portable key
+ *  (label) against THIS context's devices — an inherently asynchronous step
+ *  (`enumerateDevices`). `acquireStream` awaits it, so the device is bound
+ *  before acquisition rather than racing a late global mutation. */
+export type ResolveCaptureDevice = (
+  deviceRef: string,
+  sourceKind: string,
+) => ResolvedCaptureDevice | Promise<ResolvedCaptureDevice>;
+
+/** §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 (amended 2026-06-27) — AWAIT the resolver: physical ids are salted
+  // per origin/partition, so the host may need an async re-resolution by a
+  // portable key (label) in THIS context. Awaiting binds the device before
+  // acquisition instead of racing a late global update (the previous sync call
+  // let the node acquire with a stale/absent id first).
+  const resolved = (await resolveCaptureDevice?.(deviceRef, sourceKind)) ?? null;
+  const deviceId = resolved?.deviceId;
+  const declaredRef = deviceRef.length > 0;
+
+  switch (sourceKind) {
+    case "media.webcam":
+    case "media.mic":
+    case "media.app_audio": {
+      // §A1.3 (amended) — NO default-device fallback for a DECLARED deviceRef
+      // that did not resolve to a real device. Acquiring the host default cam
+      // here is the silent "automatic allocation" of the WRONG camera the
+      // consuming app must never get. → PLACEHOLDER (return null). The bare
+      // default constraint stays ONLY when no deviceRef is declared at all.
+      if (declaredRef && (typeof deviceId !== "string" || deviceId.length === 0)) {
+        return null;
+      }
+      const channel = sourceKind === "media.webcam" ? "video" : "audio";
+      return md.getUserMedia({ [channel]: deviceConstraint(deviceId) });
+    }
+    case "media.screen":
+    case "media.window": {
+      // DIRECT capture of the picked desktopCapturer surface (no system picker)
+      // via Electron's legacy `chromeMediaSource:desktop` + the resolved
+      // `captureSourceId`.
+      const captureSourceId = resolved?.captureSourceId;
+      if (typeof captureSourceId === "string" && captureSourceId.length > 0) {
+        return md.getUserMedia({
+          video: {
+            mandatory: {
+              chromeMediaSource: "desktop",
+              chromeMediaSourceId: captureSourceId,
+            },
+          } as unknown as MediaTrackConstraints,
+        });
+      }
+      // A declared surface ref that didn't resolve → PLACEHOLDER, never a
+      // default `getDisplayMedia` picker. The picker stays only when no ref is
+      // declared (a bare capture node on a non-Electron host).
+      if (declaredRef) return null;
+      return md.getDisplayMedia({ video: true });
+    }
+    default:
+      return null;
+  }
+}
+
+/** A `getUserMedia` track constraint. A resolved deviceId is pinned with
+ *  `exact`, NOT a bare (ideal) deviceId: an *ideal* constraint SILENTLY falls
+ *  back to the host default camera when the requested device can't start (e.g.
+ *  an INACTIVE virtual cam that's enumerated but produces no stream) — the
+ *  "automatic allocation" of the WRONG camera. `exact` yields the requested
+ *  device (its placeholder frame if idle), or an OverconstrainedError the
+ *  caller catches into PLACEHOLDER — never the wrong cam. No deviceId → `true`
+ *  (host default) applies ONLY when no deviceRef was declared. */
+function deviceConstraint(deviceId: string | undefined): MediaTrackConstraints | boolean {
+  return typeof deviceId === "string" && deviceId.length > 0
+    ? { deviceId: { exact: 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

@@ -12,7 +12,9 @@ import { Text } from "./text";
 import { Image } from "./image";
 import { Shape } from "./shape";
 import { Media } from "./media";
+import { MeetPeer } from "./meet-peer";
 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.
@@ -47,5 +49,10 @@ export const PRIMITIVES: Partial<Record<RenderKind, ComponentType<PrimitiveProps
   image: Image,
   shape: Shape,
   media: Media,
+  // ADR 006 §3.3/§3.5 — the unified source kind : every exported source is a
+  // `meet.peer` node rendered in `<video srcObject>` from the WebRTC viewer.
+  "meet.peer": MeetPeer,
   instance: Instance,
+  // RFC-0001 / ADR 004 — Zab vendor capture placeholder (transparent, inert).
+  "x-zab.capture": Capture,
 };

package/src/render/primitives/live-peer-video.tsx

@@ -0,0 +1,90 @@
+import { useEffect, useRef, useState } from "react";
+import { useOptionalLumencastRuntime } from "../../overlay/runtime-context";
+
+/** Shared LIVE peer-stream rendering (ADR 006 §3.3/§3.5) — the SINGLE srcObject
+ *  path used by BOTH the `media` primitive's live mode (#4, keyed on `peerLabel`)
+ *  AND the generic `meet.peer` source kind (the unified source abstraction).
+ *  There is no special renderer per source : every live source resolves
+ *  `peerLabel → MediaStream` through the host viewer and paints it the same way.
+ *
+ *  Resolution : prefer the reactive channel (`subscribePeerStream`, #3) so a node
+ *  mounted BEFORE its peer connects re-renders on arrival ; fall back to the
+ *  one-shot `resolvePeerStream` (#4 contract) ; no host resolver → stream-less
+ *  box. Reading a stream is the ONLY side effect — the scene is never mutated
+ *  (RC-ReadOnly).
+ *
+ *  Geometry (RC-Geo) : the `<video>` fills `100%`/`100%` of the box the Tree's
+ *  UniversalWrapper sized from the node's `x/y/width/height`. The geometry lives
+ *  on the wrapper, NEVER on the video, so it is structurally impossible to force
+ *  a full-viewport size ; `object-fit` is the scene-authored value.
+ *
+ *  Ownership : the stream is owned by the viewer (#3). This component is a pure
+ *  consumer — unmounting clears its own `srcObject` and stops NO track (a mirror
+ *  must never tear a peer down for the on-air composite). */
+export function LivePeerVideo({
+  peerLabel,
+  objectFit,
+  muted = true,
+}: {
+  peerLabel: string;
+  objectFit: string;
+  /** Audio playout hint. Always muted for now (broadcast audio is Pulsar-side). */
+  muted?: boolean;
+}) {
+  const runtime = useOptionalLumencastRuntime();
+  const resolvePeerStream = runtime?.resolvePeerStream;
+  const subscribePeerStream = runtime?.subscribePeerStream;
+
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const [stream, setStream] = useState<MediaStream | null>(null);
+
+  useEffect(() => {
+    if (subscribePeerStream !== undefined) {
+      return subscribePeerStream(peerLabel, setStream);
+    }
+    if (resolvePeerStream !== undefined) {
+      setStream(resolvePeerStream(peerLabel));
+      return;
+    }
+    setStream(null);
+  }, [peerLabel, resolvePeerStream, subscribePeerStream]);
+
+  // `srcObject` is not a serialisable attribute — attach imperatively. Never
+  // stop the tracks here (the viewer owns them).
+  useEffect(() => {
+    const el = videoRef.current;
+    if (el === null) return;
+    el.srcObject = stream;
+    return () => {
+      if (el !== null) el.srcObject = null;
+    };
+  }, [stream]);
+
+  if (stream === null) {
+    // Stream-less box of the wrapper geometry — transparent, inert, paints
+    // nothing. NOT an error : the peer can connect mid-show.
+    return (
+      <div
+        aria-hidden
+        data-lumencast-media-live
+        style={{ width: "100%", height: "100%", opacity: 0, pointerEvents: "none" }}
+      />
+    );
+  }
+
+  return (
+    <video
+      ref={videoRef}
+      data-lumencast-media-live
+      autoPlay
+      muted={muted}
+      playsInline
+      style={{
+        width: "100%",
+        height: "100%",
+        objectFit: objectFit as React.CSSProperties["objectFit"],
+        pointerEvents: "none",
+      }}
+    />
+  );
+}

package/src/render/primitives/media.tsx

@@ -1,26 +1,68 @@
 import type { PrimitiveProps } from "./index";
 import { gateSrc, useAllowedHosts } from "../allowed-hosts";
+import { LivePeerVideo } from "./live-peer-video";
 
-/** Embedded video. `src`, `loop`, `mute`, `autoplay`. Audio is muted
- *  by default — broadcast audio is Pulsar-side, not from the browser
- *  source.
+/** Resolver injected by the consuming app (ADR 006 §3.3, #4). Maps a LOGICAL
+ *  `peerLabel` (the `meet.peer.peer_label` carried by the scene) to the live
+ *  `MediaStream` of that peer — supplied by the WebRTC viewer (issue #3). The
+ *  stream is rendered in `srcObject` ; it NEVER enters the bundle or the content
+ *  hash. Returns `null` when the peer is not (yet) connected → the node stays a
+ *  stream-less box, no throw, no diagnostic (a peer can join mid-show). */
+export type ResolvePeerStream = (peerLabel: string) => MediaStream | null;
+
+/** Reactive variant (ADR 006 #3) : the viewer pushes a peer's stream when it
+ *  connects and `null` when it leaves. The LIVE primitive prefers this over the
+ *  one-shot resolver so a node that mounted BEFORE the peer connected re-renders
+ *  on arrival (a peer joins mid-show). The listener is invoked immediately with
+ *  the current value, then on every change ; the return value unsubscribes.
+ *  Like `resolvePeerStream`, it is injected at mount — never the bundle. */
+export type SubscribePeerStream = (
+  peerLabel: string,
+  listener: (stream: MediaStream | null) => void,
+) => () => void;
+
+/** Embedded video. Two source modes, picked by the node's props :
+ *
+ *   - **BUNDLE** (`src`, the original mode) : a `<video src>` of a bundled /
+ *     gated URL. Audio muted by default (broadcast audio is Pulsar-side). `src`
+ *     is the sole network sink and MUST pass `gateSrc` before reaching the
+ *     `<video>` (Bastion, ADR 003 — an off-allowlist request is an SSRF surface
+ *     in headless `zabrender`). A rejected host/scheme omits the source.
  *
- *  Security (Bastion, ADR 003) : `src` is the media primitive's sole
- *  network sink (no `poster` / `<source>` / `<track>` are rendered). Like
- *  every other asset leaf (image / image-fill / mask) it MUST pass
- *  `gateSrc` BEFORE reaching the `<video>` — otherwise a `kind:"media"`
- *  node would make the headless Chromium of `zabrender` emit an
- *  off-allowlist request (an SSRF surface). A rejected host/scheme omits
- *  the source entirely (no passthrough), with an R9-clean diagnostic
- *  ({ nodeId, field, reason } — never the URL). */
+ *   - **LIVE** (`peerLabel`, ADR 006 #4) : the source is a `meet.peer`'s
+ *     `peer_label`. The runtime resolves the peer's `MediaStream` through a
+ *     host-provided resolver (`resolvePeerStream`, injected at mount — NOT the
+ *     bundle, like `resolveCaptureDevice`) and renders it imperatively via
+ *     `<video>.srcObject` in real time. No URL, no `gateSrc` (a `MediaStream`
+ *     is not a network sink). An absent resolver or an unconnected peer leaves a
+ *     stream-less box — no throw, no diagnostic (peers join mid-show).
+ *
+ *  `peerLabel` takes precedence when present (a live node), else `src` (bundle).
+ *
+ *  Geometry is read-only (ADR 006 A1.6) : the node's `x/y/width/height` are
+ *  applied by the Tree's UniversalWrapper around this primitive ; the `<video>`
+ *  fills that box (`100%`/`100%`) with the scene-authored `object-fit`. The
+ *  primitive NEVER forces full-screen and NEVER writes any geometry back — it
+ *  only reads `resolved`. */
 export function Media({ resolved, nodeId }: PrimitiveProps) {
   const allowedHosts = useAllowedHosts();
+  const fit = (resolved.fit as string | undefined) ?? "cover";
+  const peerLabel =
+    typeof resolved.peerLabel === "string" && resolved.peerLabel.length > 0
+      ? resolved.peerLabel
+      : "";
+
+  if (peerLabel !== "") {
+    // LIVE mode — the SAME srcObject path as the generic `meet.peer` source.
+    return <LivePeerVideo peerLabel={peerLabel} objectFit={fit} />;
+  }
+
+  // BUNDLE mode (unchanged) — gated `<video src>`.
   const src = gateSrc(resolved.src, allowedHosts, "media.src", nodeId);
   if (!src) return null;
   const loop = (resolved.loop as boolean | undefined) ?? true;
   const mute = (resolved.mute as boolean | undefined) ?? true;
   const autoplay = (resolved.autoplay as boolean | undefined) ?? true;
-  const fit = (resolved.fit as string | undefined) ?? "cover";
 
   return (
     <video
@@ -29,11 +71,18 @@ export function Media({ resolved, nodeId }: PrimitiveProps) {
       loop={loop}
       muted={mute}
       playsInline
-      style={{
-        width: "100%",
-        height: "100%",
-        objectFit: fit as React.CSSProperties["objectFit"],
-      }}
+      style={fillBox(fit)}
     />
   );
 }
+
+/** The bundle `<video src>` fills the box the UniversalWrapper sized from the
+ *  node's `width`/`height` (RC-Geo) ; `object-fit` is the scene-authored `fit`.
+ *  The geometry lives on the wrapper, never on the video. */
+function fillBox(fit: string): React.CSSProperties {
+  return {
+    width: "100%",
+    height: "100%",
+    objectFit: fit as React.CSSProperties["objectFit"],
+  };
+}

package/src/render/primitives/meet-peer.tsx

@@ -0,0 +1,57 @@
+import type { PrimitiveProps } from "./index";
+import { LivePeerVideo } from "./live-peer-video";
+
+/** `meet.peer` — the UNIFIED source primitive (ADR 006 §3.3/§3.5). Every source
+ *  that crosses the Prism export (cam, screen, game_capture, …) arrives as a
+ *  single `meet.peer` LSML node ; this is the ONE renderer for all of them — not
+ *  a special-case path. It generalises the `media` primitive's live mode (#4) to
+ *  the source abstraction : read `peer_label`, resolve the peer's `MediaStream`
+ *  through the host viewer (#3), and paint it in `<video srcObject>` constrained
+ *  to the node's box.
+ *
+ *  Contract (rendered verbatim, ADR §3.3 — no variation) :
+ *   - `peer_label` (string) — the STREAM REFERENCE. Resolved `peer_label →
+ *     MediaStream` via `subscribePeerStream`/`resolvePeerStream`. Empty / missing
+ *     → a transparent inert box (the source is not addressable).
+ *   - `x-zab.sourceKind` (string) — ADVISORY only. Rendering is UNIFORM whatever
+ *     the kind ; at most it could hint audio-only, but Phase 0 paints every
+ *     visual source identically.
+ *   - `object_fit` ("cover"|"contain"|"fill") — how the video fills the box.
+ *   - `muted` (bool, optional) — audio playout hint (default muted ; broadcast
+ *     audio is Pulsar-side).
+ *   - `position{x,y}` + `size{w,h}` — geometry via the Tree's UniversalWrapper
+ *     (compiler-flattened to `x/y/width/height`). Z-ORDER = sibling order (cam
+ *     over game = two ordered `meet.peer` nodes — no special z handling here).
+ *   - `metadata.figma` — advisory (editor round-trip), never read for rendering.
+ *
+ *  RC-Geo : the `<video>` fills `100%`/`100%` of the wrapper box at the exact
+ *  authored geometry / `object_fit` — never forced full-screen (the geometry is
+ *  on the wrapper, not the video). RC-ReadOnly : the primitive only READS
+ *  `resolved` ; it never writes geometry or any field back to the scene. An
+ *  unconnected peer → transparent inert box, no throw, no diagnostic. */
+export function MeetPeer({ resolved }: PrimitiveProps) {
+  const peerLabel =
+    typeof resolved.peer_label === "string" && resolved.peer_label.length > 0
+      ? resolved.peer_label
+      : "";
+
+  // Empty / missing label → not addressable yet : a transparent inert box of the
+  // wrapper geometry, exactly like an unconnected peer (no throw, no diagnostic).
+  if (peerLabel === "") {
+    return (
+      <div
+        aria-hidden
+        data-lumencast-meet-peer
+        style={{ width: "100%", height: "100%", opacity: 0, pointerEvents: "none" }}
+      />
+    );
+  }
+
+  const objectFit =
+    typeof resolved.object_fit === "string" && resolved.object_fit.length > 0
+      ? resolved.object_fit
+      : "cover";
+  const muted = resolved.muted === undefined ? true : resolved.muted !== false;
+
+  return <LivePeerVideo peerLabel={peerLabel} objectFit={objectFit} muted={muted} />;
+}