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

package/client/browser-frame-buffer.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+import {
+  type BrowserFrameBuffer,
+  createBrowserFrameBuffer,
+  type FrameCandidate,
+} from "./browser-frame-buffer";
+
+function candidate(id: string, pixels = id, generation = 0): FrameCandidate {
+  return {
+    viewerToken: "viewer-a",
+    mutationEpoch: 0,
+    frame: {
+      sessionId: "session-a",
+      frameId: id,
+      mimeType: "image/jpeg",
+      transport: "screenshot",
+      dataBase64: pixels,
+      byteLength: pixels.length,
+      width: 1280,
+      height: 800,
+      navigationGeneration: generation,
+      viewportGeneration: 0,
+      runtimeId: "runtime-a",
+      capturedAt: "2026-10-02T12:00:00.000Z",
+    },
+  };
+}
+function pendingTicket(buffer: BrowserFrameBuffer): number {
+  const state = buffer.snapshot();
+  if (state.pending === null) throw new Error("No pending decoder");
+  return state.layers[state.pending]!.ticket;
+}
+function visible(buffer: BrowserFrameBuffer) {
+  const state = buffer.snapshot();
+  return state.front === null ? null : state.layers[state.front];
+}
+function decodeFirst(buffer: BrowserFrameBuffer) {
+  buffer.offer(candidate("front"));
+  buffer.settle(pendingTicket(buffer), true, () => true);
+}
+
+describe("decoded Shared Browser frame handoff", () => {
+  it("keeps initial capture hidden until successful decode, then retains it during replacement", () => {
+    const buffer = createBrowserFrameBuffer();
+    buffer.offer(candidate("front"));
+    expect(visible(buffer)).toBeNull();
+    buffer.settle(pendingTicket(buffer), true, () => true);
+    const original = visible(buffer);
+    buffer.offer(candidate("next"));
+    expect(visible(buffer)).toBe(original);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("front");
+    buffer.settle(pendingTicket(buffer), true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("next");
+  });
+
+  it("retains the decoded front and input frame after a failed replacement", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    const original = visible(buffer);
+    buffer.offer(candidate("failed"));
+    buffer.settle(pendingTicket(buffer), false, () => true);
+    expect(visible(buffer)).toBe(original);
+    expect(buffer.snapshot().imageError).toBe(false);
+    buffer.offer(candidate("retry"));
+    buffer.settle(pendingTicket(buffer), true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("retry");
+  });
+
+  it("shows the established initial error only when no decoded front exists", () => {
+    const buffer = createBrowserFrameBuffer();
+    buffer.offer(candidate("bad-first"));
+    buffer.settle(pendingTicket(buffer), false, () => true);
+    expect(buffer.snapshot().imageError).toBe(true);
+    expect(visible(buffer)).toBeNull();
+  });
+
+  it("advances identical-pixel frame authority without replacing its decoded source", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    const source = visible(buffer)?.source;
+    const ticket = visible(buffer)?.ticket;
+    buffer.offer(candidate("new-authority", "front", 1));
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("new-authority");
+    expect(visible(buffer)?.candidate.frame.navigationGeneration).toBe(1);
+    expect(visible(buffer)?.source).toBe(source);
+    expect(visible(buffer)?.ticket).toBe(ticket);
+    expect(buffer.snapshot().pending).toBeNull();
+  });
+
+  it("coalesces fast captures without cancelling the slow decoder or accumulating images", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    buffer.offer(candidate("slow"));
+    const ticket = pendingTicket(buffer);
+    for (let i = 0; i < 100; i++) buffer.offer(candidate(`queued-${i}`));
+    expect(pendingTicket(buffer)).toBe(ticket);
+    expect(buffer.snapshot().layers.filter(Boolean)).toHaveLength(2);
+    expect(buffer.snapshot().queued?.frame.frameId).toBe("queued-99");
+    buffer.settle(ticket, true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("slow");
+    buffer.settle(pendingTicket(buffer), true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("queued-99");
+  });
+
+  it("ignores late callbacks when the same native slot was reused for a newer generation", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    buffer.offer(candidate("obsolete"));
+    const oldTicket = pendingTicket(buffer);
+    buffer.invalidatePending();
+    buffer.offer(candidate("current", "current", 1));
+    const newTicket = pendingTicket(buffer);
+    buffer.settle(oldTicket, true, () => true);
+    buffer.settle(oldTicket, false, () => true);
+    expect(pendingTicket(buffer)).toBe(newTicket);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("front");
+    buffer.settle(newTicket, true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("current");
+  });
+
+  it("never promotes a decoded frame whose viewer/runtime/generation authority expired", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    buffer.offer(candidate("obsolete"));
+    buffer.offer({ ...candidate("fresh"), viewerToken: "viewer-b" });
+    const isCurrent = (item: FrameCandidate) => item.viewerToken === "viewer-b";
+    buffer.settle(pendingTicket(buffer), true, isCurrent);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("front");
+    buffer.settle(pendingTicket(buffer), true, isCurrent);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("fresh");
+  });
+
+  it("clears workspace pixels and prevents ticket replay after reset", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    buffer.offer(candidate("old-workspace"));
+    const oldTicket = pendingTicket(buffer);
+    buffer.reset();
+    expect(visible(buffer)).toBeNull();
+    buffer.offer(candidate("new-workspace"));
+    const fresh = buffer.snapshot();
+    buffer.settle(oldTicket, true, () => true);
+    expect(buffer.snapshot()).toBe(fresh);
+    buffer.settle(pendingTicket(buffer), true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("new-workspace");
+  });
+
+  it("a freshest capture identical to the front cancels obsolete pending promotion", () => {
+    const buffer = createBrowserFrameBuffer();
+    decodeFirst(buffer);
+    buffer.offer(candidate("transient"));
+    const oldTicket = pendingTicket(buffer);
+    buffer.offer(candidate("back-to-front", "front"));
+    buffer.settle(oldTicket, true, () => true);
+    expect(visible(buffer)?.candidate.frame.frameId).toBe("back-to-front");
+  });
+});

