@omercnet/paseo-shared-browser 1.1.0-next.210.1 → 1.1.0-next.213.1

package/client/browser.tsx

@@ -45,6 +45,7 @@ import {
   sendBrowserInputRpc,
   toViewportPoint,
 } from "../shared/browser";
+import { FrameLifecycle } from "./frame-lifecycle";
 
 const SPACE = {
   xxs: 2,
@@ -989,14 +990,15 @@ export function SharedBrowserPanel({
   const mountedRef = useRef(false);
   const activeViewerTokenRef = useRef<string | null>(null);
   const stateRef = useRef<BrowserState | null>(null);
-  const frameRef = useRef<BrowserFrame | null>(null);
+  const lifecycleRef = useRef(new FrameLifecycle());
+  const lifecycle = lifecycleRef.current;
   const lastPointRef = useRef<{ x: number; y: number } | null>(null);
   const dragStartRef = useRef<{ x: number; y: number } | null>(null);
-  const mutationEpochRef = useRef(0);
   const captureInFlightRef = useRef(false);
 
   const [state, setState] = useState<BrowserState | null>(null);
   const [frame, setFrame] = useState<BrowserFrame | null>(null);
+  const [inputBusy, setInputBusy] = useState(false);
   const [controlToken, setControlToken] = useState<string | null>(null);
   const [operationError, setOperationError] = useState<string | null>(null);
   const [imageError, setImageError] = useState(false);
@@ -1024,7 +1026,7 @@ export function SharedBrowserPanel({
   const acceptState = useCallback((next: BrowserState) => {
     const previous = stateRef.current;
     if (previous && !isBrowserStateCurrent(previous, next)) return false;
-    const currentFrame = frameRef.current;
+    const currentFrame = lifecycle.frame;
     if (previous && didBrowserRuntimeRestart(previous, next)) {
       setRuntimeNotice(
         "Browser restarted. The preserved viewer connection now targets the new runtime.",
@@ -1032,7 +1034,7 @@ export function SharedBrowserPanel({
       setControlToken(null);
     }
     if (currentFrame && !isFrameCurrent(currentFrame, next)) {
-      frameRef.current = null;
+      lifecycle.drop();
       setFrame(null);
       lastPointRef.current = null;
     }
@@ -1074,9 +1076,10 @@ export function SharedBrowserPanel({
 
   useEffect(() => {
     stateRef.current = null;
-    frameRef.current = null;
+    lifecycle.reset();
     setState(null);
     setFrame(null);
+    setInputBusy(false);
     setControlToken(null);
     setOperationError(null);
     setRuntimeNotice(null);
@@ -1086,8 +1089,8 @@ export function SharedBrowserPanel({
     queryKey: ["shared-browser", "capture", viewerToken],
     queryFn: async () => {
       if (!viewerToken) throw new Error("The browser viewer is not attached.");
-      const mutationEpoch = mutationEpochRef.current;
-      const knownFrame = frameRef.current;
+      const mutationEpoch = lifecycle.epoch;
+      const knownFrame = lifecycle.frame;
       captureInFlightRef.current = true;
       try {
         const result = await captureBrowser({
@@ -1113,17 +1116,14 @@ export function SharedBrowserPanel({
 
   useEffect(() => {
     const result = captureQuery.data;
-    if (
-      !result ||
-      result.mutationEpoch !== mutationEpochRef.current ||
-      !acceptState(result.state)
-    ) {
+    if (!result || !lifecycle.isCurrent(result.mutationEpoch) || !acceptState(result.state)) {
       return;
     }
     if (result.frame && isFrameCurrent(result.frame, result.state)) {
-      frameRef.current = result.frame;
+      lifecycle.accept(result.mutationEpoch, result.frame);
       setImageError(false);
-      setFrame(result.frame);
+      setFrame(lifecycle.visible);
+      setInputBusy(lifecycle.busy);
     }
   }, [acceptState, captureQuery.data]);
 
@@ -1212,6 +1212,9 @@ export function SharedBrowserPanel({
     onSuccess: (result) => mutationSucceeded(result.state),
     onError: mutationFailed,
   });
+  const settleInput = () => {
+    lifecycle.settle();
+  };
   const inputMutation = useMutation({
     mutationFn: sendBrowserInput,
     retry: false,
@@ -1220,9 +1223,13 @@ export function SharedBrowserPanel({
         const sentText = variables.event.text;
         setTypeDraft((current) => (current === sentText ? "" : current));
       }
+      settleInput();
       mutationSucceeded(result.state);
     },
-    onError: mutationFailed,
+    onError: (error) => {
+      settleInput();
+      mutationFailed(error);
+    },
   });
 
   const anyMutationPending =
@@ -1234,7 +1241,8 @@ export function SharedBrowserPanel({
     inputMutation.isPending;
   const canControl = Boolean(viewerToken && controlToken && state?.controller === "self");
   const currentFrame = frame && state && isFrameCurrent(frame, state) ? frame : null;
-  const canSendInput = canControl && Boolean(currentFrame) && !inputMutation.isPending;
+  const canSendInput =
+    canControl && Boolean(currentFrame) && !inputMutation.isPending && !inputBusy;
 
   const frameUri = useMemo(
     () => (currentFrame ? `data:${currentFrame.mimeType};base64,${currentFrame.dataBase64}` : null),
@@ -1284,7 +1292,7 @@ export function SharedBrowserPanel({
   const inputContext = useCallback(() => {
     const context = controlContext();
     const current = stateRef.current;
-    const targetFrame = frameRef.current;
+    const targetFrame = lifecycle.frame;
     if (!context || !current || !targetFrame || !isFrameCurrent(targetFrame, current)) return null;
     return {
       ...context,
@@ -1317,12 +1325,13 @@ export function SharedBrowserPanel({
 
   const sendEvent = useCallback(
     (event: BrowserInputEvent) => {
+      if (lifecycle.busy) return;
       const context = requireInputContext();
-      if (!context || inputMutation.isPending) return;
-      mutationEpochRef.current += 1;
+      if (!context || !lifecycle.begin()) return;
+      setInputBusy(true);
       inputMutation.mutate({ ...context, event });
     },
-    [inputMutation, requireInputContext],
+    [inputMutation, lifecycle, requireInputContext],
   );
 
   const pointFromEvent = useCallback(
@@ -1402,7 +1411,7 @@ export function SharedBrowserPanel({
   const takeControl = useCallback(
     (takeover: boolean) => {
       if (!viewerToken || acquireMutation.isPending) return;
-      mutationEpochRef.current += 1;
+      lifecycle.bump();
       acquireMutation.mutate({ viewerToken, takeover });
     },
     [acquireMutation, viewerToken],
@@ -1417,7 +1426,7 @@ export function SharedBrowserPanel({
     ) {
       return;
     }
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     releaseMutation.mutate({ viewerToken: viewer, controlToken });
   }, [controlToken, releaseMutation]);
 
@@ -1431,11 +1440,11 @@ export function SharedBrowserPanel({
           setOperationError("Enter an address to navigate.");
           return;
         }
-        mutationEpochRef.current += 1;
+        lifecycle.bump();
         navigateMutation.mutate({ ...context, action: { kind: "goto", url: nextUrl } });
         return;
       }
-      mutationEpochRef.current += 1;
+      lifecycle.bump();
       navigateMutation.mutate({ ...context, action: { kind: action } });
     },
     [navigateMutation, requireControlContext],
@@ -1459,7 +1468,7 @@ export function SharedBrowserPanel({
       );
       return;
     }
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     resizeMutation.mutate({ ...context, viewport: { width, height } });
   }, [requireControlContext, resizeMutation, viewportHeight, viewportWidth]);
 
@@ -1467,7 +1476,7 @@ export function SharedBrowserPanel({
     (presetId: DevicePresetId) => {
       const context = requireControlContext();
       if (!context || deviceMutation.isPending) return;
-      mutationEpochRef.current += 1;
+      lifecycle.bump();
       setDevicePickerOpen(false);
       deviceMutation.mutate({ ...context, presetId });
     },
@@ -1498,7 +1507,7 @@ export function SharedBrowserPanel({
 
   const reconnect = useCallback(() => {
     if (attachQuery.isFetching) return;
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     setReconnecting(true);
     setControlToken(null);
     setOperationError(null);
@@ -1703,7 +1712,7 @@ export function SharedBrowserPanel({
                 }
                 accessibilityRole="image"
                 onError={() => {
-                  frameRef.current = null;
+                  lifecycle.frame = null;
                   setImageError(true);
                   void captureQuery.refetch({ cancelRefetch: false });
                 }}

package/client/frame-lifecycle.ts

@@ -0,0 +1,65 @@
+import type { BrowserFrame } from "../shared/browser";
+
+/**
+ * Tracks which captured frame input may target. After an input is submitted
+ * and again when it settles, the actionable frame is dropped and the epoch
+ * advances, so captures that began earlier are ignored. Input stays blocked
+ * until a capture taken after settlement is accepted. The last accepted image
+ * stays visible meanwhile.
+ */
+export class FrameLifecycle {
+  epoch = 0;
+  /** Frame input may target; null while a fresh capture is awaited. */
+  frame: BrowserFrame | null = null;
+  /** Last accepted frame, kept on screen while input is blocked. */
+  visible: BrowserFrame | null = null;
+  private gate: "idle" | "pending" | "refreshing" = "idle";
+
+  get busy(): boolean {
+    return this.gate !== "idle";
+  }
+
+  bump(): void {
+    this.epoch += 1;
+  }
+
+  isCurrent(captureEpoch: number): boolean {
+    return captureEpoch === this.epoch;
+  }
+
+  /** Claims the input slot; false if an input is already in flight or awaiting a fresh frame. */
+  begin(): boolean {
+    if (this.busy) return false;
+    this.gate = "pending";
+    this.frame = null;
+    this.bump();
+    return true;
+  }
+
+  /** Called when an input succeeds or fails. Never replays the action. */
+  settle(): void {
+    this.frame = null;
+    this.bump();
+    this.gate = "refreshing";
+  }
+
+  /** Accepts a capture started at `captureEpoch`; false if it predates the latest boundary. */
+  accept(captureEpoch: number, frame: BrowserFrame): boolean {
+    if (!this.isCurrent(captureEpoch)) return false;
+    this.frame = frame;
+    this.visible = frame;
+    if (this.gate === "refreshing") this.gate = "idle";
+    return true;
+  }
+
+  /** Forgets all frames, e.g. when the session no longer matches them. */
+  drop(): void {
+    this.frame = null;
+    this.visible = null;
+  }
+
+  reset(): void {
+    this.drop();
+    this.gate = "idle";
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-shared-browser",
-  "version": "1.1.0-next.210.1",
+  "version": "1.1.0-next.213.1",
   "description": "One real Chromium session per Paseo workspace, shared live across every connected client.",
   "keywords": [
     "browser",
@@ -43,8 +43,8 @@
     "check:write": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "prepare:runtime": "node scripts/prepare-runtime.mjs",
-    "test": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts tests/sidebar.test.ts tests/pointer-mapping.test.ts",
-    "test:unit": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts tests/sidebar.test.ts tests/pointer-mapping.test.ts",
+    "test": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts tests/sidebar.test.ts tests/pointer-mapping.test.ts tests/frame-lifecycle.test.ts tests/viewport-resync.test.ts",
+    "test:unit": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts tests/sidebar.test.ts tests/pointer-mapping.test.ts tests/frame-lifecycle.test.ts tests/viewport-resync.test.ts",
     "test:smoke": "vitest run tests/browser.smoke.test.ts --testTimeout=30000"
   },
   "dependencies": {

package/server/agent-browser-runtime.ts

@@ -183,6 +183,26 @@ function findString(value: unknown, keys: readonly string[]): string | null {
   return null;
 }
 
+export function jpegDimensions(base64: string): { width: number; height: number } | null {
+  const bytes = Buffer.from(base64, "base64");
+  let offset = 2;
+  while (bytes[0] === 0xff && bytes[1] === 0xd8 && offset + 9 <= bytes.length) {
+    if (bytes[offset] !== 0xff) return null;
+    const marker = bytes[offset + 1];
+    // SOFn carries the frame size; DHT (c4), JPG (c8) and DAC (cc) share the range but do not.
+    if (
+      marker !== undefined &&
+      marker >= 0xc0 &&
+      marker <= 0xcf &&
+      ![0xc4, 0xc8, 0xcc].includes(marker)
+    )
+      return { width: bytes.readUInt16BE(offset + 7), height: bytes.readUInt16BE(offset + 5) };
+    if (marker === 0xda) return null;
+    offset += 2 + bytes.readUInt16BE(offset + 2);
+  }
+  return null;
+}
+
 export class AgentBrowserRuntime {
   readonly binaryPath: string;
   readonly executablePath: string;
@@ -318,7 +338,7 @@ export class AgentBrowserRuntime {
     await this.requireConnection().send("Target.activateTarget", { targetId }, { mutation: true });
     this.page = await attachToTarget(this.requireConnection(), targetId);
     this.targetId = targetId;
-    await this.bindPageEvents(this.page);
+    await this.preparePage(this.page);
     if (this.screencastActive) await this.startScreencastSession(this.page);
   }
 
@@ -425,34 +445,7 @@ export class AgentBrowserRuntime {
   async emulate(device: DeviceEmulation): Promise<void> {
     this.assertViewport(device);
     await this.withInvalidatedScreencast(async (page) => {
-      await page.send(
-        "Emulation.setDeviceMetricsOverride",
-        {
-          width: device.width,
-          height: device.height,
-          deviceScaleFactor: device.deviceScaleFactor,
-          mobile: device.mobile,
-          screenWidth: device.screenWidth ?? device.width,
-          screenHeight: device.screenHeight ?? device.height,
-          screenOrientation: {
-            type: device.width > device.height ? "landscapePrimary" : "portraitPrimary",
-            angle: device.width > device.height ? 90 : 0,
-          },
-        },
-        { mutation: true },
-      );
-      await page.send(
-        "Emulation.setTouchEmulationEnabled",
-        { enabled: device.touch, maxTouchPoints: device.touch ? 5 : 1 },
-        { mutation: true },
-      );
-      if (device.userAgent) {
-        await page.send(
-          "Emulation.setUserAgentOverride",
-          { userAgent: device.userAgent, platform: device.platform ?? "" },
-          { mutation: true },
-        );
-      }
+      await this.applyEmulation(page, device);
       this.viewport = { ...device };
     });
   }
@@ -483,7 +476,17 @@ export class AgentBrowserRuntime {
       throw new RangeError("maxBytes must be positive");
     const streamed = this.screencastFrame ?? (await this.waitForFrame(waitMs));
     if (streamed && streamed.byteLength <= maxBytes) return streamed;
-    const page = await this.requirePage();
+    let frame = await this.screenshot(await this.requirePage(), maxBytes, quality);
+    if (!this.sizeMismatch(frame)) return frame;
+    // The browser stopped honouring the cached viewport. Re-apply it once; never loop.
+    await this.emulate(this.requireViewport());
+    frame = await this.screenshot(await this.requirePage(), maxBytes, quality);
+    const mismatch = this.sizeMismatch(frame);
+    if (mismatch) throw new Error(`Browser returned a ${mismatch} after viewport resync`);
+    return frame;
+  }
+
+  private async screenshot(page: CdpSession, maxBytes: number, quality: number) {
     for (const candidate of [quality, 50, 35, 20, 10, 1]) {
       const boundedQuality = Math.max(1, Math.min(100, Math.round(candidate)));
       const result = await page.send<{ data: string }>("Page.captureScreenshot", {
@@ -502,12 +505,25 @@ export class AgentBrowserRuntime {
           height: viewport.height,
           transport: "screenshot",
           capturedAt: new Date().toISOString(),
-        };
+        } satisfies RuntimeFrame;
       }
     }
     throw new Error(`JPEG screenshot exceeds ${maxBytes} bytes at minimum quality`);
   }
 
+  private sizeMismatch(frame: RuntimeFrame): string | null {
+    const { width, height, deviceScaleFactor: scale } = this.requireViewport();
+    const size = jpegDimensions(frame.dataBase64);
+    // Chromium rounds fractional device pixels, so allow one pixel of slack.
+    if (
+      size &&
+      Math.abs(size.width - width * scale) <= 1 &&
+      Math.abs(size.height - height * scale) <= 1
+    )
+      return null;
+    return `${size ? `${size.width}x${size.height}` : "unreadable"} JPEG for a ${width}x${height} viewport at ${scale}x`;
+  }
+
   async mouseMove(x: number, y: number): Promise<void> {
     this.assertPoint(x, y);
     await (await this.requirePage()).send(
@@ -786,13 +802,46 @@ export class AgentBrowserRuntime {
     return this.viewport;
   }
 
-  private async bindPageEvents(page: CdpSession): Promise<void> {
+  private async preparePage(page: CdpSession): Promise<void> {
     page.on("Page.screencastFrame", this.onScreencastFrame);
     page.on("event", (event: CdpEvent) => {
       if (event.method === "Inspector.targetCrashed") this.invalidateScreencastFrame();
     });
     await Promise.all([page.send("Page.enable"), page.send("Runtime.enable")]);
     await this.navigationHistory(page);
+    // Emulation is scoped to the CDP session, so every fresh attach starts without it.
+    if (this.viewport) await this.applyEmulation(page, this.viewport);
+  }
+
+  private async applyEmulation(page: CdpSession, device: DeviceEmulation): Promise<void> {
+    await page.send(
+      "Emulation.setDeviceMetricsOverride",
+      {
+        width: device.width,
+        height: device.height,
+        deviceScaleFactor: device.deviceScaleFactor,
+        mobile: device.mobile,
+        screenWidth: device.screenWidth ?? device.width,
+        screenHeight: device.screenHeight ?? device.height,
+        screenOrientation: {
+          type: device.width > device.height ? "landscapePrimary" : "portraitPrimary",
+          angle: device.width > device.height ? 90 : 0,
+        },
+      },
+      { mutation: true },
+    );
+    await page.send(
+      "Emulation.setTouchEmulationEnabled",
+      { enabled: device.touch, maxTouchPoints: device.touch ? 5 : 1 },
+      { mutation: true },
+    );
+    if (device.userAgent) {
+      await page.send(
+        "Emulation.setUserAgentOverride",
+        { userAgent: device.userAgent, platform: device.platform ?? "" },
+        { mutation: true },
+      );
+    }
   }
 
   private async startScreencastSession(page: CdpSession): Promise<void> {
@@ -837,7 +886,7 @@ export class AgentBrowserRuntime {
       { mutation: true },
     );
     const replacement = await attachToTarget(connection, target.targetId);
-    await this.bindPageEvents(replacement);
+    await this.preparePage(replacement);
     if (this.page === previous) {
       this.page = replacement;
       this.targetId = target.targetId;