@lumencast/runtime 0.8.0 → 0.10.0

package/src/render/prop-allowlist.ts

@@ -97,8 +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"]),

package/src/render/tree.tsx

@@ -326,20 +326,47 @@ function finite(v: unknown): number | undefined {
  *  the compiler-flattened `resolved.x`/`resolved.y`. BOTH axes must be
  *  finite numbers : a partial or malformed pair yields `undefined` (the
  *  node stays in the normal flow — RC#3 mistyped-position is inert, not
- *  injected). Values are plain numbers, never untrusted strings. */
+ *  injected). Values are plain numbers, never untrusted strings.
+ *
+ *  ADR 006 §3.3 — a `meet.peer` node produced DIRECTLY by the Prism from-scene
+ *  export bypasses `@lumencast/compiler`, so its geometry arrives in the NESTED
+ *  LSML shape (`position:{x,y}`) rather than flattened `x`/`y`. We accept that
+ *  nested form as a fallback ONLY when the flat form is absent. This is purely
+ *  additive : every compiled bundle always carries flat `x`/`y` (which win), so
+ *  no existing node's placement changes. */
 function extractPosition(resolved: Record<string, unknown>): { x: number; y: number } | undefined {
-  const x = finite(resolved.x);
-  const y = finite(resolved.y);
+  let x = finite(resolved.x);
+  let y = finite(resolved.y);
+  if (x === undefined && y === undefined) {
+    const nested = resolved.position as { x?: unknown; y?: unknown } | undefined;
+    if (nested && typeof nested === "object") {
+      x = finite(nested.x);
+      y = finite(nested.y);
+    }
+  }
   if (x === undefined || y === undefined) return undefined;
   return { x, y };
 }
 
 /** ADR 002 §3.1 (D1) — the absolute box size from `resolved.width`/
  *  `resolved.height`. Only meaningful alongside `position` (the wrapper
- *  ignores it otherwise). Partial sizes are allowed (one axis hugs). */
+ *  ignores it otherwise). Partial sizes are allowed (one axis hugs).
+ *
+ *  ADR 006 §3.3 — like `extractPosition`, accept the NESTED `size:{w,h}` shape
+ *  as a fallback for an uncompiled `meet.peer` node (flat `width`/`height`
+ *  always win when present, so compiled bundles are unaffected). Without this,
+ *  the `meet.peer` wrapper got a position but NO size → the `<video>` filled a
+ *  collapsed box instead of the authored geometry (the observed RC-Geo bug). */
 function extractSize(resolved: Record<string, unknown>): { w?: number; h?: number } | undefined {
-  const w = finite(resolved.width);
-  const h = finite(resolved.height);
+  let w = finite(resolved.width);
+  let h = finite(resolved.height);
+  if (w === undefined && h === undefined) {
+    const nested = resolved.size as { w?: unknown; h?: unknown } | undefined;
+    if (nested && typeof nested === "object") {
+      w = finite(nested.w);
+      h = finite(nested.h);
+    }
+  }
   if (w === undefined && h === undefined) return undefined;
   return { w, h };
 }
@@ -353,8 +380,17 @@ function childIsAbsolute(child: RenderNode): boolean {
   if (child.kind === "frame") return false; // a frame positions itself
   const props = child.props ?? {};
   const bindings = child.bindings ?? {};
-  const hasX = finite(props.x) !== undefined || "x" in bindings;
-  const hasY = finite(props.y) !== undefined || "y" in bindings;
+  // ADR 006 §3.3 — also recognise the nested `position:{x,y}` shape (an
+  // uncompiled `meet.peer` node), mirroring extractPosition's fallback.
+  const nested = props.position as { x?: unknown; y?: unknown } | undefined;
+  const hasX =
+    finite(props.x) !== undefined ||
+    "x" in bindings ||
+    (nested ? finite(nested.x) !== undefined : false);
+  const hasY =
+    finite(props.y) !== undefined ||
+    "y" in bindings ||
+    (nested ? finite(nested.y) !== undefined : false);
   return hasX && hasY;
 }
 

package/src/types.ts

@@ -1,6 +1,8 @@
 // Public types of @lumencast/runtime — must align with RUNTIME-API.md.
 
 import type { ErrorCode } from "@lumencast/protocol";
