@omercnet/paseo-shared-browser 1.2.2-next.232.1 → 1.2.2-next.237.1

package/client/browser-video-decoder.ts

@@ -0,0 +1,311 @@
+/**
+ * Owns bounded video decode/presentation and correlates each rendered source
+ * timestamp with its server-issued input authority. The web adapter supplies
+ * codecs and drawing; this module has no DOM globals and remains Hermes-safe.
+ */
+import type { BrowserVideoPacket } from "../shared/browser-video";
+
+export interface DecodedBrowserVideoFrame {
+  readonly timestamp: number;
+  readonly displayWidth: number;
+  readonly displayHeight: number;
+  close(): void;
+}
+export interface BrowserVideoCodec {
+  readonly decodeQueueSize: number;
+  configure(config: {
+    codec: string;
+    codedWidth: number;
+    codedHeight: number;
+    description?: Uint8Array;
+    optimizeForLatency: boolean;
+  }): void;
+  decode(chunk: unknown): void;
+  close(): void;
+}
+export interface BrowserVideoDecodeEnvironment {
+  createDecoder(callbacks: {
+    output(frame: DecodedBrowserVideoFrame): void;
+    error(error: unknown): void;
+    /** Native queue capacity can free without producing a frame. */
+    dequeue(): void;
+  }): BrowserVideoCodec;
+  /** Native bridges already carry base64; avoid decoding and re-encoding each packet in Hermes. */
+  createEncodedChunk?(input: {
+    type: "key" | "delta";
+    timestamp: number;
+    dataBase64: string;
+  }): unknown;
+  createChunk(input: { type: "key" | "delta"; timestamp: number; data: Uint8Array }): unknown;
+  decodeBase64(data: string): Uint8Array;
+  /** Schedule a draw on the next local paint; return an idempotent cancellation. */
+  scheduleDraw(draw: () => void): () => void;
+  draw(frame: DecodedBrowserVideoFrame): void | Promise<void>;
+}
+export interface BrowserVideoDecoderOptions {
+  environment: BrowserVideoDecodeEnvironment;
+  isCurrent(packet: BrowserVideoPacket, mutationEpoch: number): boolean;
+  /** Optional exact current source/document/geometry check, independent of a
+   * local press epoch. Allows continuous visual decode without granting input. */
+  isSourceCurrent?(packet: BrowserVideoPacket): boolean;
+  /** Carries the original read epoch; caller separately admits input authority. */
+  onPresented(packet: BrowserVideoPacket, mutationEpoch: number): void;
+  onNeedKeyFrame(): void;
+  onError(error: unknown): void;
+}
+
+const MAX_PENDING_FRAMES = 64;
+const MAX_DECODE_QUEUE = 4;
+const MAX_BUFFERED_BASE64_CHARACTERS = 8 * 1024 * 1024;
+
+/** Decode a bounded continuous source chain. A caller opting into source-only
+ * visuals must keep the original epoch when separately admitting input. */
+export function createBrowserVideoDecoder(options: BrowserVideoDecoderOptions) {
+  const { environment } = options;
+  const canPresent = (packet: BrowserVideoPacket, epoch: number) =>
+    options.isSourceCurrent ? options.isSourceCurrent(packet) : options.isCurrent(packet, epoch);
+  let closed = false;
+  let codec: BrowserVideoCodec | null = null;
+  let decoderGeneration = 0;
+  let streamKey: string | null = null;
+  let sequence = 0;
+  let lastPresentedTimestamp = -1;
+  let scheduled: (() => void) | null = null;
+  let painting = false;
+  let paint: { frame: DecodedBrowserVideoFrame; packet: BrowserVideoPacket; epoch: number } | null =
+    null;
+  const pending = new Map<number, { packet: BrowserVideoPacket; epoch: number }>();
+  const queued: { packet: BrowserVideoPacket; epoch: number }[] = [];
+  let bufferedCharacters = 0;
+  let draining = false;
+
+  const reset = () => {
+    decoderGeneration += 1;
+    scheduled?.();
+    scheduled = null;
+    paint?.frame.close();
+    paint = null;
+    pending.clear();
+    queued.length = 0;
+    bufferedCharacters = 0;
+    try {
+      codec?.close();
+    } catch {
+      /* Closing an errored decoder is best-effort. */
+    }
+    codec = null;
+    streamKey = null;
+    sequence = 0;
+    lastPresentedTimestamp = -1;
+  };
+
+  const fail = (error: unknown) => {
+    if (closed) return;
+    reset();
+    options.onError(error);
+  };
+
+  /** Preserve the dependency chain while the native decoder is busy. Both actual
+   * output and dequeue wake this bounded FIFO; no timer or repeated key reset is
+   * needed merely because a relay delivered a normal packet batch at once. */
+  const drain = () => {
+    if (draining || closed) return;
+    draining = true;
+    try {
+      while (codec && codec.decodeQueueSize < MAX_DECODE_QUEUE && queued.length) {
+        const entry = queued.shift()!;
+        if (!canPresent(entry.packet, entry.epoch)) {
+          reset();
+          options.onNeedKeyFrame();
+          return;
+        }
+        pending.set(entry.packet.timestampUs, entry);
+        let chunk: unknown;
+        if (environment.createEncodedChunk) {
+          chunk = environment.createEncodedChunk({
+            type: entry.packet.type,
+            timestamp: entry.packet.timestampUs,
+            dataBase64: entry.packet.dataBase64,
+          });
+        } else {
+          chunk = environment.createChunk({
+            type: entry.packet.type,
+            timestamp: entry.packet.timestampUs,
+            data: environment.decodeBase64(entry.packet.dataBase64),
+          });
+        }
+        codec.decode(chunk);
+      }
+    } catch (error) {
+      fail(error);
+    } finally {
+      draining = false;
+    }
+  };
+
+  const output = (frame: DecodedBrowserVideoFrame, generation: number) => {
+    if (generation !== decoderGeneration) {
+      frame.close();
+      return;
+    }
+    const entry = pending.get(frame.timestamp);
+    pending.delete(frame.timestamp);
+    if (entry) bufferedCharacters -= entry.packet.dataBase64.length;
+    drain();
+    if (
+      closed ||
+      generation !== decoderGeneration ||
+      !entry ||
+      !canPresent(entry.packet, entry.epoch) ||
+      frame.timestamp <= lastPresentedTimestamp
+    ) {
+      frame.close();
+      return;
+    }
+    if (frame.displayWidth !== entry.packet.width || frame.displayHeight !== entry.packet.height) {
+      frame.close();
+      fail(new Error("Decoded video dimensions do not match the current browser view."));
+      return;
+    }
+    if (paint && frame.timestamp <= paint.frame.timestamp) {
+      frame.close();
+      return;
+    }
+    // Keep only the newest decoded frame while the local compositor is delayed.
+    paint?.frame.close();
+    paint = { frame, packet: entry.packet, epoch: entry.epoch };
+    schedulePaint();
+  };
+
+  /** Native paint crosses an asynchronous bridge. Serialize presentations so a
+   * newer frame cannot replace the pixels while an older receipt is admitted. */
+  const schedulePaint = () => {
+    if (scheduled || painting || !paint || closed) return;
+    const generation = decoderGeneration;
+    scheduled = environment.scheduleDraw(() => {
+      scheduled = null;
+      const selected = paint;
+      paint = null;
+      if (!selected) return;
+      const complete = () => {
+        if (
+          !closed &&
+          generation === decoderGeneration &&
+          canPresent(selected.packet, selected.epoch)
+        ) {
+          lastPresentedTimestamp = selected.frame.timestamp;
+          options.onPresented(selected.packet, selected.epoch);
+        }
+      };
+      const release = () => {
+        selected.frame.close();
+        painting = false;
+        schedulePaint();
+      };
+      try {
+        if (
+          closed ||
+          generation !== decoderGeneration ||
+          !canPresent(selected.packet, selected.epoch)
+        ) {
+          release();
+          return;
+        }
+        const result = environment.draw(selected.frame);
+        if (!result) {
+          complete();
+          release();
+          return;
+        }
+        painting = true;
+        void (async () => {
+          try {
+            await result;
+            complete();
+          } catch (error) {
+            if (!closed && generation === decoderGeneration) fail(error);
+          } finally {
+            release();
+          }
+        })();
+      } catch (error) {
+        if (generation === decoderGeneration) fail(error);
+        release();
+      }
+    });
+  };
+
+  return {
+    /** Returns false when a new keyframe is needed; never feeds a decoder an unknown delta chain. */
+    receive(packet: BrowserVideoPacket, mutationEpoch: number): boolean {
+      if (closed || !canPresent(packet, mutationEpoch)) return false;
+      const identity = JSON.stringify([
+        packet.streamId,
+        packet.captureGeneration,
+        packet.codec,
+        packet.width,
+        packet.height,
+        packet.frame.sessionId,
+        packet.frame.runtimeId,
+        packet.frame.captureEpoch,
+        packet.frame.navigationGeneration,
+        packet.frame.viewportGeneration,
+      ]);
+      if (streamKey !== identity) reset();
+      if (codec && packet.sequence <= sequence) return true;
+      // A complete new key can replace unsubmitted old pictures under decode
+      // pressure. Preserve the visible canvas and original receipt/epoch checks;
+      // a delta can never perform this catch-up because it needs its old chain.
+      if (codec && packet.type === "key" && queued.length > 0) reset();
+      if (
+        (codec && packet.sequence !== sequence + 1) ||
+        pending.size + queued.length >= MAX_PENDING_FRAMES ||
+        bufferedCharacters + packet.dataBase64.length > MAX_BUFFERED_BASE64_CHARACTERS
+      ) {
+        reset();
+      }
+      if (!codec && packet.type !== "key") {
+        options.onNeedKeyFrame();
+        return false;
+      }
+      try {
+        if (!codec) {
+          const generation = decoderGeneration;
+          codec = environment.createDecoder({
+            output: (frame) => output(frame, generation),
+            error: (error) => {
+              if (generation === decoderGeneration) fail(error);
+            },
+            dequeue: () => {
+              if (generation === decoderGeneration) drain();
+            },
+          });
+          codec.configure({
+            codec: packet.codec,
+            codedWidth: packet.width,
+            codedHeight: packet.height,
+            ...(packet.descriptionBase64
+              ? { description: environment.decodeBase64(packet.descriptionBase64) }
+              : {}),
+            optimizeForLatency: true,
+          });
+          streamKey = identity;
+        }
+        sequence = packet.sequence;
+        bufferedCharacters += packet.dataBase64.length;
+        queued.push({ packet, epoch: mutationEpoch });
+        drain();
+        return codec !== null;
+      } catch (error) {
+        fail(error);
+        return false;
+      }
+    },
+    reset,
+    close() {
+      if (closed) return;
+      closed = true;
+      reset();
+    },
+  };
+}

