@lumencast/runtime 0.12.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumencast/runtime",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "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.12.0"
+    "@lumencast/protocol": "0.12.2"
   },
   "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.12.0",
-    "@lumencast/server": "0.12.0"
+    "@lumencast/server": "0.12.2",
+    "@lumencast/dev-server": "0.12.2"
   },
   "scripts": {
     "dev": "vite",

package/src/render/bundle.ts

@@ -287,6 +287,7 @@ export interface BundleFetcherOptions {
 
 class FetcherImpl implements BundleFetcher {
   private readonly cache = new Map<string, RenderBundle>();
+  private readonly inFlight = new Map<string, Promise<RenderBundle>>();
   private readonly baseUrl: string;
   private readonly pathPrefix: string;
   private readonly resolveUrl: BundleUrlResolver | undefined;
@@ -329,6 +330,19 @@ class FetcherImpl implements BundleFetcher {
   async get(sceneId: string, sceneVersion: string): Promise<RenderBundle> {
     const cached = this.cache.get(sceneVersion);
     if (cached) return cached;
+    // Bundles are content-addressed by scene_version, so a concurrent miss for
+    // the same version can share a single fetch. The entry is cleared in
+    // `finally` — a rejected fetch is never cached, so a later call retries.
+    const existing = this.inFlight.get(sceneVersion);
+    if (existing) return existing;
+    const promise = this.fetchBundle(sceneId, sceneVersion).finally(() => {
+      this.inFlight.delete(sceneVersion);
+    });
+    this.inFlight.set(sceneVersion, promise);
+    return promise;
+  }
+
+  private async fetchBundle(sceneId: string, sceneVersion: string): Promise<RenderBundle> {
     const url = this.buildUrl(sceneId, sceneVersion);
     const init = await this.buildInit();
     const response = init ? await this.fetchImpl(url, init) : await this.fetchImpl(url);

package/src/render/primitives/capture-stream-cache.ts

@@ -0,0 +1,164 @@
+// Per-device stream cache for `x-zab.capture` ACQUIRE mode.
+//
+// Why this exists: a scene switch remounts the WHOLE render tree
+// (`AnimatePresence` keyed on the scene id in app.tsx / crossfade.tsx), so every
+// `Capture` node unmounts and a fresh one mounts. Without sharing, each switch
+// stops the old node's tracks (RC11) and re-acquires the same physical device in
+// the new node. A real USB webcam reopens near-instantly, but a synthetic
+// DirectShow filter (OBS Virtual Camera) renegotiates slowly → a visible blink
+// on every switch, because — by design (ADR 007 Prism) — every scene references
+// the SAME shared vcam device.
+//
+// The fix mirrors the editor's `use-live-source.ts`: a ref-counted cache keyed by
+// the resolved PHYSICAL device. Two `Capture` nodes on the same device share one
+// `getUserMedia`; tracks stop (RC11) only when the LAST consumer releases. During
+// a crossfade both the exiting and entering scenes are mounted at once
+// (`AnimatePresence mode="sync"`), so the ref-count never reaches 0 across a
+// switch and the device is never renegotiated — no blink.
+//
+// Cache key stability: the key is the resolved `deviceId` / `captureSourceId`, not
+// the raw logical `deviceRef`. Physical ids are salted per origin/partition (see
+// capture.tsx §A1.3), but the salt is constant WITHIN one runtime origin, so the
+// resolved id is stable across scene switches inside a single mount/session — the
+// exact scope over which sharing must hold. Keying on the physical id also
+// correctly de-dupes two distinct `deviceRef`s that resolve to the same device.
+
+import type { ResolveCaptureDevice } from "./capture";
+
+interface CacheEntry {
+  promise: Promise<MediaStream>;
+  stream: MediaStream | null;
+  refs: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/** Outcome of a claim: either a shared stream promise (with the key to release
+ *  later) or PLACEHOLDER — the unknown-kind / declared-but-unresolved-ref path
+ *  that acquires nothing, exactly as the old inline `acquireStream` returning
+ *  `null` did. A PLACEHOLDER claim holds NO ref (nothing to release). */
+export type CaptureClaim =
+  | { kind: "stream"; key: string; promise: Promise<MediaStream> }
+  | { kind: "placeholder" };
+
+/** Resolve the device, then claim a shared stream for it (incrementing the
+ *  ref-count), or return PLACEHOLDER. Awaits the resolver first — physical ids
+ *  are salted per origin/partition, so the host may re-resolve a portable key
+ *  (label) against THIS context (capture.tsx §A1.3). A throw from the underlying
+ *  `getUserMedia` surfaces via the returned promise (caller → PLACEHOLDER). */
+export async function claimCaptureStream(
+  sourceKind: string,
+  deviceRef: string,
+  resolveCaptureDevice: ResolveCaptureDevice | undefined,
+): Promise<CaptureClaim> {
+  const md = navigator.mediaDevices;
+  const resolved = (await resolveCaptureDevice?.(deviceRef, sourceKind)) ?? null;
+  const deviceId = resolved?.deviceId;
+  const captureSourceId = resolved?.captureSourceId;
+  const declaredRef = deviceRef.length > 0;
+
+  // Compute a stable physical key + a lazy acquisition thunk, or bail to
+  // PLACEHOLDER for the same reasons the inline switch used to return `null`.
+  let physicalId: string;
+  let acquire: () => Promise<MediaStream>;
+  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. Acquiring the host default here is the silent
+      // "automatic allocation" of the WRONG camera. → PLACEHOLDER. The bare
+      // default constraint stays ONLY when no deviceRef is declared at all.
+      if (declaredRef && (typeof deviceId !== "string" || deviceId.length === 0)) {
+        return { kind: "placeholder" };
+      }
+      const channel = sourceKind === "media.webcam" ? "video" : "audio";
+      physicalId = typeof deviceId === "string" && deviceId.length > 0 ? deviceId : "default";
+      acquire = () => md.getUserMedia({ [channel]: deviceConstraint(deviceId) });
+      break;
+    }
+    case "media.screen":
+    case "media.window": {
+      // DIRECT capture of the picked desktopCapturer surface (no system picker)
+      // via Electron's legacy `chromeMediaSource:desktop` + resolved id.
+      if (typeof captureSourceId === "string" && captureSourceId.length > 0) {
+        physicalId = captureSourceId;
+        acquire = () =>
+          md.getUserMedia({
+            video: {
+              mandatory: {
+                chromeMediaSource: "desktop",
+                chromeMediaSourceId: captureSourceId,
+              },
+            } as unknown as MediaTrackConstraints,
+          });
+        break;
+      }
+      // A declared surface ref that didn't resolve → PLACEHOLDER, never a
+      // default picker. The picker stays only when no ref is declared.
+      if (declaredRef) return { kind: "placeholder" };
+      physicalId = "display";
+      acquire = () => md.getDisplayMedia({ video: true });
+      break;
+    }
+    default:
+      return { kind: "placeholder" };
+  }
+
+  const key = `${sourceKind}:${physicalId}`;
+  const existing = cache.get(key);
+  if (existing) {
+    existing.refs += 1;
+    return { kind: "stream", key, promise: existing.promise };
+  }
+  const promise = acquire();
+  const entry: CacheEntry = { promise, stream: null, refs: 1 };
+  cache.set(key, entry);
+  promise
+    .then((s) => {
+      entry.stream = s;
+    })
+    .catch(() => {
+      // Acquisition failed — evict so a later mount retries instead of sharing a
+      // rejected promise. Consumers of this promise all fall back to PLACEHOLDER.
+      cache.delete(key);
+    });
+  return { kind: "stream", key, promise };
+}
+
+/** Drop one consumer's claim. Stops every track (RC11 — kill the device light)
+ *  ONLY when the last consumer releases. A no-op for an already-evicted key
+ *  (e.g. an acquisition that rejected and self-evicted). */
+export function releaseCaptureStream(key: string): void {
+  const entry = cache.get(key);
+  if (entry === undefined) return;
+  entry.refs -= 1;
+  if (entry.refs > 0) return;
+  cache.delete(key);
+  if (entry.stream !== null) stopStream(entry.stream);
+}
+
+/** 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 enumerated but producing no stream). `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 light). */
+function stopStream(stream: MediaStream): void {
+  for (const track of stream.getTracks()) track.stop();
+}
+
+/** Test-only: drop all cached entries WITHOUT stopping tracks. Lets a test file
+ *  start from a clean ref-count without leaking state between cases. */
+export function __resetCaptureStreamCache(): void {
+  cache.clear();
+}

package/src/render/primitives/capture.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import type { PrimitiveProps } from "./index";
 import { useOptionalLumencastRuntime } from "../../overlay/runtime-context";
+import { claimCaptureStream, releaseCaptureStream } from "./capture-stream-cache";
 
 /** `x-zab.capture` — context-aware capture primitive (Zab vendor primitive,
  *  RFC-0001 / ADR 004 §Amendment 1).
@@ -62,32 +63,38 @@ export function Capture({ resolved }: PrimitiveProps) {
     if (!isCaptureCapable()) return;
 
     let cancelled = false;
-    let acquired: MediaStream | null = null;
+    // The cache key of the claim we hold, so cleanup releases exactly one ref.
+    let claimedKey: string | null = null;
 
     void (async () => {
       try {
-        const media = await acquireStream(sourceKind, deviceRef, resolveCaptureDevice);
-        if (media === null) return; // unknown/unsupported kind → PLACEHOLDER
+        // Claim a per-device shared stream (ref-counted): a scene switch that
+        // remounts a Capture on the SAME device reuses the live stream instead
+        // of stopping and re-acquiring it — the vcam-blink fix.
+        const claim = await claimCaptureStream(sourceKind, deviceRef, resolveCaptureDevice);
+        if (claim.kind === "placeholder") return; // unknown/unresolved → PLACEHOLDER
+        const media = await claim.promise;
         if (cancelled) {
-          // Unmounted (or scene-changed) during acquisition — stop immediately
-          // so we never leave a camera light on (RC11).
-          stopStream(media);
+          // Unmounted (or scene-changed) during acquisition — drop our claim.
+          // The shared stream stays alive if another consumer still holds it,
+          // and stops (RC11) only when the last one releases.
+          releaseCaptureStream(claim.key);
           return;
         }
-        acquired = media;
+        claimedKey = claim.key;
         setStream(media);
       } catch {
         // §A1.2(2)(a) — any acquisition failure (permission denied, no device,
         // getUserMedia rejected) falls back to PLACEHOLDER, no throw, no
-        // diagnostic.
+        // diagnostic. The rejected cache entry self-evicts; our ref went with it.
       }
     })();
 
     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);
+      // RC11 — release our claim at unmount / scene change. Tracks stop only
+      // when this was the last consumer of the shared stream.
+      if (claimedKey !== null) releaseCaptureStream(claimedKey);
     };
     // Re-acquire when the logical source identity changes (a scene switch can
     // reuse the node with a new sourceKind/deviceRef).
@@ -142,7 +149,7 @@ export type ResolvedCaptureDevice = {
  *  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
+ *  (`enumerateDevices`). `claimCaptureStream` awaits it, so the device is bound
  *  before acquisition rather than racing a late global mutation. */
 export type ResolveCaptureDevice = (
   deviceRef: string,
@@ -165,87 +172,6 @@ function isVisualKind(sourceKind: string): boolean {
   );
 }
 
-/** 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 {