@lumencast/runtime 0.10.0 → 0.11.0

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 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";
 export type LumencastStatus = "disconnected" | "connecting" | "live";
 export interface LumencastTokenProvider {
@@ -76,6 +77,17 @@ export interface MountOptions {
      *  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 {
     /** Tear down the WS, unmount the React tree, release timers. Idempotent. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAExF,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,eAAe,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;+BAE+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C;;;yDAGqD;IACrD,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACzD;;;;;;;yEAOqE;IACrE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;;gFAK4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;qEAGiE;IACjE,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,eAAe,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;+BAE+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,CAAC;IACrE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IAC7C;;;yDAGqD;IACrD,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACzD;;;;;;;yEAOqE;IACrE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;;gFAK4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;qEAGiE;IACjE,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;;;;;;;kDAS8C;IAC9C,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Browser runtime for Lumencast — mount(), LSDP/1 transport, leaf-grain store, LSML render, animations, overlays.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,7 +36,7 @@
     "framer-motion": "^12.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@lumencast/protocol": "0.10.0"
+    "@lumencast/protocol": "0.11.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
@@ -50,8 +50,8 @@
     "vite-plugin-dts": "^4.5.0",
     "vitest": "^4.1.5",
     "ws": "^8.18.0",
-    "@lumencast/dev-server": "0.10.0",
-    "@lumencast/server": "0.10.0"
+    "@lumencast/server": "0.11.0",
+    "@lumencast/dev-server": "0.11.0"
   },
   "scripts": {
     "dev": "vite",

package/src/index.ts

@@ -37,6 +37,18 @@ export type { ResolveCaptureDevice } from "./render/primitives/capture.js";
 // runtime's contract.
 export type { ResolvePeerStream, SubscribePeerStream } from "./render/primitives/media.js";
 
+// ADR Blue 009 §3.2–3.3 — reserved `__cam.*` LSDP leaves (slot→peer assignments
+// + receive-only viewer creds) surfaced to the host via `MountOptions
+// .onReservedLeaves`. Exported so the consuming host (Solar) types its sink and
+// reuses the reserved-path predicate / wire-name constants without re-deriving.
+export {
+  CAM_RESERVED_PREFIX,
+  CAM_SLOTS_PREFIX,
+  CAM_VIEWER_LEAF,
+  isReservedCamPath,
+  type ReservedCamLeaves,
+} from "./state/reserved-leaves.js";
+
 // ADR 006 #3 — WebRTC viewer (mesh, viewer role) + peer-stream registry. The
 // #3↔#4 bridge : a viewer joins Meet room(s), receives N peers and returns the
 // `resolvePeerStream` / `subscribePeerStream` the `media`/`meet.peer` LIVE render

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,

package/src/render/primitives/index.ts

@@ -13,6 +13,7 @@ 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
@@ -55,4 +56,9 @@ export const PRIMITIVES: Partial<Record<RenderKind, ComponentType<PrimitiveProps
   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/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/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

@@ -3,6 +3,7 @@
 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";
 
@@ -92,6 +93,17 @@ export interface MountOptions {
    *  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 {