package/client/browser-video-surface.tsx

@@ -0,0 +1,21 @@
+/** Web renderer boundary. Other clients keep the JPEG path; the host SDK this plugin
+ * is pinned to publishes no encoded-video surface. */
+import { useEffect } from "react";
+import { type StyleProp, View, type ViewStyle } from "react-native";
+import * as Web from "./web";
+
+export type BrowserVideoCanvasNode = Web.BrowserVideoCanvasNode;
+export const supportsBrowserVideo = Web.supportsBrowserVideo;
+export const bindBrowserVideoVisibility = Web.bindBrowserVideoVisibility;
+export const createBrowserVideoEnvironment = Web.createBrowserVideoEnvironment;
+
+interface SurfaceProps {
+  canvasRef(value: unknown): void;
+  style: StyleProp<ViewStyle>;
+}
+
+/** Pointer handling stays on the sibling touch overlay, never inside the canvas host. */
+export function BrowserVideoSurface({ canvasRef, style }: SurfaceProps) {
+  useEffect(() => () => canvasRef(null), [canvasRef]);
+  return <View ref={canvasRef} style={style} pointerEvents="none" accessible={false} />;
+}

package/client/browser-video-visibility.test.ts

@@ -0,0 +1,45 @@
+/** Real EventTarget envelopes exercise host suspension without a decoder or DOM shim. */
+import { expect, it, vi } from "vitest";
+
+vi.mock("react-native", () => ({ Platform: { OS: "web" } }));
+
+import { type BrowserVideoCanvasNode, bindBrowserVideoVisibility } from "./web";
+
+it("tracks hidden documents and page-cache suspension and removes every listener", () => {
+  const document = Object.assign(new EventTarget(), { hidden: false });
+  let intersection: ((entries: { isIntersecting: boolean }[]) => void) | null = null;
+  const disconnected = vi.fn();
+  const view = Object.assign(new EventTarget(), {
+    IntersectionObserver: class {
+      constructor(callback: (entries: { isIntersecting: boolean }[]) => void) {
+        intersection = callback;
+      }
+      observe() {}
+      disconnect = disconnected;
+    },
+  });
+  const changes: boolean[] = [];
+  const cleanup = bindBrowserVideoVisibility(
+    {
+      getClientRects: () => [1],
+      ownerDocument: Object.assign(document, { defaultView: view }),
+    } as unknown as BrowserVideoCanvasNode,
+    (value) => changes.push(value),
+  );
+  document.hidden = true;
+  document.dispatchEvent(new Event("visibilitychange"));
+  document.hidden = false;
+  view.dispatchEvent(new Event("pagehide"));
+  document.dispatchEvent(new Event("visibilitychange"));
+  view.dispatchEvent(new Event("pageshow"));
+  expect(changes).toEqual([true, false, false, false, true]);
+  intersection!([{ isIntersecting: false }]);
+  intersection!([{ isIntersecting: true }]);
+  expect(changes.slice(-2)).toEqual([false, true]);
+  cleanup();
+  document.hidden = true;
+  document.dispatchEvent(new Event("visibilitychange"));
+  view.dispatchEvent(new Event("pageshow"));
+  expect(changes).toHaveLength(7);
+  expect(disconnected).toHaveBeenCalledOnce();
+});

