@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.244.1

package/server/native-video-extension-source.ts

@@ -0,0 +1,364 @@
+/**
+ * Trusted extension-page program. It captures one exact tab, never reads site DOM,
+ * and shares a bounded native track among at most three independent encoders.
+ * Binding acknowledgements limit outstanding packets; a dropped output forces a
+ * new keyframe before another delta can be forwarded.
+ */
+export const NATIVE_VIDEO_EXTENSION_SOURCE = `
+let capture = null;
+const encoders = new Map();
+const pendingEncoders = new Map();
+const bytes64 = (bytes) => {
+  // Native byte conversion avoids constructing/copying a large binary string.
+  // Retain the bounded legacy path for browsers without the newer byte API.
+  if (typeof bytes.toBase64 === "function") return bytes.toBase64();
+  let result = "";
+  for (let offset = 0; offset < bytes.length; offset += 8192) {
+    result += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+  }
+  return btoa(result);
+};
+/** Revoke the source, codecs and pending allocations before awaiting reader cleanup. */
+async function stopCapture() {
+  const previous = capture;
+  capture = null;
+  pendingEncoders.clear();
+  if (!previous) return;
+  previous.stopped = true;
+  for (const encoder of encoders.values()) {
+    try {
+      encoder.encoder.close();
+    } catch {}
+  }
+  encoders.clear();
+  for (const track of previous.stream.getTracks()) track.stop();
+  await previous.reader.cancel().catch(() => {});
+  await previous.loop.catch(() => {});
+}
+/** Preserve requested geometry across Chromium's even-aligned YUV capture.
+ * Only the known one-pixel rounding is resampled by VideoEncoder. Other source
+ * changes remain failures; cloning retains the source timestamp and lifetime.
+ */
+function frameForViewport(frame, width, height) {
+  if (frame.displayWidth === width && frame.displayHeight === height) return frame;
+  if (
+    !["I420", "NV12"].includes(frame.format) ||
+    frame.displayWidth !== (width & ~1) ||
+    frame.displayHeight !== (height & ~1)
+  ) return null;
+  return new VideoFrame(frame, { displayWidth: width, displayHeight: height });
+}
+/** Start one exact tab at physical pixel dimensions; generation fences previously queued frames. */
+async function startCapture(targetId, width, height, generation) {
+  await stopCapture();
+  let stream;
+  try {
+    const targets = await chrome.debugger.getTargets();
+    const matched = targets.filter(
+      (target) =>
+        target.id === targetId && target.type === "page" && Number.isInteger(target.tabId),
+    );
+    if (matched.length !== 1) throw new Error("Exact capture target is unavailable");
+    const sourceId = await chrome.tabCapture.getMediaStreamId({ targetTabId: matched[0].tabId });
+    stream = await navigator.mediaDevices.getUserMedia({
+      audio: false,
+      video: {
+        mandatory: {
+          chromeMediaSource: "tab",
+          chromeMediaSourceId: sourceId,
+          maxWidth: width,
+          maxHeight: height,
+          minFrameRate: 1,
+          maxFrameRate: 60,
+        },
+      },
+    });
+    const track = stream.getVideoTracks()[0];
+    const reader = new MediaStreamTrackProcessor({ track, maxBufferSize: 1 }).readable.getReader();
+    const current = {
+      stream,
+      reader,
+      width,
+      height,
+      generation,
+      minimumTimestampUs: -Infinity,
+      stopped: false,
+      loop: null,
+    };
+    capture = current;
+    current.loop = (async () => {
+      try {
+        while (capture === current && !current.stopped) {
+          const { value: frame, done } = await reader.read();
+          if (done) {
+            if (capture === current && !current.stopped)
+              nativeVideoPacket(JSON.stringify({ error: "Native video capture stopped" }));
+            break;
+          }
+          let encodingFrame = null;
+          try {
+            if (capture !== current || current.stopped) break;
+            if (frame.timestamp < current.minimumTimestampUs) continue;
+            encodingFrame = frameForViewport(frame, width, height);
+            if (!encodingFrame) {
+              // Only native YUV even-alignment is correctable. Keep unexpected
+              // source geometry terminal without changing viewport or density.
+              nativeVideoPacket(
+                JSON.stringify({
+                  error: "Native video dimensions changed",
+                  reasonCode: "source-dimensions",
+                }),
+              );
+              break;
+            }
+            for (const state of encoders.values()) {
+              if (state.failed || performance.now() - state.lastRequestedAt > 2000) continue;
+              if (state.pending.size >= 2 || state.encoder.encodeQueueSize >= 2) {
+                // This source frame was never encoded, so skipping it does not
+                // lose a codec dependency. Keep already queued output usable.
+                // The output callback below still forces recovery if it must
+                // discard an actual encoded chunk.
+                continue;
+              }
+              // Source timestamps are integer microseconds. Allow one microsecond
+              // of rounding so genuine 30fps timestamps do not become 15fps.
+              const minimumIntervalUs = 1000000 / state.configuration.framerate;
+              // Recovery uses the next fresh frame even inside the ordinary FPS interval.
+              // Producer/encoder backlog checks above still apply to forced keys.
+              if (
+                !state.forceKey &&
+                frame.timestamp - state.lastEncodedTimestampUs < minimumIntervalUs - 1
+              )
+                continue;
+              state.lastEncodedTimestampUs = frame.timestamp;
+              state.frameGenerations.set(frame.timestamp, current.generation);
+              while (state.frameGenerations.size > 4)
+                state.frameGenerations.delete(state.frameGenerations.keys().next().value);
+              const keyFrame =
+                state.forceKey || frame.timestamp - state.lastKeyTimestamp >= 1000000;
+              try {
+                state.encoder.encode(encodingFrame, { keyFrame });
+              } catch {
+                // A synchronous codec rejection belongs to this cohort, just
+                // like its asynchronous error callback. Healthy peers keep the track.
+                state.failed = true;
+                try {
+                  state.encoder.close();
+                } catch {}
+                state.frameGenerations.clear();
+                nativeVideoPacket(
+                  JSON.stringify({
+                    error: "Native video encoder stopped",
+                    streamId: state.streamId,
+                  }),
+                );
+                continue;
+              }
+              if (keyFrame) state.lastKeyTimestamp = frame.timestamp;
+              state.forceKey = false;
+            }
+          } finally {
+            if (encodingFrame && encodingFrame !== frame) encodingFrame.close();
+            frame.close();
+          }
+        }
+      } catch {
+        if (capture === current)
+          nativeVideoPacket(JSON.stringify({ error: "Native video capture stopped" }));
+      }
+    })();
+    return { width, height, settings: track.getSettings() };
+  } catch (error) {
+    if (stream) for (const track of stream.getTracks()) track.stop();
+    throw error;
+  }
+}
+/** Allocate a cohort selected by its stable quality/configuration key. Bitrate is bits per second,
+ * fps is the requested frame ceiling. Reserve capacity before asynchronous codec probes. */
+async function addEncoder(quality, streamId, bitrate, fps) {
+  if (!capture) throw new Error("Native capture is not running");
+  const bitrates = { low: 2000000, medium: 5000000, high: 12000000 };
+  bitrate ??= bitrates[quality];
+  fps ??= 30;
+  if (![2000000, 5000000, 12000000, 24000000].includes(bitrate) || ![15, 30, 60].includes(fps))
+    throw new Error("Unknown video settings");
+  const existing = encoders.get(quality);
+  if (existing) {
+    if (
+      existing.streamId !== streamId ||
+      existing.configuration.bitrate !== bitrate ||
+      existing.configuration.framerate !== fps
+    )
+      throw new Error("Encoder identity changed");
+    touchEncoder(quality);
+    return { codec: existing.codec };
+  }
+  const pending = pendingEncoders.get(quality);
+  if (pending) {
+    if (pending.streamId !== streamId || pending.bitrate !== bitrate || pending.fps !== fps)
+      throw new Error("Encoder allocation identity changed");
+    return pending.promise;
+  }
+  if (encoders.size + pendingEncoders.size >= 3) throw new Error("Native encoder limit reached");
+  // Reserve before any codec probe. A timed-out CDP request can continue in this
+  // page, so host-side serialization alone cannot enforce the encoder ceiling.
+  const source = capture;
+  const reservation = { streamId, bitrate, fps, promise: null };
+  pendingEncoders.set(quality, reservation);
+  const assertAllocation = () => {
+    if (capture !== source || source.stopped || pendingEncoders.get(quality) !== reservation)
+      throw new Error("Native encoder allocation changed");
+  };
+  reservation.promise = (async () => {
+    let state = null;
+    try {
+      let configuration;
+      for (const codec of ["avc1.420033", "vp8"]) {
+        const candidate = {
+          codec,
+          width: source.width,
+          height: source.height,
+          bitrate,
+          framerate: fps,
+          latencyMode: "realtime",
+          hardwareAcceleration: "no-preference",
+          ...(codec.startsWith("avc") ? { avc: { format: "annexb" } } : {}),
+        };
+        const support = await VideoEncoder.isConfigSupported(candidate);
+        assertAllocation();
+        if (support.supported) {
+          configuration = candidate;
+          break;
+        }
+      }
+      if (!configuration) throw new Error("Native encoder is unavailable");
+      state = {
+        streamId,
+        codec: configuration.codec,
+        sequence: 0,
+        pending: new Set(),
+        forceKey: true,
+        lastKeyTimestamp: -Infinity,
+        lastEncodedTimestampUs: -Infinity,
+        lastRequestedAt: performance.now(),
+        needsKey: true,
+        configuration,
+        frameGenerations: new Map(),
+        failed: false,
+        encoder: null,
+      };
+      state.encoder = new VideoEncoder({
+        output: (chunk, metadata) => {
+          if (!capture || encoders.get(quality) !== state || state.failed) return;
+          const generation = state.frameGenerations.get(chunk.timestamp);
+          state.frameGenerations.delete(chunk.timestamp);
+          if (chunk.byteLength > 2097152) {
+            state.failed = true;
+            try {
+              state.encoder.close();
+            } catch {}
+            nativeVideoPacket(
+              JSON.stringify({ error: "Native video quality exceeds its packet bound", streamId }),
+            );
+            return;
+          }
+          if (generation !== capture.generation || state.pending.size >= 2) {
+            state.forceKey = true;
+            state.needsKey = true;
+            return;
+          }
+          if (state.needsKey && chunk.type !== "key") return;
+          if (chunk.type === "key") state.needsKey = false;
+          const bytes = new Uint8Array(chunk.byteLength);
+          chunk.copyTo(bytes);
+          const sequence = ++state.sequence;
+          state.pending.add(sequence);
+          const description = metadata.decoderConfig && metadata.decoderConfig.description;
+          nativeVideoPacket(
+            JSON.stringify({
+              streamId,
+              captureGeneration: generation,
+              sequence,
+              timestampUs: chunk.timestamp,
+              type: chunk.type,
+              codec: state.codec,
+              width: capture.width,
+              height: capture.height,
+              ...(description ? { descriptionBase64: bytes64(new Uint8Array(description)) } : {}),
+              dataBase64: bytes64(bytes),
+            }),
+          );
+        },
+        error: () => {
+          state.failed = true;
+          nativeVideoPacket(JSON.stringify({ error: "Native video encoder stopped", streamId }));
+        },
+      });
+      state.encoder.configure(configuration);
+      assertAllocation();
+      pendingEncoders.delete(quality);
+      encoders.set(quality, state);
+      return { codec: state.codec };
+    } catch (error) {
+      try {
+        state?.encoder?.close();
+      } catch {}
+      throw error;
+    } finally {
+      if (pendingEncoders.get(quality) === reservation) pendingEncoders.delete(quality);
+    }
+  })();
+  return reservation.promise;
+}
+/** Cancel an uncertain allocation and release only the selected cohort. */
+function removeEncoder(quality) {
+  // Cancel uncertain pending allocation before its async support probe returns.
+  pendingEncoders.delete(quality);
+  const state = encoders.get(quality);
+  if (!state) return;
+  encoders.delete(quality);
+  try {
+    state.encoder.close();
+  } catch {}
+  state.pending.clear();
+  state.frameGenerations.clear();
+}
+/** Renew viewing demand without allocating or resetting a codec. */
+function touchEncoder(quality) {
+  const state = encoders.get(quality);
+  if (state) state.lastRequestedAt = performance.now();
+}
+/** Request the next eligible independent picture while preserving healthy in-flight deltas. */
+function requestKeyFrame(quality) {
+  const state = encoders.get(quality);
+  if (state) {
+    state.lastRequestedAt = performance.now();
+    // Joining/recovering viewers need an additional key, but healthy viewers
+    // can keep consuming an intact in-flight chain until that key is encoded.
+    // Preserve any existing needsKey from actual output loss or source reset.
+    state.forceKey = true;
+  }
+}
+/** Release producer pressure for this exact stream/sequence, including refused stale packets. */
+function acknowledge(streamId, sequence) {
+  for (const state of encoders.values())
+    if (state.streamId === streamId) state.pending.delete(sequence);
+}
+/** Fence pre-transition output using source-clock microseconds without replacing the track. */
+function resetCapture(generation, minimumTimestampUs) {
+  if (!capture) return;
+  if (generation < capture.generation) return;
+  capture.generation = generation;
+  capture.minimumTimestampUs = minimumTimestampUs;
+  for (const state of encoders.values()) {
+    if (state.failed) continue;
+    state.forceKey = true;
+    state.needsKey = true;
+    state.frameGenerations.clear();
+    state.pending.clear();
+    // reset cancels outstanding pre-navigation encoding, preserving the track.
+    state.encoder.reset();
+    state.encoder.configure(state.configuration);
+  }
+}
+`;