package/client/browser-frame-buffer.ts

@@ -0,0 +1,148 @@
+/**
+ * Owns decoded browser-frame handoff independently of transport capture cadence.
+ * Two stable image slots retain the decoded front while one replacement loads;
+ * one newest queued capture bounds memory without starving a slow decoder.
+ * Frame IDs are opaque. A decode ticket, not capture timestamps, rejects late
+ * native callbacks. Callers qualify session/generation ownership separately.
+ */
+import type { BrowserFrame } from "../shared/browser";
+
+export type FrameCandidate = {
+  frame: BrowserFrame;
+  /** Canonical CSS layout captured with these pixels, independent of capture density. */
+  viewport?: { width: number; height: number };
+  viewerToken: string;
+  mutationEpoch: number;
+  /** Held-video handoff request captured when this image RPC began. */
+  fallbackRevision?: number;
+};
+export type FrameLayer = {
+  ticket: number;
+  candidate: FrameCandidate;
+  source: { uri: string };
+};
+export type FrameBufferSnapshot = {
+  layers: readonly [FrameLayer | null, FrameLayer | null];
+  front: 0 | 1 | null;
+  pending: 0 | 1 | null;
+  queued: FrameCandidate | null;
+  imageError: boolean;
+};
+
+/** Exact JPEG reuse avoids reloading an already decoded image for a fresh frame ID. */
+function samePixels(a: BrowserFrame, b: BrowserFrame): boolean {
+  return (
+    a.mimeType === b.mimeType &&
+    a.width === b.width &&
+    a.height === b.height &&
+    a.dataBase64 === b.dataBase64
+  );
+}
+
+/**
+ * Create a bounded handoff model. Use plain closures rather than a class because
+ * the client is evaluated dynamically across Paseo hosts, outside Metro's normal
+ * class lowering. Visible input authority is published only after React commits.
+ */
+export function createBrowserFrameBuffer() {
+  let nextTicket = 0;
+  let value: FrameBufferSnapshot = {
+    layers: [null, null],
+    front: null,
+    pending: null,
+    queued: null,
+    imageError: false,
+  };
+
+  function snapshot(): FrameBufferSnapshot {
+    return value;
+  }
+
+  /** Replace an obsolete pending decode without discarding the last decoded front. */
+  function invalidatePending(): FrameBufferSnapshot {
+    const layers: [FrameLayer | null, FrameLayer | null] = [...value.layers];
+    if (value.pending !== null) {
+      layers[value.pending] = null;
+    }
+    value = { ...value, layers, pending: null, queued: null };
+    return value;
+  }
+
+  /** Clear workspace-owned pixels. Ticket numbers never reset, including across workspaces. */
+  function reset(): FrameBufferSnapshot {
+    value = {
+      layers: [null, null],
+      front: null,
+      pending: null,
+      queued: null,
+      imageError: false,
+    };
+    return value;
+  }
+
+  /** Offer a qualified capture; newest queued metadata replaces earlier queued captures. */
+  function offer(candidate: FrameCandidate): FrameBufferSnapshot {
+    const front = value.front;
+    const frontLayer = front === null ? null : value.layers[front];
+    if (front !== null && frontLayer && samePixels(frontLayer.candidate.frame, candidate.frame)) {
+      invalidatePending();
+      const layers: [FrameLayer | null, FrameLayer | null] = [...value.layers];
+      layers[front] = { ...frontLayer, candidate };
+      value = { ...value, layers, imageError: false };
+      return value;
+    }
+
+    if (value.pending !== null) {
+      value = { ...value, queued: candidate };
+      return value;
+    }
+
+    const slot = front === 0 ? 1 : 0;
+    const layers: [FrameLayer | null, FrameLayer | null] = [...value.layers];
+    layers[slot] = {
+      ticket: ++nextTicket,
+      candidate,
+      source: { uri: `data:${candidate.frame.mimeType};base64,${candidate.frame.dataBase64}` },
+    };
+    value = { ...value, layers, pending: slot, queued: null, imageError: false };
+    return value;
+  }
+
+  /**
+   * Accept only this pending image's successful load. Failure or expired authority
+   * never removes the front. Only a still-qualified newest queued capture is loaded.
+   */
+  function settle(
+    ticket: number,
+    succeeded: boolean,
+    isCurrent: (candidate: FrameCandidate) => boolean,
+  ): FrameBufferSnapshot {
+    const pending = value.pending;
+    const layer = pending === null ? null : value.layers[pending];
+    if (pending === null || !layer || layer.ticket !== ticket) {
+      return value;
+    }
+
+    const queued = value.queued;
+    const accepted = succeeded && isCurrent(layer.candidate);
+    const layers: [FrameLayer | null, FrameLayer | null] = [...value.layers];
+    if (!accepted) {
+      layers[pending] = null;
+    }
+    value = {
+      ...value,
+      layers,
+      front: accepted ? pending : value.front,
+      pending: null,
+      queued: null,
+      imageError: !succeeded && value.front === null && isCurrent(layer.candidate),
+    };
+    if (queued && isCurrent(queued)) {
+      offer(queued);
+    }
+    return value;
+  }
+  return { snapshot, invalidatePending, reset, offer, settle };
+}
+
+export type BrowserFrameBuffer = ReturnType<typeof createBrowserFrameBuffer>;