package/client/browser-viewer-recovery.test.ts

@@ -0,0 +1,111 @@
+import { QueryClient, QueryObserver } from "@tanstack/react-query";
+import { describe, expect, it } from "vitest";
+import {
+  createBrowserViewerRecovery,
+  isBrowserClosedError,
+  isExpiredBrowserViewerError,
+} from "./browser-viewer-recovery";
+
+const expired = Object.assign(
+  new Error(
+    "Request failed: Viewer token is invalid or expired requestType=plugin.rpc.invoke.request code=handler_error",
+  ),
+  { code: "handler_error" },
+);
+const observation = {
+  identity: "host-a/workspace-a",
+  viewerToken: "old-viewer",
+  failedViewerToken: "old-viewer",
+  captureError: expired,
+  pending: false,
+};
+
+describe("expired browser viewing recovery", () => {
+  it("recognizes explicit closure without treating it as an expired viewer", () => {
+    const closed = Object.assign(
+      new Error(
+        "Request failed: Browser is closed requestType=plugin.rpc.invoke.request code=handler_error",
+      ),
+      { code: "handler_error" },
+    );
+    expect(isBrowserClosedError(closed)).toBe(true);
+    expect(isExpiredBrowserViewerError(closed)).toBe(false);
+    expect(isBrowserClosedError(expired)).toBe(false);
+  });
+  it("matches the actual SDK handler-error suffix but not transport, control or arbitrary failures", () => {
+    expect(isExpiredBrowserViewerError(expired)).toBe(true);
+    expect(
+      isExpiredBrowserViewerError(
+        Object.assign(new Error("Request failed: Viewer token is invalid or expired"), {
+          code: "handler_error",
+        }),
+      ),
+    ).toBe(true);
+    expect(isExpiredBrowserViewerError(new Error("Viewer token is invalid or expired"))).toBe(true);
+    for (const error of [
+      new Error("Control lease is invalid or expired"),
+      new Error("Browser frame is stale"),
+      new Error("Bridge disconnected"),
+      Object.assign(new Error("Viewer token is invalid or expired"), { code: "unknown_outcome" }),
+      Object.assign(new Error("Viewer token is invalid or expired"), { code: "rpc_timeout" }),
+      { code: "handler_error", message: "Other error: Viewer token is invalid or expired" },
+    ])
+      expect(isExpiredBrowserViewerError(error)).toBe(false);
+  });
+
+  it("reattaches once for each expired token and leaves failures for explicit reconnect", () => {
+    const claim = createBrowserViewerRecovery();
+    expect(claim({ ...observation, pending: true })).toBe(false);
+    expect(claim(observation)).toBe(true);
+    expect(claim(observation)).toBe(false);
+    expect(claim({ ...observation, pending: true })).toBe(false);
+    expect(claim({ ...observation, viewerToken: "new", failedViewerToken: "new" })).toBe(true);
+  });
+
+  it("ignores obsolete token errors, missing attachments and unrelated current capture errors", () => {
+    const claim = createBrowserViewerRecovery();
+    expect(claim({ ...observation, viewerToken: "replacement" })).toBe(false);
+    expect(claim({ ...observation, viewerToken: null })).toBe(false);
+    expect(claim({ ...observation, captureError: new Error("Timeout") })).toBe(false);
+    expect(claim(observation)).toBe(true);
+  });
+
+  it("permits a distinct scope's attachment while retaining per-token loop protection", () => {
+    const claim = createBrowserViewerRecovery();
+    expect(claim(observation)).toBe(true);
+    expect(claim(observation)).toBe(false);
+    expect(claim({ ...observation, identity: "host-b/workspace-a" })).toBe(true);
+    expect(claim({ ...observation, identity: "host-b/workspace-a" })).toBe(false);
+  });
+});
+
+it("the actual capture query observer discards old token errors when its token key changes", async () => {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 } } });
+  const replacement = Promise.withResolvers<string>();
+  const observer = new QueryObserver(client, {
+    queryKey: ["shared-browser", "capture", "old-viewer"],
+    queryFn: async (): Promise<string> => {
+      throw expired;
+    },
+  });
+  const unsubscribe = observer.subscribe(() => {});
+  try {
+    await observer.refetch();
+    expect(observer.getCurrentResult().error).toBe(expired);
+    observer.setOptions({
+      queryKey: ["shared-browser", "capture", "new-viewer"],
+      queryFn: () => replacement.promise,
+      retry: false,
+    });
+    expect(observer.getCurrentResult().error).toBeNull();
+    expect(observer.getCurrentResult().status).toBe("pending");
+    replacement.resolve("fresh capture");
+    await observer.refetch({ cancelRefetch: false });
+    expect(observer.getCurrentResult().error).toBeNull();
+    expect(observer.getCurrentResult().data).toBe("fresh capture");
+  } finally {
+    replacement.resolve("cleanup");
+    unsubscribe();
+    client.clear();
+  }
+});