+import type { ResolveCaptureDevice } from "./render/primitives/capture";
+import type { ResolvePeerStream, SubscribePeerStream } from "./render/primitives/media";
 
 export type LumencastMode = "broadcast" | "control" | "test";
 
@@ -69,6 +71,27 @@ 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;
+  /** ADR 006 #4 — host resolver for the `media` primitive's LIVE mode. Given a
+   *  LOGICAL `peerLabel` (a `meet.peer.peer_label` from the scene), return the
+   *  live `MediaStream` of that peer, or `null` when it is not connected yet.
+   *  Supplied by the WebRTC viewer (issue #3) ; the stream is rendered in
+   *  `<video>.srcObject` and NEVER enters the bundle or the content hash. Omit
+   *  it and a live `media` node renders a stream-less box, never throwing. */
+  resolvePeerStream?: ResolvePeerStream;
+  /** ADR 006 #3 — reactive variant of `resolvePeerStream` : 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. `createPeerViewer()` returns one.
+   *  Preferred over `resolvePeerStream` when both are supplied. */
+  subscribePeerStream?: SubscribePeerStream;
 }
 
 export interface LumencastHandle {

package/src/webrtc/index.ts

@@ -0,0 +1,252 @@
+// WebRTC viewer — public surface (ADR 006 §3.3, issue #3).
+//
+// `createPeerViewer` wires a `MeetViewer` (mesh, viewer role) to a
+// `PeerStreamRegistry` and returns the `resolvePeerStream` / `subscribePeerStream`
+// the `media` primitive's LIVE mode (#4) consumes via `MountOptions`. This is
+// the #3↔#4 bridge : the viewer receives peers, the registry maps
+// `peer_label → MediaStream`, the primitive renders it in `<video srcObject>`.
+//
+// MULTI-ROOM (final model) : `createMultiRoomPeerViewer({ rooms: [...] })` joins
+// EVERY room with its own mesh and feeds ONE shared registry, so the `meet.peer`
+// renderer resolves a `peer_label` to its stream whatever room it came from.
+
+import { MeetViewer, type MeetViewerOptions, type RemoteTrackEvent } from "./meet-viewer.js";
+import {
+  createPeerStreamRegistry,
+  type PeerStreamListener,
+  type PeerStreamRegistry,
+} from "./peer-stream-registry.js";
+
+export {
+  MeetViewer,
+  type MeetViewerOptions,
+  type MeetViewerDeps,
+  type PeerInfo,
+  type RemoteTrackEvent,
+} from "./meet-viewer.js";
+export {
+  createPeerStreamRegistry,
+  type PeerStreamRegistry,
+  type PeerStreamListener,
+} from "./peer-stream-registry.js";
+
+export interface PeerViewer {
+  /** Join the room(s) (viewer role, no capture). */
+  join: () => Promise<void>;
+  /** Leave + tear down all peer connections (the track owner releases here). */
+  leave: () => void;
+  /** #4 contract — pass to `mount({ resolvePeerStream })`. Synchronous. */
+  resolvePeerStream: (peerLabel: string) => MediaStream | null;
+  /** Push channel for the LIVE primitive to re-render on connect/disconnect. */
+  subscribePeerStream: (peerLabel: string, listener: PeerStreamListener) => () => void;
+  /** The underlying registry, for advanced hosts. */
+  registry: PeerStreamRegistry;
+  /** Single-room only — the underlying mesh, for diagnostics. Absent in the
+   *  multi-room viewer (it owns N meshes). */
+  viewer?: MeetViewer;
+}
+
+/** Feed a (possibly shared) registry from ONE viewer's lifecycle. A label is
+ *  owned by the FIRST room that connects it (`label-collision` policy) : `claim`
+ *  decides whether this viewer may publish/withdraw a given label, so a second
+ *  room carrying the same `peer_label` never clobbers the first. Returns the
+ *  viewer + a `dispose` that closes the mesh and releases this viewer's labels. */
+/** Normalise a peer name / peer_label into the SAME key both sides agree on.
+ *  The publisher announces a FREE name on the mesh (e.g. "Publisher 366"), but
+ *  the scene's `peer_label` is slugified at LSML export (from-scene → "publisher
+ *  _366", per source-node.ts `slugifyToLabel`). Strict `peerName === peer_label`
+ *  therefore never matches. Applying the SAME slug to BOTH the indexing side
+ *  (peerName) and the resolution side (peer_label) makes the map work regardless
+ *  of format (a raw label and its slug collapse to the same key). Mirrors
+ *  Prism `slugifyToLabel`. */
+export function labelKey(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "_")
+    .replace(/^[_-]+|[_-]+$/g, "");
+}
+
+function wireViewer(
+  viewer: MeetViewer,
+  registry: PeerStreamRegistry,
+  claim: {
+    acquire: (label: string, viewer: MeetViewer) => boolean;
+    release: (label: string, viewer: MeetViewer) => void;
+  },
+): void {
+  // Index the registry by the NORMALISED label (slug of peerName), so it matches
+  // the scene node's slugified `peer_label`. Never the opaque `peerId`.
+  viewer.on("remote-track", (e: RemoteTrackEvent) => {
+    const key = labelKey(e.peerName);
+    if (claim.acquire(key, viewer)) registry.set(key, e.stream);
+  });
+  viewer.on("peer-left", (e) => {
+    const key = labelKey(e.peerName);
+    if (claim.acquire(key, viewer)) {
+      registry.remove(key);
+      claim.release(key, viewer);
+    }
+  });
+}
+
+/** Single-room ownership : trivially, this lone viewer owns every label. */
+const SOLE_OWNER = {
+  acquire: () => true,
+  release: () => {},
+};
+
+/** Build a viewer + registry for a SINGLE room and expose the #4 resolver.
+ *  (Back-compat surface — `createMultiRoomPeerViewer` is the final model.) */
+export function createPeerViewer(options: MeetViewerOptions): PeerViewer {
+  const registry = createPeerStreamRegistry();
+  const viewer = new MeetViewer(options);
+  wireViewer(viewer, registry, SOLE_OWNER);
+  return {
+    join: () => viewer.join(),
+    leave: () => {
+      viewer.leave();
+      registry.clear();
+    },
+    resolvePeerStream: (peerLabel) => registry.resolve(labelKey(peerLabel)),
+    subscribePeerStream: (peerLabel, listener) => registry.subscribe(labelKey(peerLabel), listener),
+    registry,
+    viewer,
+  };
+}
+
+/** A single room's connection params (one mesh per entry). */
+export type RoomOptions = Omit<MeetViewerOptions, "name"> & {
+  /** This viewer's announce name on the mesh. Defaults to "solar-viewer". */
+  name?: string;
+};
+
+export interface MultiRoomPeerViewerOptions {
+  rooms: RoomOptions[];
+  /** Shared deps (WS/RTCPeerConnection/MediaStream) applied to every room when a
+   *  room entry does not override them — used to test without a browser stack. */
+  deps?: MeetViewerOptions["deps"];
+}
+
+export interface MultiRoomPeerViewer extends PeerViewer {
+  /** Reconcile the live room set : open meshes for new rooms, close meshes for
+   *  removed ones (matched by `roomId`). Best-effort ; idempotent for an
+   *  unchanged set. Newly opened rooms are joined immediately. */
+  setRooms: (rooms: RoomOptions[]) => Promise<void>;
+}
+
+/** The FINAL viewer model : join N rooms, aggregate every peer into ONE shared
+ *  registry keyed by `peer_label`. The `meet.peer` renderer resolves a label to
+ *  its stream regardless of which room the peer published in.
+ *
+ *  LABEL COLLISION (improbable at the POC) : FIRST-CONNECTED-WINS. The room that
+ *  first connects a `peer_label` owns it ; a second room carrying the same label
+ *  is ignored until the owner releases it (on the owner's `peer-left`). This is
+ *  deterministic and never flips a live source under the compositor.
+ *
+ *  LIFECYCLE : one mesh per room ; `leave()` closes all. `setRooms()` reconciles
+ *  on re-arm (close removed rooms, open new ones), matched by `roomId`. */
+export function createMultiRoomPeerViewer(
+  options: MultiRoomPeerViewerOptions,
+): MultiRoomPeerViewer {
+  const registry = createPeerStreamRegistry();
+  // roomId → { viewer, joined }
+  const meshes = new Map<string, { viewer: MeetViewer }>();
+  // peer_label → owning viewer (first-connected-wins).
+  const owners = new Map<string, MeetViewer>();
+
+  const claim = {
+    acquire: (label: string, viewer: MeetViewer): boolean => {
+      const owner = owners.get(label);
+      if (owner === undefined) {
+        owners.set(label, viewer);
+        return true;
+      }
+      return owner === viewer; // only the owning room may publish/withdraw
+    },
+    release: (label: string, viewer: MeetViewer): void => {
+      if (owners.get(label) === viewer) owners.delete(label);
+    },
+  };
+
+  function openRoom(room: RoomOptions): void {
+    if (meshes.has(room.roomId)) return; // idempotent
+    const viewer = new MeetViewer({
+      name: room.name ?? "solar-viewer",
+      ...room,
+      ...(options.deps !== undefined && room.deps === undefined ? { deps: options.deps } : {}),
+    });
+    wireViewer(viewer, registry, claim);
+    meshes.set(room.roomId, { viewer });
+  }
+
+  function closeRoom(roomId: string): void {
+    const mesh = meshes.get(roomId);
+    if (mesh === undefined) return;
+    // Release every label this viewer owns BEFORE closing, so a surviving room
+    // can take over the label and the registry drops the gone stream.
+    for (const [label, owner] of [...owners.entries()]) {
+      if (owner === mesh.viewer) {
+        registry.remove(label);
+        owners.delete(label);
+      }
+    }
+    mesh.viewer.leave();
+    meshes.delete(roomId);
+  }
+
+  for (const room of options.rooms) openRoom(room);
+
+  return {
+    join: async () => {
+      await Promise.all([...meshes.values()].map((m) => m.viewer.join()));
+    },
+    leave: () => {
+      for (const roomId of [...meshes.keys()]) closeRoom(roomId);
+      registry.clear();
+    },
+    setRooms: async (rooms) => {
+      const next = new Set(rooms.map((r) => r.roomId));
+      // Close rooms no longer present.
+      for (const roomId of [...meshes.keys()]) {
+        if (!next.has(roomId)) closeRoom(roomId);
+      }
+      // Open + join rooms newly added.
+      const added: MeetViewer[] = [];
+      for (const room of rooms) {
+        if (!meshes.has(room.roomId)) {
+          openRoom(room);
+          const m = meshes.get(room.roomId);
+          if (m) added.push(m.viewer);
+        }
+      }
+      await Promise.all(added.map((v) => v.join()));
+    },
+    resolvePeerStream: (peerLabel) => registry.resolve(labelKey(peerLabel)),
+    subscribePeerStream: (peerLabel, listener) => registry.subscribe(labelKey(peerLabel), listener),
+    registry,
+  };
+}
+
+/** The shape the Prism host injects on `window.__ZAB_PEER_VIEWER__`. The FINAL
+ *  model is the multi-room `{ rooms: [...] }` ; the legacy single-room shape is
+ *  still accepted for back-compat (treated as a one-room array). */
+export type PeerViewerInjection =
+  | MultiRoomPeerViewerOptions
+  | (Omit<MeetViewerOptions, "name"> & { name?: string });
+
+/** Normalise either injection shape into a multi-room viewer. forge-prism passes
+ *  `window.__ZAB_PEER_VIEWER__` straight through ; a bare single-room object is
+ *  wrapped as `{ rooms: [it] }`. */
+export function createPeerViewerFromInjection(injection: PeerViewerInjection): MultiRoomPeerViewer {
+  if ("rooms" in injection && Array.isArray(injection.rooms)) {
+    return createMultiRoomPeerViewer(injection);
+  }
+  // Legacy single-room shape → one-room array.
+  const { name, deps, ...room } = injection as Omit<MeetViewerOptions, "name"> & {
+    name?: string;
+  };
+  return createMultiRoomPeerViewer({
+    rooms: [{ ...room, ...(name !== undefined ? { name } : {}) }],
+    ...(deps !== undefined ? { deps } : {}),
+  });
+}