@lumencast/runtime 0.9.0 → 0.11.0

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/state/reserved-leaves.ts

@@ -0,0 +1,121 @@
+// Reserved `__cam.*` LSDP leaves — surfaced to the host, never rendered.
+//
+// ADR Blue 009 §3.2–3.3 (axe 1, antenne). The meet-cam antenne path needs two
+// pieces of RUNTIME, stream-level ZabCam state that travel on the LSDP wire as
+// RESERVED leaves (they bind to no node and are never painted) :
+//
+//   - `__cam.slots.<slotRef>` = "<peer_label>"  (Orion #267 deltas, §3.3)
+//        which peer currently fills an authored `x-zab.meet-peer` slot.
+//   - `__cam.viewer` = { rooms: [{ signalingUrl, roomId, token }] }  (Orion #268)
+//        the receive-only viewer credentials for the active stream.
+//
+// The runtime does NOT join rooms, hold creds, or re-key slots itself — that is
+// the host's WebRTC viewer (Solar `peer-viewer/*`). The runtime's only job is to
+// SURFACE these reserved leaves to the host through `MountOptions.onReservedLeaves`
+// so Solar can feed `__cam.viewer` into its viewer injection and drive its
+// slot-binding registry's `assign(slotRef, peer_label | null)` from `__cam.slots.*`.
+// Receive-only : the token flows host→viewer→join ; the runtime never reads it.
+
+/** Every reserved cam leaf lives under this prefix. */
+export const CAM_RESERVED_PREFIX = "__cam.";
+
+/** One scalar leaf per bound slot : `__cam.slots.<slotRef>` = "<peer_label>"
+ *  (ADR Blue 009 §3.3). Mirrors Solar's `CAM_SLOTS_PREFIX` — keep them in sync. */
+export const CAM_SLOTS_PREFIX = "__cam.slots.";
+
+/** The single viewer-credentials leaf (ADR Blue 009 §3.2, Orion #268). */
+export const CAM_VIEWER_LEAF = "__cam.viewer";
+
+/** The reserved cam state surfaced to the host in one shot on every change. */
+export interface ReservedCamLeaves {
+  /** `__cam.viewer` — receive-only viewer creds for the active stream. Opaque to
+   *  the runtime (shape `{ rooms: [{ signalingUrl, roomId, token }] }` validated
+   *  host-side) ; `undefined` when the leaf is absent. */
+  viewer?: unknown;
+  /** `slotRef → peer_label` snapshot from the `__cam.slots.*` subtree. A slot
+   *  ABSENT from this map is UNBOUND — the host releases it (`assign(slotRef,
+   *  null)`) so the `x-zab.meet-peer` node falls back to its placeholder. Only
+   *  non-empty string values are kept. */
+  slots: Record<string, string>;
+}
+
+/** A reserved cam leaf the runtime forwards rather than renders. */
+export function isReservedCamPath(path: string): boolean {
+  return path === CAM_VIEWER_LEAF || path.startsWith(CAM_SLOTS_PREFIX);
+}
+
+/** Project a raw reserved-leaf state into the host-facing shape. Defensive : a
+ *  malformed slot value (non-string / empty) or empty slotRef is dropped. */
+function project(raw: Map<string, unknown>): ReservedCamLeaves {
+  const slots: Record<string, string> = {};
+  let viewer: unknown;
+  for (const [path, value] of raw) {
+    if (path === CAM_VIEWER_LEAF) {
+      if (value !== undefined && value !== null) viewer = value;
+    } else if (path.startsWith(CAM_SLOTS_PREFIX)) {
+      const slotRef = path.slice(CAM_SLOTS_PREFIX.length);
+      if (slotRef !== "" && typeof value === "string" && value !== "") slots[slotRef] = value;
+    }
+  }
+  return viewer !== undefined ? { viewer, slots } : { slots };
+}
+
+/** A stable identity key for change detection — two `ReservedCamLeaves` with the
+ *  same content always produce the same key regardless of insertion order. */
+function identity(leaves: ReservedCamLeaves): string {
+  const slots = Object.keys(leaves.slots)
+    .sort()
+    .map((k) => `${k}=${leaves.slots[k]}`)
+    .join("&");
+  const viewer = leaves.viewer === undefined ? "" : JSON.stringify(leaves.viewer);
+  return `${slots}|${viewer}`;
+}
+
+export interface ReservedLeafObserver {
+  /** Reseed from a full snapshot's state (reserved leaves not present are
+   *  dropped). Emits when the projected state changed. */
+  onSnapshot(state: Record<string, unknown>): void;
+  /** Apply a delta's patches ; emits only when a reserved leaf actually moved. */
+  onDelta(patches: ReadonlyArray<{ path: string; value: unknown }>): void;
+}
+
+/** Track the reserved `__cam.*` leaves across snapshots + deltas and `emit` the
+ *  host-facing projection whenever it changes (de-duplicated by content, so an
+ *  unrelated scene's deltas never call back). Created only when the host supplies
+ *  `onReservedLeaves` — zero cost otherwise. */
+export function createReservedLeafObserver(
+  emit: (leaves: ReservedCamLeaves) => void,
+): ReservedLeafObserver {
+  const raw = new Map<string, unknown>();
+  // Seed with the empty projection's identity so a plain scene (no cam leaves)
+  // never fires a spurious empty emit ; a later transition to/from cam state does.
+  let last = identity({ slots: {} });
+
+  const flush = (): void => {
+    const leaves = project(raw);
+    const key = identity(leaves);
+    if (key === last) return;
+    last = key;
+    emit(leaves);
+  };
+
+  return {
+    onSnapshot(state) {
+      raw.clear();
+      for (const [path, value] of Object.entries(state)) {
+        if (isReservedCamPath(path)) raw.set(path, value);
+      }
+      flush();
+    },
+    onDelta(patches) {
+      let touched = false;
+      for (const patch of patches) {
+        if (isReservedCamPath(patch.path)) {
+          raw.set(patch.path, patch.value);
+          touched = true;
+        }
+      }
+      if (touched) flush();
+    },
+  };
+}

package/src/types.ts

@@ -2,6 +2,8 @@
 
 import type { ErrorCode } from "@lumencast/protocol";
 import type { ResolveCaptureDevice } from "./render/primitives/capture";
+import type { ResolvePeerStream, SubscribePeerStream } from "./render/primitives/media";
+import type { ReservedCamLeaves } from "./state/reserved-leaves";
 
 export type LumencastMode = "broadcast" | "control" | "test";
 
@@ -79,6 +81,29 @@ export interface MountOptions {
    *  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;
+  /** ADR Blue 009 §3.2–3.3 — host sink for the reserved `__cam.*` LSDP leaves
+   *  (never rendered, never bound to a node). Called with the full current
+   *  projection whenever it changes : `viewer` carries the receive-only viewer
+   *  creds (`__cam.viewer`, Orion #268) and `slots` the `slotRef → peer_label`
+   *  snapshot (`__cam.slots.*`, Orion #267). The host (Solar) feeds `viewer` into
+   *  its peer-viewer injection and drives its slot-binding registry's
+   *  `assign(slotRef, peer_label | null)` so `x-zab.meet-peer` nodes re-key by
+   *  `slotRef`. Receive-only : the runtime forwards the token verbatim, never
+   *  reads it. Omit it and the reserved leaves are simply not surfaced (the
+   *  preview/headless paths are unaffected). */
+  onReservedLeaves?: (leaves: ReservedCamLeaves) => void;
 }
 
 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 } : {}),
+  });
+}