package/client/browser-frame-image.tsx

@@ -0,0 +1,62 @@
+/**
+ * Owns one visual JPEG/decode slot. Input authority belongs to the frame-buffer
+ * hook, not this image. Metadata-only captures and mouse state must not rerender
+ * the native image or recreate its load callbacks when its pixels are unchanged.
+ */
+import { memo, useCallback, useMemo } from "react";
+import { Image, StyleSheet } from "react-native";
+import { createBrowserImageLoadHandler } from "./browser-image-load";
+
+interface BrowserFrameImageProps {
+  ticket: number;
+  source: { uri: string };
+  visible: boolean;
+  label: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  cornerRadius: number;
+  settled(ticket: number, succeeded: boolean): boolean;
+  retry(): void;
+}
+
+const styles = StyleSheet.create({ frame: { position: "absolute" } });
+
+/** Memoize visual values only; newer input frame IDs still commit through the parent hook. */
+export const BrowserFrameImage = memo(function BrowserFrameImage(props: BrowserFrameImageProps) {
+  const { ticket, source, settled, retry } = props;
+  const onLoad = useMemo(
+    () => createBrowserImageLoadHandler(ticket, source.uri, settled),
+    [ticket, source.uri, settled],
+  );
+  const onError = useCallback(() => {
+    if (settled(ticket, false)) {
+      retry();
+    }
+  }, [ticket, settled, retry]);
+
+  return (
+    <Image
+      accessible={props.visible}
+      accessibilityLabel={props.label}
+      accessibilityRole="image"
+      fadeDuration={0}
+      onLoad={onLoad}
+      onError={onError}
+      resizeMode="contain"
+      source={source}
+      style={[
+        styles.frame,
+        {
+          left: props.x,
+          top: props.y,
+          width: props.width,
+          height: props.height,
+          borderRadius: props.cornerRadius,
+          opacity: props.visible ? 1 : 0,
+        },
+      ]}
+    />
+  );
+});