package/server/native-video-extension.test.ts

@@ -0,0 +1,41 @@
+import { mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { prepareNativeVideoExtension } from "./native-video-extension";
+import { NATIVE_VIDEO_EXTENSION_SOURCE } from "./native-video-extension-source";
+
+describe("immutable trusted native video helper", () => {
+  it("concurrent workspace starts publish complete files once without in-place truncation", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "owned-extension-"));
+    try {
+      const paths = await Promise.all(
+        Array.from({ length: 12 }, () => prepareNativeVideoExtension(directory)),
+      );
+      expect(new Set(paths).size).toBe(1);
+      const path = paths[0]!;
+      expect(await readFile(join(path, "recorder.js"), "utf8")).toBe(NATIVE_VIDEO_EXTENSION_SOURCE);
+      expect((await readdir(directory)).length).toBe(1);
+      const modified = (await stat(join(path, "recorder.js"))).mtimeMs;
+      await prepareNativeVideoExtension(directory);
+      expect((await stat(join(path, "recorder.js"))).mtimeMs).toBe(modified);
+      const manifest = JSON.parse(await readFile(join(path, "manifest.json"), "utf8"));
+      expect(manifest.permissions).toEqual(["tabCapture", "debugger"]);
+      expect(manifest.content_scripts).toBeUndefined();
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+  it("a failed publication does not poison future startup", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "owned-extension-retry-"));
+    const blocked = join(directory, "initially-file");
+    try {
+      await writeFile(blocked, "occupied");
+      await expect(prepareNativeVideoExtension(blocked)).rejects.toThrow();
+      await rm(blocked);
+      expect(await prepareNativeVideoExtension(blocked)).toContain("native-video-extension-");
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+});

package/server/native-video-extension.ts

@@ -0,0 +1,83 @@
+/** Materializes the trusted tab-capture helper inside this runtime's private IPC tree. */
+import { createHash } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { NATIVE_VIDEO_EXTENSION_SOURCE } from "./native-video-extension-source";
+
+const PUBLIC_EXTENSION_KEY =
+  "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs/JqirNVWTX8dJUeT8eyDXNNZS9jbMpw+IeqE6MHaM6+DPzMH/+QoM1VswHRZ/dRDWpqnKLtf5mhB7dWqWYXxAttlgbxolhVvj2M1DE9qfW+vEY9ag2vmn0d33nkhX5tHZcl4l1z9Gq9nrOaRjOsSm8FOfQIkCvFKwUgbE7rdgXUjwKjPf598zM5Pu36vT6IH4rP1dpnJpi+wVJzRKL1bRziP0hrrZulVNO97JOHumQ05VmS8jrmnKhwk/koFMSOHVvonuxXqnnPwdzNHfgQeCuYUcRNqgWxSnSwFfGqRwRjJ14H0l4nmFS3gvcMuabma9c3fTAX5EEU1CmzdW3MYQIDAQAB";
+export const NATIVE_VIDEO_EXTENSION_ID = [
+  ...createHash("sha256")
+    .update(Buffer.from(PUBLIC_EXTENSION_KEY, "base64"))
+    .digest()
+    .subarray(0, 16),
+]
+  .map((byte) => String.fromCharCode(97 + (byte >> 4), 97 + (byte & 15)))
+  .join("");
+const HELPER_HTML = '<!doctype html><meta charset="utf-8"><script src="recorder.js"></script>';
+const HELPER_MANIFEST = JSON.stringify({
+  manifest_version: 3,
+  name: "Shared Browser native capture",
+  version: "1.0.0",
+  key: PUBLIC_EXTENSION_KEY,
+  permissions: ["tabCapture", "debugger"],
+});
+const CONTENT_HASH = createHash("sha256")
+  .update(HELPER_MANIFEST)
+  .update(HELPER_HTML)
+  .update(NATIVE_VIDEO_EXTENSION_SOURCE)
+  .digest("hex");
+const preparations = new Map<string, Promise<string>>();
+
+/**
+ * Publish an immutable content-versioned directory atomically, safe for concurrent
+ * workspace startups sharing one IPC root. Failure is retryable, never cached.
+ * No web-accessible resources, messages, content scripts, or network permissions.
+ */
+export function prepareNativeVideoExtension(ipcDirectory: string): Promise<string> {
+  let preparation = preparations.get(ipcDirectory);
+  if (!preparation) {
+    preparation = materializeExtension(ipcDirectory);
+    preparations.set(ipcDirectory, preparation);
+    void preparation.catch(() => {
+      if (preparations.get(ipcDirectory) === preparation) preparations.delete(ipcDirectory);
+    });
+  }
+  return preparation;
+}
+
+async function materializeExtension(ipcDirectory: string): Promise<string> {
+  await mkdir(ipcDirectory, { recursive: true, mode: 0o700 });
+  const directory = join(ipcDirectory, `native-video-extension-${CONTENT_HASH.slice(0, 24)}`);
+  if (await isComplete(directory)) return directory;
+  const temporary = await mkdtemp(join(ipcDirectory, ".native-video-extension-"));
+  try {
+    await chmod(temporary, 0o700);
+    await Promise.all([
+      writeFile(join(temporary, "manifest.json"), HELPER_MANIFEST, { mode: 0o600 }),
+      writeFile(join(temporary, "recorder.html"), HELPER_HTML, { mode: 0o600 }),
+      writeFile(join(temporary, "recorder.js"), NATIVE_VIDEO_EXTENSION_SOURCE, { mode: 0o600 }),
+    ]);
+    await writeFile(join(temporary, "complete"), CONTENT_HASH, { mode: 0o600 });
+    try {
+      await rename(temporary, directory);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if ((code !== "EEXIST" && code !== "ENOTEMPTY") || !(await isComplete(directory)))
+        throw error;
+    }
+    return directory;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+/** The completion marker is published with the whole directory, never separately. */
+async function isComplete(directory: string): Promise<boolean> {
+  try {
+    return (await readFile(join(directory, "complete"), "utf8")) === CONTENT_HASH;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/server/native-video-packet.ts

@@ -0,0 +1,9 @@
+/** Private supervisor receipts share one Node monotonic clock domain. */
+import { z } from "zod";
+import { nativeVideoPacketSchema } from "../shared/browser-video";
+
+/** The native capture owns this timestamp; it is removed before public RPC output. */
+export const runtimeVideoPacketSchema = nativeVideoPacketSchema.extend({
+  capturedAtMonotonicMs: z.number().finite(),
+});
+export type RuntimeVideoPacket = z.infer<typeof runtimeVideoPacketSchema>;