@lumencast/runtime 0.9.0 → 0.11.0

package/src/mount.ts

@@ -7,6 +7,7 @@ import { createElement } from "react";
 import { LumencastApp } from "./app.js";
 import { applyDelta } from "./state/apply-delta.js";
 import { applySnapshot } from "./state/apply-snapshot.js";
+import { createReservedLeafObserver } from "./state/reserved-leaves.js";
 import { createStore } from "./state/store.js";
 import { createBundleFetcher, type BundleFetcher, type RenderBundle } from "./render/bundle.js";
 import { WsClient, type ConnectionStatus, type TransportError } from "./transport/ws.js";
@@ -45,6 +46,15 @@ export function mount(options: MountOptions): LumencastHandle {
 
   let active = true;
 
+  // ADR Blue 009 §3.2–3.3 — surface the reserved `__cam.*` LSDP leaves (the
+  // slot→peer assignments + the receive-only viewer creds) to the host so its
+  // WebRTC viewer (Solar) can drive room joins + `x-zab.meet-peer` slot re-keying.
+  // The runtime never joins, holds creds, or re-keys ; it only forwards. Created
+  // only when the host opts in — zero cost on the preview/headless paths.
+  const reservedLeaves = options.onReservedLeaves
+    ? createReservedLeafObserver(options.onReservedLeaves)
+    : undefined;
+
   // ADR 001 §3.4 (issue #34) — anti-silent-drop diagnostics are events
   // surfaced to the host, never console logs in `broadcast` mode.
   const removeDiagnosticsHandler = options.onDiagnostic
@@ -59,6 +69,7 @@ export function mount(options: MountOptions): LumencastHandle {
     onStatus: setStatus,
     onSnapshot: (frame) => {
       if (!active) return;
+      reservedLeaves?.onSnapshot(frame.state);
       void onSnapshot(
         bundleFetcher,
         bundleSignal,
@@ -78,6 +89,7 @@ export function mount(options: MountOptions): LumencastHandle {
       if (!active) return;
       const start = performance.now();
       applyDelta(store, frame);
+      reservedLeaves?.onDelta(frame.patches);
       options.onMetric?.({
         name: "delta_applied",
         duration_ms: performance.now() - start,
@@ -123,6 +135,17 @@ export function mount(options: MountOptions): LumencastHandle {
       ...(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

@@ -5,6 +5,7 @@ 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;
@@ -17,6 +18,15 @@ export interface LumencastRuntime {
    *  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);

package/src/render/bundle.ts

@@ -26,10 +26,20 @@ export type RenderKind =
   | "media"
   | "repeat"
   | "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";
+  | "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;

package/src/render/primitives/capture.tsx

@@ -36,12 +36,12 @@ import { useOptionalLumencastRuntime } from "../../overlay/runtime-context";
 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)
-    : "";
+  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
@@ -129,30 +129,39 @@ export function Capture({ resolved }: PrimitiveProps) {
   );
 }
 
+/** 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` for a live `getUserMedia` constraint.
- *  The result NEVER enters the bundle or the content hash. */
+ *  `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,
-) => { deviceId?: string } | null;
+) => 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"
+    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"
+    sourceKind === "media.webcam" || sourceKind === "media.screen" || sourceKind === "media.window"
   );
 }
 
@@ -166,33 +175,69 @@ async function acquireStream(
 ): 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;
+  // §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":
-      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.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":
-      // Display capture has no deviceId constraint (the picker selects the
-      // surface). The resolver is consulted but its id is not applicable here.
+    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 specific `deviceId` when resolved,
- *  else `true` (the host's default device). */
+/** 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 } : true;
+  return typeof deviceId === "string" && deviceId.length > 0
+    ? { deviceId: { exact: deviceId } }
+    : true;
 }
 
 /** Stop every track of a stream (RC11 — release the camera/mic, kill the

package/src/render/primitives/index.ts

@@ -12,6 +12,8 @@ import { Text } from "./text";
 import { Image } from "./image";
 import { Shape } from "./shape";
 import { Media } from "./media";
+import { MeetPeer } from "./meet-peer";
+import { MeetPeerSlot } from "./meet-peer-slot";
 import { Instance } from "./instance";
 import { Capture } from "./capture";
 // `repeat` is dispatched specially in the tree (it iterates a bound
@@ -48,7 +50,15 @@ 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,
+  // ADR Blue 009 §3.1 (Amendment 2) — Zab vendor meet-peer SLOT placeholder.
+  // Carries only a logical `x-zab.slotRef` ; the host's slot-aware peer-stream
+  // registry resolves `slotRef → peer_label → MediaStream` (transparent when
+  // unbound). Closes the kind→primitive gap that left it an unknown-kind drop.
+  "x-zab.meet-peer": MeetPeerSlot,
 };

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-slot.tsx

@@ -0,0 +1,55 @@
+import type { PrimitiveProps } from "./index";
+import { LivePeerVideo } from "./live-peer-video";
+
+/** `x-zab.meet-peer` — the transparent meet-peer SLOT placeholder (Zab vendor
+ *  primitive, ADR Blue 009 §3.1 Amendment 2 ; type shipped in v0.10.0 / #81).
+ *
+ *  Distinct from `meet.peer` (the cam-identity source) : this node carries NO
+ *  peer identity, only a hash-stable LOGICAL `x-zab.slotRef` (e.g. `cam-caster-1`)
+ *  + geometry. WHICH `peer_label` fills a slot is RUNTIME, stream-level ZabCam
+ *  state — never baked in the scene. The slot→peer binding is ported by Orion on
+ *  the LSDP as `__cam.slots.<slotRef>` = "<peer_label>" (§3.3) and re-keyed into
+ *  the host's peer-stream registry (Solar `slot-binding.ts`) so the registry
+ *  resolves `slotRef → peer_label → MediaStream`.
+ *
+ *  Contract (rendered verbatim) :
+ *   - `x-zab.slotRef` (string) — the SLOT REFERENCE, used as the resolver KEY.
+ *     The host's peer-stream resolver (`resolvePeerStream`/`subscribePeerStream`)
+ *     is keyed by `slotRef` on the antenne (Solar's slot-aware registry maps it
+ *     to a `peer_label`, then to a stream). Empty / missing → a transparent inert
+ *     box (the slot is not addressable).
+ *   - geometry (`width`/`height` + position) — applied by the Tree's
+ *     UniversalWrapper, exactly like `meet.peer` ; the `<video>` fills the box
+ *     100%/100% and is never forced full-screen (RC-Geo).
+ *
+ *  Receive-only : the slot reads its stream through the host viewer (Solar joins
+ *  the room and owns the peer connections / track lifecycle) ; the primitive
+ *  carries no creds and never mutates the scene (RC-ReadOnly). An UNBOUND slot
+ *  (no `__cam.slots.*` assignment) or a not-yet-connected peer → a transparent
+ *  placeholder, no throw, no diagnostic (R3). */
+export function MeetPeerSlot({ resolved }: PrimitiveProps) {
+  const slotRef =
+    typeof resolved["x-zab.slotRef"] === "string" &&
+    (resolved["x-zab.slotRef"] as string).length > 0
+      ? (resolved["x-zab.slotRef"] as string)
+      : "";
+
+  // No slotRef → not addressable : a transparent inert box of the wrapper
+  // geometry (no throw, no diagnostic), exactly like an unbound slot.
+  if (slotRef === "") {
+    return (
+      <div
+        aria-hidden
+        data-lumencast-meet-peer-slot
+        style={{ width: "100%", height: "100%", opacity: 0, pointerEvents: "none" }}
+      />
+    );
+  }
+
+  // Key the peer-viewer resolver by `slotRef` (NOT a peer_label). The shared
+  // `LivePeerVideo` is resolver-key agnostic : it passes its `peerLabel` prop
+  // straight to `resolvePeerStream`/`subscribePeerStream`, and the host's
+  // slot-aware registry translates the slotRef to the bound peer's stream. An
+  // unbound slot resolves to `null` → the transparent placeholder.
+  return <LivePeerVideo peerLabel={slotRef} objectFit="cover" muted />;
+}

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

package/src/render/prop-allowlist.ts

@@ -97,13 +97,39 @@ export const PRIMITIVE_PROP_ALLOWLIST: Readonly<Record<RenderKind, ReadonlySet<s
     "paths",
     "ariaLabel",
   ]),
-  media: allow(["src", "loop", "mute", "autoplay", "fit"]),
+  // `peerLabel` (ADR 006 #4) selects the live MediaStream mode : a node whose
+  // source is a `meet.peer.peer_label` is rendered in `srcObject` from a host
+  // resolver instead of `<video src>`. Listed so it is NOT flagged as a silent
+  // drop by the anti-drop audit when a scene carries a live source.
+  media: allow(["src", "peerLabel", "loop", "mute", "autoplay", "fit"]),
+  // ADR 006 §3.3/§3.5 — the unified source kind. `peer_label` is the stream
+  // reference (resolved to a MediaStream → srcObject) ; `object_fit`/`muted`
+  // drive the video ; `x-zab.sourceKind` is advisory ; `metadata` carries the
+  // editor round-trip (figma). Geometry is universal as flat `x/y/width/height`,
+  // but an UNCOMPILED from-scene node carries the NESTED `position`/`size` shape
+  // (the Tree flattens it as a fallback) — listed so neither form is flagged as
+  // a silent drop by the anti-drop audit.
+  "meet.peer": allow([
+    "peer_label",
+    "object_fit",
+    "muted",
+    "x-zab.sourceKind",
+    "metadata",
+    "position",
+    "size",
+  ]),
   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"]),
+  // ADR Blue 009 §3.1 (Amendment 2) — vendor meet-peer SLOT placeholder.
+  // `width`/`height` are the flattened geometry (universal) ; `x-zab.slotRef`
+  // is the logical slot identity carried as metadata (the runtime resolves
+  // `slotRef → peer_label` from stream-level ZabCam state). NO cam/peer
+  // identity is carried. Listed so they are NOT flagged as silent drops.
+  "x-zab.meet-peer": allow(["x-zab.slotRef", "width", "height"]),
   // `repeat` is dispatched specially by the tree ; its only consumed
   // binding is `items`.
   repeat: new Set(["items"]),