@omercnet/paseo-shared-browser 1.1.0-next.204.1 → 1.1.0-next.211.1

package/client/browser.tsx

@@ -29,6 +29,8 @@ import {
   type BrowserInputEvent,
   type BrowserState,
   captureBrowserRpc,
+  containedRect,
+  createImageSizeLoader,
   DEVICE_PRESETS,
   type DevicePresetId,
   detachBrowserRpc,
@@ -41,7 +43,9 @@ import {
   releaseControlRpc,
   resizeBrowserRpc,
   sendBrowserInputRpc,
+  toViewportPoint,
 } from "../shared/browser";
+import { FrameLifecycle } from "./frame-lifecycle";
 
 const SPACE = {
   xxs: 2,
@@ -88,12 +92,7 @@ interface Size {
   height: number;
 }
 
-interface DisplayRect extends Size {
-  x: number;
-  y: number;
-}
-
-interface DisplayPoint extends Size {
+interface DisplayPoint {
   x: number;
   y: number;
 }
@@ -115,21 +114,6 @@ const SPECIAL_KEYS: readonly { key: SpecialKey; label: string }[] = [
   { key: "Space", label: "Space" },
 ];
 
-function containedRect(container: Size, image: Size): DisplayRect | null {
-  if (container.width <= 0 || container.height <= 0 || image.width <= 0 || image.height <= 0) {
-    return null;
-  }
-  const scale = Math.min(container.width / image.width, container.height / image.height);
-  const width = image.width * scale;
-  const height = image.height * scale;
-  return {
-    x: (container.width - width) / 2,
-    y: (container.height - height) / 2,
-    width,
-    height,
-  };
-}
-
 function errorMessage(error: unknown): string {
   if (error instanceof Error && error.message.trim()) return error.message;
   return "The shared browser request failed.";
@@ -1006,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);
@@ -1041,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.",
@@ -1049,7 +1034,7 @@ export function SharedBrowserPanel({
       setControlToken(null);
     }
     if (currentFrame && !isFrameCurrent(currentFrame, next)) {
-      frameRef.current = null;
+      lifecycle.drop();
       setFrame(null);
       lastPointRef.current = null;
     }
@@ -1091,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);
@@ -1103,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({
@@ -1130,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]);
 
@@ -1229,6 +1212,9 @@ export function SharedBrowserPanel({
     onSuccess: (result) => mutationSucceeded(result.state),
     onError: mutationFailed,
   });
+  const settleInput = () => {
+    lifecycle.settle();
+  };
   const inputMutation = useMutation({
     mutationFn: sendBrowserInput,
     retry: false,
@@ -1237,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 =
@@ -1251,18 +1241,37 @@ 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),
+    [currentFrame],
+  );
+  const [imageSize, setImageSize] = useState<{ uri: string; size: Size } | null>(null);
+  const loadImageSize = useMemo(
+    () =>
+      createImageSizeLoader(
+        (uri, success, failure) => Image.getSize(uri, success, failure),
+        (uri, size) => setImageSize(size ? { uri, size } : null),
+      ),
+    [],
+  );
+  useEffect(() => {
+    if (frameUri) loadImageSize(frameUri);
+  }, [frameUri, loadImageSize]);
+  // The bitmap can disagree with the frame metadata; its own aspect ratio decides the rectangle.
   const displayRect = useMemo(
     () =>
       currentFrame
-        ? containedRect(containerSize, { width: currentFrame.width, height: currentFrame.height })
+        ? containedRect(
+            containerSize,
+            imageSize?.uri === frameUri
+              ? imageSize.size
+              : { width: currentFrame.width, height: currentFrame.height },
+          )
         : null,
-    [containerSize, currentFrame],
-  );
-  const frameUri = useMemo(
-    () => (currentFrame ? `data:${currentFrame.mimeType};base64,${currentFrame.dataBase64}` : null),
-    [currentFrame],
+    [containerSize, currentFrame, frameUri, imageSize],
   );
 
   const controlContext = useCallback(() => {
@@ -1283,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,
@@ -1316,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(
@@ -1329,7 +1339,7 @@ export function SharedBrowserPanel({
       if (!displayRect) return null;
       const x = Math.min(displayRect.width, Math.max(0, event.nativeEvent.locationX));
       const y = Math.min(displayRect.height, Math.max(0, event.nativeEvent.locationY));
-      return { x, y, width: displayRect.width, height: displayRect.height };
+      return { x, y };
     },
     [displayRect],
   );
@@ -1338,17 +1348,18 @@ export function SharedBrowserPanel({
     (event: GestureResponderEvent) => {
       const start = dragStartRef.current;
       const end = pointFromEvent(event);
+      const viewport = stateRef.current?.viewport;
       dragStartRef.current = null;
-      if (!start || !end) return;
+      if (!start || !end || !displayRect || !viewport) return;
+      const toViewport = (point: DisplayPoint) => toViewportPoint(point, displayRect, viewport);
       lastPointRef.current = { x: end.x, y: end.y };
       const distance = Math.hypot(end.x - start.x, end.y - start.y);
       if (distance >= DRAG_THRESHOLD) {
         if (swipeMode === "scroll") {
-          const current = stateRef.current;
-          const scale = current ? current.viewport.width / end.width : 1;
+          const scale = viewport.width / displayRect.width;
           sendEvent({
             kind: "scroll",
-            point: { ...start, width: end.width, height: end.height },
+            point: toViewport(start),
             deltaX: clampScrollDelta((start.x - end.x) * scale),
             deltaY: clampScrollDelta((start.y - end.y) * scale),
           });
@@ -1356,20 +1367,20 @@ export function SharedBrowserPanel({
         }
         sendEvent({
           kind: "drag",
-          start: { ...start, width: end.width, height: end.height },
-          end,
+          start: toViewport(start),
+          end: toViewport(end),
           button: interactionMode === "right" ? "right" : "left",
         });
         return;
       }
       sendEvent({
         kind: "click",
-        point: end,
+        point: toViewport(end),
         button: interactionMode === "right" ? "right" : "left",
         clickCount: interactionMode === "double" ? 2 : 1,
       });
     },
-    [interactionMode, pointFromEvent, sendEvent, swipeMode],
+    [displayRect, interactionMode, pointFromEvent, sendEvent, swipeMode],
   );
 
   const panResponder = useMemo(
@@ -1400,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],
@@ -1415,7 +1426,7 @@ export function SharedBrowserPanel({
     ) {
       return;
     }
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     releaseMutation.mutate({ viewerToken: viewer, controlToken });
   }, [controlToken, releaseMutation]);
 
@@ -1429,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],
@@ -1457,7 +1468,7 @@ export function SharedBrowserPanel({
       );
       return;
     }
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     resizeMutation.mutate({ ...context, viewport: { width, height } });
   }, [requireControlContext, resizeMutation, viewportHeight, viewportWidth]);
 
@@ -1465,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 });
     },
@@ -1474,13 +1485,14 @@ export function SharedBrowserPanel({
 
   const scroll = useCallback(
     (deltaX: number, deltaY: number) => {
-      if (!displayRect) return;
+      const viewport = stateRef.current?.viewport;
+      if (!displayRect || !viewport) return;
       const previous = lastPointRef.current;
       const x = previous && previous.x <= displayRect.width ? previous.x : displayRect.width / 2;
       const y = previous && previous.y <= displayRect.height ? previous.y : displayRect.height / 2;
       sendEvent({
         kind: "scroll",
-        point: { x, y, width: displayRect.width, height: displayRect.height },
+        point: toViewportPoint({ x, y }, displayRect, viewport),
         deltaX,
         deltaY,
       });
@@ -1495,7 +1507,7 @@ export function SharedBrowserPanel({
 
   const reconnect = useCallback(() => {
     if (attachQuery.isFetching) return;
-    mutationEpochRef.current += 1;
+    lifecycle.bump();
     setReconnecting(true);
     setControlToken(null);
     setOperationError(null);
@@ -1700,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.204.1",
+  "version": "1.1.0-next.211.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",
-    "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",
+    "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",
+    "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",
     "test:smoke": "vitest run tests/browser.smoke.test.ts --testTimeout=30000"
   },
   "dependencies": {

package/shared/browser.ts

@@ -365,3 +365,70 @@ export function mapDisplayedPoint(
     y: Math.min(viewport.height - 1, Math.max(0, (point.y / point.height) * viewport.height)),
   };
 }
+
+export interface FrameSize {
+  width: number;
+  height: number;
+}
+
+export interface FrameRect extends FrameSize {
+  x: number;
+  y: number;
+}
+
+export function containedRect(container: FrameSize, image: FrameSize): FrameRect | null {
+  if (container.width <= 0 || container.height <= 0 || image.width <= 0 || image.height <= 0) {
+    return null;
+  }
+  const scale = Math.min(container.width / image.width, container.height / image.height);
+  const width = image.width * scale;
+  const height = image.height * scale;
+  return {
+    x: (container.width - width) / 2,
+    y: (container.height - height) / 2,
+    width,
+    height,
+  };
+}
+
+/** Converts a point in the displayed image to the canonical viewport, scaling both axes by viewport.width / rect.width. */
+export function toViewportPoint(
+  point: MappedPoint,
+  rect: FrameSize,
+  viewport: Viewport,
+): MappedPoint & FrameSize {
+  const scale = viewport.width / rect.width;
+  return {
+    x: point.x * scale,
+    y: Math.min(viewport.height, point.y * scale),
+    width: viewport.width,
+    height: viewport.height,
+  };
+}
+
+type GetImageSize = (
+  uri: string,
+  success: (width: number, height: number) => void,
+  failure: () => void,
+) => void;
+
+/** Looks up the intrinsic size once per distinct URI and drops results superseded by a newer URI. */
+export function createImageSizeLoader(
+  getSize: GetImageSize,
+  onSize: (uri: string, size: FrameSize | null) => void,
+): (uri: string) => void {
+  let current: string | null = null;
+  return (uri) => {
+    if (uri === current) return;
+    current = uri;
+    getSize(
+      uri,
+      (width, height) => {
+        if (current === uri) onSize(uri, { width, height });
+      },
+      () => {
+        if (current === uri) onSize(uri, null);
+      },
+    );
+  };
+}