package/client/browser-viewer-recovery.ts

@@ -0,0 +1,78 @@
+/**
+ * Recover viewing after its short-lived viewer token expires during background
+ * suspension. Only a viewing capture/video error can use this policy; mutation failure must
+ * never trigger action replay, control acquisition or lease takeover.
+ */
+const VIEWER_EXPIRED_MESSAGE = "Viewer token is invalid or expired";
+const BROWSER_CLOSED_MESSAGE = "Browser is closed";
+
+/** Recognize the server's explicit close fence without confusing it with a transport failure. */
+export function isBrowserClosedError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const value = error as { message?: unknown; code?: unknown };
+  if (typeof value.message !== "string") return false;
+  if (value.code !== undefined && value.code !== "handler_error") return false;
+  const message = value.message.startsWith("Request failed: ")
+    ? value.message.slice("Request failed: ".length)
+    : value.message;
+  return (
+    message === BROWSER_CLOSED_MESSAGE ||
+    (value.code === "handler_error" && message.startsWith(`${BROWSER_CLOSED_MESSAGE} requestType=`))
+  );
+}
+
+/** Match the owned handler error, including Paseo's documented RPC error suffix. */
+export function isExpiredBrowserViewerError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const value = error as { message?: unknown; code?: unknown };
+  if (typeof value.message !== "string") return false;
+  if (value.code !== undefined && value.code !== "handler_error") return false;
+  // Daemon session.js applies this exact prefix before the client appends
+  // requestType/code. Arbitrary error text never grants automatic recovery.
+  const message =
+    value.code === "handler_error" && value.message.startsWith("Request failed: ")
+      ? value.message.slice("Request failed: ".length)
+      : value.message;
+  if (message === VIEWER_EXPIRED_MESSAGE) return true;
+  return (
+    value.code === "handler_error" && message.startsWith(`${VIEWER_EXPIRED_MESSAGE} requestType=`)
+  );
+}
+
+export interface BrowserViewerRecoveryObservation {
+  /** Host/workspace scope of the mounted panel, never a printer or page identity. */
+  identity: string;
+  viewerToken: string | null;
+  /** Exact token of the failed capture query or video reader; an old viewer cannot recover its replacement. */
+  failedViewerToken: string | null;
+  captureError: unknown;
+  pending: boolean;
+}
+
+/**
+ * Claim at most one automatic viewing reattachment per expired token. Failure
+ * keeps manual Reconnect available. A new token or panel scope permits its own
+ * later recovery; this helper neither issues input nor holds browser authority.
+ */
+export function createBrowserViewerRecovery() {
+  let scope: string | null = null;
+  let attemptedToken: string | null = null;
+  return (observation: BrowserViewerRecoveryObservation): boolean => {
+    if (scope !== observation.identity) {
+      scope = observation.identity;
+      attemptedToken = null;
+    }
+    const token = observation.viewerToken;
+    if (
+      observation.pending ||
+      !token ||
+      observation.failedViewerToken !== token ||
+      attemptedToken === token ||
+      !isExpiredBrowserViewerError(observation.captureError)
+    ) {
+      return false;
+    }
+    attemptedToken = token;
+    return true;
+  };
+}