package/client/browser-image-load.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { createBrowserImageLoadHandler } from "./browser-image-load";
+
+describe("cross-platform browser image decode", () => {
+  it("accepts the desktop DOM load envelope without inventing a reported URI", () => {
+    const delivered: unknown[] = [];
+    const handler = createBrowserImageLoadHandler(1, "data:image/jpeg;base64,frame", (...args) =>
+      delivered.push(args),
+    );
+    expect(() => handler({ nativeEvent: new Event("load") })).not.toThrow();
+    expect(delivered).toEqual([[1, true]]);
+  });
+
+  it("accepts the native exact source and refuses a contradictory source", () => {
+    const delivered: unknown[] = [];
+    const handler = createBrowserImageLoadHandler(7, "expected", (...args) => delivered.push(args));
+    handler({ nativeEvent: { source: { uri: "other" } } });
+    handler({ nativeEvent: { source: { uri: 42 } } });
+    expect(delivered).toEqual([]);
+    handler({ nativeEvent: { source: { uri: "expected" } } });
+    expect(delivered).toEqual([[7, true]]);
+  });
+});

package/client/browser-image-load.ts

@@ -0,0 +1,26 @@
+/** Qualify native and web image-load events before the current decode-ticket handoff. */
+
+/**
+ * Native Image may report its loaded source URI; React Native Web instead wraps
+ * a DOM load Event without that field. The unique decoder ticket remains the
+ * authority when no URI is reported. A contradictory reported URI is rejected.
+ * The settlement callback must still check current viewer, mutation and browser
+ * generations before committing pixels or input authority.
+ */
+export function createBrowserImageLoadHandler(
+  ticket: number,
+  expectedUri: string,
+  settle: (ticket: number, succeeded: boolean) => unknown,
+): (event: unknown) => void {
+  return (event) => {
+    const nativeEvent =
+      event && typeof event === "object" && "nativeEvent" in event ? event.nativeEvent : undefined;
+    const source =
+      nativeEvent && typeof nativeEvent === "object" && "source" in nativeEvent
+        ? nativeEvent.source
+        : undefined;
+    const uri = source && typeof source === "object" && "uri" in source ? source.uri : undefined;
+    if (uri && uri !== expectedUri) return;
+    settle(ticket, true);
+  };
+}