@opengeni/react 3.1.0 → 3.1.2

package/src/hooks/use-browser-session.ts

@@ -19,10 +19,28 @@ import {
 import { isNonRetryableInteractionError } from "../lib/interaction-errors";
 import { usePageLiveActivity } from "./internal";
 
+/** Immutable input fence; queued actions never need the encoded screenshot. */
+export type BrowserFrameInputFence = Pick<
+  BrowserFrame,
+  | "browserSessionId"
+  | "controllerGeneration"
+  | "targetId"
+  | "targetGeneration"
+  | "documentGeneration"
+  | "frameId"
+>;
+
+export type BrowserInputFailure = Pick<BrowserActionReceipt, "operationId" | "error"> & {
+  state: Exclude<BrowserActionReceipt["state"], "completed">;
+};
+
 export type UseBrowserSessionOptions = EmbeddedBrowserInteractionClientOverride & {
   browserSessionId: string | null;
   enabled?: boolean | undefined;
   pollIntervalMs?: number | undefined;
+  /** Keep session/tab inventory current without repeatedly fetching the full
+   * accessibility tree while a live frame is available or the viewer is hidden. */
+  semanticObservationEnabled?: boolean | undefined;
 };
 
 export type UseBrowserSessionResult = {
@@ -33,7 +51,13 @@ export type UseBrowserSessionResult = {
   loading: boolean;
   mutating: boolean;
   error: Error | null;
+  inputFailure: BrowserInputFailure | null;
   refresh: () => Promise<void>;
+  observeForInput: () => Promise<BrowserObservation>;
+  actFromObservation: (
+    action: BrowserAction,
+    observation: BrowserObservation,
+  ) => Promise<BrowserActionReceipt>;
   selectTarget: (targetId: string) => Promise<BrowserTarget>;
   openTarget: (url?: string) => Promise<BrowserTarget>;
   closeTarget: (targetId: string) => Promise<void>;
@@ -45,8 +69,9 @@ export type UseBrowserSessionResult = {
    *  the controller fence instead of targeting a newer page. */
   actFromFrame: (
     action: BrowserAction | BrowserActionBatch,
-    frame: BrowserFrame,
+    frame: BrowserFrameInputFence,
     operationId?: string,
+    observationMode?: "none" | "input",
   ) => Promise<BrowserActionReceipt>;
   readClipboard: () => Promise<BrowserClipboard>;
   diagnostics: (options?: BrowserDiagnosticsOptions) => Promise<BrowserDiagnosticBatch>;
@@ -58,9 +83,27 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
   const { client, workspaceId } = useEmbeddedBrowserInteraction(options);
   const browserSessionId = options.browserSessionId;
   const enabled = (options.enabled ?? true) && browserSessionId !== null;
+  const sourceRef = useRef({ client, workspaceId, browserSessionId, enabled });
+  if (
+    sourceRef.current.client !== client ||
+    sourceRef.current.workspaceId !== workspaceId ||
+    sourceRef.current.browserSessionId !== browserSessionId ||
+    sourceRef.current.enabled !== enabled
+  ) {
+    sourceRef.current = { client, workspaceId, browserSessionId, enabled };
+  }
+  const source = sourceRef.current;
+  const semanticObservationEnabled = options.semanticObservationEnabled ?? true;
+  const semanticObservationEnabledRef = useRef(semanticObservationEnabled);
+  semanticObservationEnabledRef.current = semanticObservationEnabled;
+  const previousSemanticObservationRef = useRef({
+    browserSessionId,
+    enabled: semanticObservationEnabled,
+  });
   const pageLive = usePageLiveActivity();
   const pollIntervalMs = Math.max(750, options.pollIntervalMs ?? 2_000);
   const [state, setState] = useState<{
+    source: typeof source;
     browserSessionId: string | null;
     session: BrowserSession | null;
     targets: BrowserTarget[];
@@ -69,16 +112,30 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     loading: boolean;
     mutating: boolean;
     error: Error | null;
-  }>(() => emptyState(browserSessionId, enabled));
+    inputFailure: BrowserInputFailure | null;
+    actionResultOrder: number;
+  }>(() => ({ ...emptyState(browserSessionId, enabled), source }));
   const visible =
-    state.browserSessionId === browserSessionId ? state : emptyState(browserSessionId, enabled);
+    state.source === source && state.browserSessionId === browserSessionId
+      ? state
+      : { ...emptyState(browserSessionId, enabled), source };
   const refreshBlocked = isNonRetryableInteractionError(visible.error);
+  const inputFailureRef = useRef(visible.inputFailure);
+  inputFailureRef.current = visible.inputFailure;
   const selectedTargetIdRef = useRef<string | null>(visible.selectedTargetId);
   selectedTargetIdRef.current = visible.selectedTargetId;
+  const selectionRevisionRef = useRef(0);
+  const actionResultOrderRef = useRef({ next: 0, settled: 0 });
+  const selectedTargetRef = useRef<BrowserTarget | null>(
+    visible.targets.find((target) => target.id === visible.selectedTargetId) ?? null,
+  );
+  selectedTargetRef.current =
+    visible.targets.find((target) => target.id === visible.selectedTargetId) ?? null;
   const observationRef = useRef<{
     browserSessionId: string | null;
     observation: BrowserObservation | null;
   }>({ browserSessionId, observation: visible.observation });
+  const lastObservationAtRef = useRef(0);
   if (observationRef.current.browserSessionId !== browserSessionId) {
     observationRef.current = {
       browserSessionId,
@@ -93,12 +150,20 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
   });
   const mutationRef = useRef<{
     browserSessionId: string | null;
+    source: typeof source;
     count: number;
+    needsInventoryReconcile: boolean;
   }>({
     browserSessionId,
+    source,
     count: 0,
+    needsInventoryReconcile: false,
   });
   const mountedRef = useRef(true);
+  const isCurrentSource = useCallback(
+    () => mountedRef.current && sourceRef.current === source,
+    [source],
+  );
 
   const invalidateRefresh = useCallback(() => {
     const id = requestRef.current.id + 1;
@@ -106,113 +171,244 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     requestRef.current = { id, controller: null };
   }, []);
 
-  const refresh = useCallback(async (): Promise<void> => {
-    if (!enabled || !browserSessionId) return;
-    const id = requestRef.current.id + 1;
-    requestRef.current.controller?.abort();
-    const controller = new AbortController();
-    requestRef.current = { id, controller };
-    try {
-      const [session, targetResponse] = await Promise.all([
-        client.getBrowserSession(workspaceId, browserSessionId, {
-          signal: controller.signal,
-        }),
-        client.listBrowserTargets(workspaceId, browserSessionId, {
-          signal: controller.signal,
-        }),
-      ]);
-      if (!mountedRef.current || requestRef.current.id !== id) return;
-      const selected = chooseTarget(targetResponse.targets, selectedTargetIdRef.current);
-      selectedTargetIdRef.current = selected?.id ?? null;
-      observationRef.current = { browserSessionId, observation: null };
-      setState((current) =>
-        current.browserSessionId === browserSessionId
-          ? {
-              ...current,
-              session,
-              targets: targetResponse.targets,
-              selectedTargetId: selected?.id ?? null,
-              observation: null,
-              loading: false,
-              error: null,
-            }
-          : current,
-      );
-      if (!selected) return;
+  const refreshInventory = useCallback(
+    async (checkInput = false, observeSelectedTarget = true) => {
+      if (!enabled || !browserSessionId || !isCurrentSource()) return;
+      const checkedInputFailure = inputFailureRef.current;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
       try {
-        const observation = await client.observeBrowserTarget(
-          workspaceId,
+        const [session, targetResponse] = await Promise.all([
+          client.getBrowserSession(workspaceId, browserSessionId, {
+            signal: controller.signal,
+          }),
+          client.listBrowserTargets(workspaceId, browserSessionId, {
+            signal: controller.signal,
+          }),
+        ]);
+        if (!isCurrentSource() || requestRef.current.id !== id) return;
+        const selected = chooseTarget(targetResponse.targets, selectedTargetIdRef.current);
+        selectedTargetIdRef.current = selected?.id ?? null;
+        selectedTargetRef.current = selected;
+        const previousObservation =
+          observationRef.current.browserSessionId === browserSessionId
+            ? observationRef.current.observation
+            : null;
+        const retainedObservation =
+          selected && previousObservation && sameObservationTarget(previousObservation, selected)
+            ? previousObservation
+            : null;
+        observationRef.current = {
           browserSessionId,
-          selected.id,
-          { signal: controller.signal },
-        );
-        if (!mountedRef.current || requestRef.current.id !== id) return;
-        observationRef.current = { browserSessionId, observation };
+          observation: retainedObservation,
+        };
         setState((current) =>
-          current.browserSessionId === browserSessionId &&
-          current.selectedTargetId === observation.target.id
-            ? { ...current, observation }
+          isCurrentSource() &&
+          current.source === source &&
+          current.browserSessionId === browserSessionId
+            ? {
+                ...current,
+                session,
+                targets: targetResponse.targets,
+                selectedTargetId: selected?.id ?? null,
+                observation: retainedObservation,
+                loading: false,
+                error: null,
+                // Media and background polling cannot confirm an input outcome.
+                // Only an explicit fresh check clears the notice it began with.
+                inputFailure:
+                  checkInput &&
+                  session.id === browserSessionId &&
+                  targetResponse.browserSessionId === browserSessionId &&
+                  current.inputFailure === checkedInputFailure
+                    ? null
+                    : current.inputFailure,
+              }
             : current,
         );
+        if (!selected || !observeSelectedTarget || !semanticObservationEnabledRef.current) return;
+        try {
+          const observation = await client.observeBrowserTarget(
+            workspaceId,
+            browserSessionId,
+            selected.id,
+            { signal: controller.signal },
+          );
+          if (!isCurrentSource() || requestRef.current.id !== id) return;
+          const currentSelected = selectedTargetRef.current;
+          if (
+            observationRef.current.browserSessionId !== browserSessionId ||
+            currentSelected?.id !== selected.id ||
+            observation.browserSessionId !== browserSessionId ||
+            observation.target.id !== selected.id ||
+            observation.target.controllerGeneration !== currentSelected.controllerGeneration ||
+            observation.target.targetGeneration !== currentSelected.targetGeneration
+          )
+            return;
+          // Navigation may complete between the inventory and its selected-page
+          // observation. Keep both the selected target and input fence coherent.
+          selectedTargetRef.current = observation.target;
+          observationRef.current = { browserSessionId, observation };
+          lastObservationAtRef.current = Date.now();
+          setState((current) =>
+            isCurrentSource() &&
+            current.source === source &&
+            current.browserSessionId === browserSessionId &&
+            current.selectedTargetId === observation.target.id
+              ? {
+                  ...current,
+                  observation,
+                  targets: replaceTarget(current.targets, observation.target),
+                }
+              : current,
+          );
+        } catch (cause) {
+          if (controller.signal.aborted || !isCurrentSource() || requestRef.current.id !== id)
+            return;
+          // Target inventory and the media plane remain authoritative for the
+          // human-facing browser. A failed semantic snapshot must not blank or
+          // disable an otherwise live visual browser.
+          void cause;
+        }
       } catch (cause) {
-        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
-          return;
-        // Target inventory and the media plane remain authoritative for the
-        // human-facing browser. A failed semantic snapshot must not blank or
-        // disable an otherwise live visual browser.
-        void cause;
+        if (controller.signal.aborted || !isCurrentSource() || requestRef.current.id !== id) return;
+        setState((current) =>
+          isCurrentSource() &&
+          current.source === source &&
+          current.browserSessionId === browserSessionId
+            ? {
+                ...current,
+                loading: false,
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+              }
+            : current,
+        );
+      } finally {
+        if (requestRef.current.id === id) {
+          requestRef.current = { id, controller: null };
+        }
       }
-    } catch (cause) {
-      if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id) return;
+    },
+    [browserSessionId, client, enabled, isCurrentSource, source, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await refreshInventory(true), [refreshInventory]);
+
+  const refreshSemantic = useCallback(async (): Promise<void> => {
+    if (!enabled || !browserSessionId || !isCurrentSource()) return;
+    const target = selectedTargetRef.current;
+    if (!target) return;
+    const id = requestRef.current.id + 1;
+    requestRef.current.controller?.abort();
+    const controller = new AbortController();
+    requestRef.current = { id, controller };
+    try {
+      const observation = await client.observeBrowserTarget(
+        workspaceId,
+        browserSessionId,
+        target.id,
+        { signal: controller.signal },
+      );
+      if (!isCurrentSource() || requestRef.current.id !== id) return;
+      if (!sameObservationTarget(observation, selectedTargetRef.current)) return;
+      observationRef.current = { browserSessionId, observation };
+      lastObservationAtRef.current = Date.now();
       setState((current) =>
-        current.browserSessionId === browserSessionId
-          ? {
-              ...current,
-              loading: false,
-              error: cause instanceof Error ? cause : new Error(String(cause)),
-            }
+        isCurrentSource() &&
+        current.source === source &&
+        current.browserSessionId === browserSessionId &&
+        current.selectedTargetId === target.id
+          ? { ...current, observation }
           : current,
       );
+    } catch {
+      // A failed semantic fallback cannot disable an otherwise live browser.
     } finally {
-      if (requestRef.current.id === id) {
-        requestRef.current = { id, controller: null };
-      }
+      if (requestRef.current.id === id) requestRef.current = { id, controller: null };
     }
-  }, [browserSessionId, client, enabled, workspaceId]);
+  }, [browserSessionId, client, enabled, isCurrentSource, source, workspaceId]);
 
   useEffect(() => {
     mountedRef.current = true;
     if (!enabled) {
       invalidateRefresh();
-      setState(emptyState(browserSessionId, false));
+      setState({ ...emptyState(browserSessionId, false), source });
       return;
     }
     setState((current) =>
+      isCurrentSource() &&
+      current.source === source &&
       current.browserSessionId === browserSessionId
         ? { ...current, loading: true }
-        : emptyState(browserSessionId, true),
+        : { ...emptyState(browserSessionId, true), source },
     );
-    void refresh();
+    void refreshInventory();
     return () => {
       mountedRef.current = false;
       invalidateRefresh();
     };
-  }, [browserSessionId, enabled, invalidateRefresh, refresh]);
+  }, [browserSessionId, enabled, invalidateRefresh, isCurrentSource, refreshInventory, source]);
+
+  useEffect(() => {
+    const previous = previousSemanticObservationRef.current;
+    previousSemanticObservationRef.current = {
+      browserSessionId,
+      enabled: semanticObservationEnabled,
+    };
+    if (
+      enabled &&
+      semanticObservationEnabled &&
+      previous.browserSessionId === browserSessionId &&
+      !previous.enabled
+    ) {
+      // The media stream disappeared or the user returned to the Browser tab.
+      // A just-returned action/tab observation is already a fresh fallback.
+      // Otherwise drop the old tree/fence until a new read settles.
+      const currentObservation = observationRef.current.observation;
+      if (
+        currentObservation &&
+        sameObservationTarget(currentObservation, selectedTargetRef.current) &&
+        Date.now() - lastObservationAtRef.current < pollIntervalMs
+      ) {
+        return;
+      }
+      observationRef.current = { browserSessionId, observation: null };
+      setState((current) =>
+        isCurrentSource() &&
+        current.source === source &&
+        current.browserSessionId === browserSessionId
+          ? { ...current, observation: null }
+          : current,
+      );
+      void refreshSemantic();
+    }
+  }, [
+    browserSessionId,
+    enabled,
+    isCurrentSource,
+    pollIntervalMs,
+    refreshSemantic,
+    semanticObservationEnabled,
+    source,
+  ]);
 
   useEffect(() => {
     if (!enabled || !pageLive || visible.mutating || refreshBlocked) return;
     const timer = setInterval(() => {
-      if (!requestRef.current.controller) void refresh();
+      if (!requestRef.current.controller) void refreshInventory();
     }, pollIntervalMs);
     return () => clearInterval(timer);
-  }, [enabled, pageLive, pollIntervalMs, refresh, refreshBlocked, visible.mutating]);
+  }, [enabled, pageLive, pollIntervalMs, refreshInventory, refreshBlocked, visible.mutating]);
 
   useEffect(() => {
     if (!enabled || !browserSessionId || !pageLive || refreshBlocked) return;
     let disposed = false;
     const heartbeat = () => {
+      if (!isCurrentSource()) return;
       void client.heartbeatBrowserSession(workspaceId, browserSessionId).catch(() => {
-        if (!disposed) void refresh();
+        if (!disposed) void refreshInventory();
       });
     };
     const timer = setInterval(heartbeat, 30_000);
@@ -220,173 +416,306 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
       disposed = true;
       clearInterval(timer);
     };
-  }, [browserSessionId, client, enabled, pageLive, refresh, refreshBlocked, workspaceId]);
+  }, [
+    browserSessionId,
+    client,
+    enabled,
+    isCurrentSource,
+    pageLive,
+    refreshInventory,
+    refreshBlocked,
+    workspaceId,
+  ]);
 
   const runMutation = useCallback(
-    async <T>(scopeBrowserSessionId: string, operation: () => Promise<T>): Promise<T> => {
+    async <T>(
+      scopeBrowserSessionId: string,
+      operation: (selectionRevision: number, readRequestId: number) => Promise<T>,
+      selectionRead = false,
+      changesInventory = false,
+    ): Promise<T> => {
+      if (!enabled || !isCurrentSource()) {
+        throw new Error("The browser source is no longer selected.");
+      }
+      const selectionRevision = ++selectionRevisionRef.current;
       invalidateRefresh();
-      if (mutationRef.current.browserSessionId !== scopeBrowserSessionId) {
+      const readRequestId = requestRef.current.id;
+      if (
+        mutationRef.current.browserSessionId !== scopeBrowserSessionId ||
+        mutationRef.current.source !== source
+      ) {
         mutationRef.current = {
           browserSessionId: scopeBrowserSessionId,
+          source,
           count: 0,
+          needsInventoryReconcile: false,
         };
       }
       mutationRef.current.count += 1;
       setState((current) =>
+        isCurrentSource() &&
+        current.source === source &&
         current.browserSessionId === scopeBrowserSessionId
           ? { ...current, mutating: true, error: null }
           : current,
       );
       try {
-        return await operation();
+        return await operation(selectionRevision, readRequestId);
       } catch (cause) {
         const error = cause instanceof Error ? cause : new Error(String(cause));
-        setState((current) =>
-          current.browserSessionId === scopeBrowserSessionId ? { ...current, error } : current,
-        );
+        // Selection observations share refresh ordering; physical mutations
+        // keep their existing outcome admission.
+        if (!selectionRead || requestRef.current.id === readRequestId) {
+          setState((current) =>
+            isCurrentSource() &&
+            selectionRevisionRef.current === selectionRevision &&
+            current.source === source &&
+            current.browserSessionId === scopeBrowserSessionId
+              ? { ...current, error }
+              : current,
+          );
+        }
         throw error;
       } finally {
-        if (mutationRef.current.browserSessionId === scopeBrowserSessionId) {
+        if (
+          mutationRef.current.browserSessionId === scopeBrowserSessionId &&
+          mutationRef.current.source === source
+        ) {
+          if (
+            changesInventory &&
+            (selectionRevisionRef.current !== selectionRevision ||
+              requestRef.current.id !== readRequestId)
+          ) {
+            mutationRef.current.needsInventoryReconcile = true;
+          }
           mutationRef.current.count = Math.max(0, mutationRef.current.count - 1);
           const mutating = mutationRef.current.count > 0;
           setState((current) =>
-            current.browserSessionId === scopeBrowserSessionId ? { ...current, mutating } : current,
+            isCurrentSource() &&
+            current.source === source &&
+            current.browserSessionId === scopeBrowserSessionId
+              ? { ...current, mutating }
+              : current,
           );
+          if (!mutating && mutationRef.current.needsInventoryReconcile && isCurrentSource()) {
+            mutationRef.current.needsInventoryReconcile = false;
+            // A superseded tab mutation still changed the real inventory. Wait
+            // for all selections to settle, then reconcile without replacing
+            // the latest selected-page observation or cancelling its read.
+            void refreshInventory(false, false);
+          }
         }
       }
     },
-    [invalidateRefresh],
+    [enabled, invalidateRefresh, isCurrentSource, refreshInventory, source],
   );
 
   const selectTarget = useCallback(
     async (targetId: string): Promise<BrowserTarget> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
-      return await runMutation(browserSessionId, async () => {
-        let targets = visible.targets;
-        let target: BrowserTarget;
-        let observation: BrowserObservation;
-        try {
-          observation = await client.selectBrowserTarget(workspaceId, browserSessionId, targetId);
-          target = observation.target;
-        } catch (cause) {
-          if (!isMissingBrowserTarget(cause)) throw cause;
-          // A physical/attached tab may disappear between inventory and click.
-          // Reconcile once from the authoritative controller inventory and move
-          // to its live selected/first page instead of leaving a dead tab ID in
-          // React state. Session-level 404s are deliberately not swallowed.
-          const response = await client.listBrowserTargets(workspaceId, browserSessionId);
-          targets = response.targets;
-          const fallback = chooseTarget(targets, null);
-          if (!fallback) {
-            selectedTargetIdRef.current = null;
-            observationRef.current = { browserSessionId, observation: null };
-            setState((current) =>
-              current.browserSessionId === browserSessionId
-                ? {
-                    ...current,
-                    targets,
-                    selectedTargetId: null,
-                    observation: null,
-                  }
-                : current,
+      return await runMutation(
+        browserSessionId,
+        async (selectionRevision, readRequestId) => {
+          const isCurrentSelection = () =>
+            isCurrentSource() && selectionRevisionRef.current === selectionRevision;
+          // Once admitted, a queued observation survives immediate input.
+          const isCurrentSelectionRead = () =>
+            isCurrentSelection() && requestRef.current.id === readRequestId;
+          let targets = visible.targets;
+          let target: BrowserTarget;
+          let observation: BrowserObservation;
+          try {
+            observation = await client.selectBrowserTarget(workspaceId, browserSessionId, targetId);
+            target = observation.target;
+          } catch (cause) {
+            if (!isCurrentSelectionRead() || !isMissingBrowserTarget(cause)) throw cause;
+            // A physical/attached tab may disappear between inventory and click.
+            // Reconcile once from the authoritative controller inventory and move
+            // to its live selected/first page instead of leaving a dead tab ID in
+            // React state. Session-level 404s are deliberately not swallowed.
+            const response = await client.listBrowserTargets(workspaceId, browserSessionId);
+            if (!isCurrentSelectionRead()) throw cause;
+            targets = response.targets;
+            const fallback = chooseTarget(targets, null);
+            if (!fallback) {
+              selectedTargetIdRef.current = null;
+              selectedTargetRef.current = null;
+              observationRef.current = { browserSessionId, observation: null };
+              setState((current) =>
+                isCurrentSelection() &&
+                current.source === source &&
+                current.browserSessionId === browserSessionId
+                  ? {
+                      ...current,
+                      targets,
+                      selectedTargetId: null,
+                      observation: null,
+                    }
+                  : current,
+              );
+              throw cause;
+            }
+            observation = await client.selectBrowserTarget(
+              workspaceId,
+              browserSessionId,
+              fallback.id,
             );
-            throw cause;
+            target = observation.target;
           }
-          observation = await client.selectBrowserTarget(
-            workspaceId,
-            browserSessionId,
-            fallback.id,
+          if (!isCurrentSelectionRead()) return target;
+          selectedTargetIdRef.current = target.id;
+          selectedTargetRef.current = target;
+          observationRef.current = { browserSessionId, observation };
+          lastObservationAtRef.current = Date.now();
+          setState((current) =>
+            isCurrentSelection() &&
+            current.source === source &&
+            current.browserSessionId === browserSessionId
+              ? {
+                  ...current,
+                  targets: replaceTarget(targets, target).map((candidate) => ({
+                    ...candidate,
+                    selected: candidate.id === target.id,
+                  })),
+                  selectedTargetId: target.id,
+                  observation,
+                }
+              : current,
           );
-          target = observation.target;
-        }
-        selectedTargetIdRef.current = target.id;
-        observationRef.current = { browserSessionId, observation };
-        setState((current) =>
-          current.browserSessionId === browserSessionId
-            ? {
-                ...current,
-                targets: targets.map((candidate) => ({
-                  ...candidate,
-                  selected: candidate.id === target.id,
-                })),
-                selectedTargetId: target.id,
-                observation,
-              }
-            : current,
-        );
-        return target;
-      });
+          return target;
+        },
+        true,
+      );
     },
-    [browserSessionId, client, runMutation, visible.targets, workspaceId],
+    [browserSessionId, client, isCurrentSource, runMutation, source, visible.targets, workspaceId],
   );
 
   const openTarget = useCallback(
     async (url?: string): Promise<BrowserTarget> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
-      return await runMutation(browserSessionId, async () => {
-        const observation = await client.openBrowserTarget(
-          workspaceId,
-          browserSessionId,
-          url === undefined ? {} : { url },
-        );
-        const target = observation.target;
-        selectedTargetIdRef.current = target.id;
-        observationRef.current = { browserSessionId, observation };
-        setState((current) =>
-          current.browserSessionId === browserSessionId
-            ? {
-                ...current,
-                targets: [
-                  ...current.targets.map((candidate) => ({
-                    ...candidate,
-                    selected: false,
-                  })),
-                  target,
-                ],
-                selectedTargetId: target.id,
-                observation,
-              }
-            : current,
-        );
-        return target;
-      });
+      return await runMutation(
+        browserSessionId,
+        async (selectionRevision, readRequestId) => {
+          const isCurrentSelection = () =>
+            isCurrentSource() && selectionRevisionRef.current === selectionRevision;
+          const isCurrentSelectionRead = () =>
+            isCurrentSelection() && requestRef.current.id === readRequestId;
+          const observation = await client.openBrowserTarget(
+            workspaceId,
+            browserSessionId,
+            url === undefined ? {} : { url },
+          );
+          const target = observation.target;
+          if (!isCurrentSource()) return target;
+          if (!isCurrentSelectionRead()) return target;
+          selectedTargetIdRef.current = target.id;
+          selectedTargetRef.current = target;
+          observationRef.current = { browserSessionId, observation };
+          lastObservationAtRef.current = Date.now();
+          setState((current) =>
+            isCurrentSelection() &&
+            current.source === source &&
+            current.browserSessionId === browserSessionId
+              ? {
+                  ...current,
+                  targets: [
+                    ...current.targets.map((candidate) => ({
+                      ...candidate,
+                      selected: false,
+                    })),
+                    target,
+                  ],
+                  selectedTargetId: target.id,
+                  observation,
+                }
+              : current,
+          );
+          return target;
+        },
+        false,
+        true,
+      );
     },
-    [browserSessionId, client, runMutation, workspaceId],
+    [browserSessionId, client, isCurrentSource, runMutation, source, workspaceId],
   );
 
   const closeTarget = useCallback(
     async (targetId: string): Promise<void> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
-      await runMutation(browserSessionId, async () => {
-        const response = await client.closeBrowserTarget(workspaceId, browserSessionId, targetId);
-        const selected = chooseTarget(response.targets, null);
-        const observation = selected
-          ? await client.observeBrowserTarget(workspaceId, browserSessionId, selected.id)
-          : null;
-        selectedTargetIdRef.current = selected?.id ?? null;
-        observationRef.current = { browserSessionId, observation };
-        setState((current) =>
-          current.browserSessionId === browserSessionId
-            ? {
-                ...current,
-                targets: response.targets,
-                selectedTargetId: selected?.id ?? null,
-                observation,
-              }
-            : current,
-        );
-      });
+      await runMutation(
+        browserSessionId,
+        async (selectionRevision, readRequestId) => {
+          const isCurrentSelection = () =>
+            isCurrentSource() && selectionRevisionRef.current === selectionRevision;
+          const isCurrentSelectionRead = () =>
+            isCurrentSelection() && requestRef.current.id === readRequestId;
+          const response = await client.closeBrowserTarget(workspaceId, browserSessionId, targetId);
+          if (!isCurrentSource()) return;
+          if (!isCurrentSelectionRead()) return;
+          const selected = chooseTarget(response.targets, selectedTargetIdRef.current);
+          const observed = selected
+            ? await client.observeBrowserTarget(workspaceId, browserSessionId, selected.id)
+            : null;
+          if (!isCurrentSource()) return;
+          if (!isCurrentSelectionRead()) return;
+          const observation =
+            observed &&
+            selected &&
+            observed.browserSessionId === browserSessionId &&
+            observed.target.id === selected.id &&
+            observed.target.controllerGeneration === selected.controllerGeneration &&
+            observed.target.targetGeneration === selected.targetGeneration
+              ? observed
+              : null;
+          const currentTarget = observation?.target ?? selected;
+          selectedTargetIdRef.current = currentTarget?.id ?? null;
+          selectedTargetRef.current = currentTarget;
+          observationRef.current = { browserSessionId, observation };
+          if (observation) lastObservationAtRef.current = Date.now();
+          setState((current) =>
+            isCurrentSelection() &&
+            current.source === source &&
+            current.browserSessionId === browserSessionId
+              ? {
+                  ...current,
+                  targets: currentTarget
+                    ? replaceTarget(response.targets, currentTarget)
+                    : response.targets,
+                  selectedTargetId: currentTarget?.id ?? null,
+                  observation,
+                }
+              : current,
+          );
+        },
+        false,
+        true,
+      );
     },
-    [browserSessionId, client, runMutation, workspaceId],
+    [browserSessionId, client, isCurrentSource, runMutation, source, workspaceId],
   );
 
   const dispatchAction = useCallback(
     async (
       action: BrowserAction | BrowserActionBatch,
       operationId: string,
-      frame: BrowserFrame | null,
+      frame:
+        | (Pick<
+            BrowserFrame,
+            "browserSessionId" | "controllerGeneration" | "targetId" | "targetGeneration"
+          > & {
+            frameId: string | null;
+            documentGeneration: string | null;
+          })
+        | null,
+      observationMode: "none" | "input" = "none",
     ): Promise<BrowserActionReceipt> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
+      if (!enabled || !isCurrentSource()) {
+        throw new Error("The browser source is no longer selected.");
+      }
+      if (!selectedTargetRef.current) {
+        throw new Error("The browser page is not ready for input.");
+      }
       if (frame && frame.browserSessionId !== browserSessionId) {
         throw new Error("The displayed browser frame belongs to another BrowserSession.");
       }
@@ -401,7 +730,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
             expectedDocumentGeneration: frame.documentGeneration,
             expectedFrameId: frame.frameId,
           }
-        : currentObservation
+        : currentObservation && sameObservationTarget(currentObservation, selectedTargetRef.current)
           ? {
               targetId: currentObservation.target.id,
               expectedTargetGeneration: currentObservation.target.targetGeneration,
@@ -412,38 +741,123 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
       if (!fence) {
         throw new Error("The browser page is not ready for input.");
       }
+      const expectedControllerGeneration =
+        frame?.controllerGeneration ?? currentObservation!.target.controllerGeneration;
+      const selectionRevision = selectionRevisionRef.current;
+      const resultOrder = ++actionResultOrderRef.current.next;
+      let resultDocumentGeneration = fence.expectedDocumentGeneration;
+      const isCurrentResultView = () => {
+        const selected = selectedTargetRef.current;
+        return (
+          isCurrentSource() &&
+          selectionRevisionRef.current === selectionRevision &&
+          selected?.browserSessionId === browserSessionId &&
+          selected.id === fence.targetId &&
+          selected.controllerGeneration === expectedControllerGeneration &&
+          selected.targetGeneration === fence.expectedTargetGeneration &&
+          (selected.documentGeneration === fence.expectedDocumentGeneration ||
+            selected.documentGeneration === resultDocumentGeneration)
+        );
+      };
+      const canProjectResult = () =>
+        isCurrentResultView() && resultOrder >= actionResultOrderRef.current.settled;
+      const settleResult = () => {
+        if (!canProjectResult()) return false;
+        actionResultOrderRef.current.settled = resultOrder;
+        invalidateRefresh();
+        return true;
+      };
       try {
         const receipt = await client.actInBrowser(workspaceId, browserSessionId, {
           operationId,
           ...fence,
-          observationMode: "none",
+          observationMode,
           action,
         });
-        if (receipt.observation) {
+        resultDocumentGeneration =
+          receipt.observation?.target.documentGeneration ?? fence.expectedDocumentGeneration;
+        const settled =
+          receipt.state === "completed" ||
+          receipt.state === "failed" ||
+          receipt.state === "outcome_unknown";
+        // Keep the operation result available to its caller, but an older
+        // delivery cannot replace a newer settled view or input failure.
+        if (!canProjectResult() || (settled && !settleResult())) return receipt;
+        const receivedObservation = receipt.observation;
+        const selectedTarget = selectedTargetRef.current;
+        let projectedObservation: BrowserObservation | null = null;
+        if (
+          settled &&
+          receivedObservation &&
+          canProjectResult() &&
+          receipt.browserSessionId === browserSessionId &&
+          receipt.controllerGeneration === expectedControllerGeneration &&
+          receipt.targetId === fence.targetId &&
+          observationRef.current.browserSessionId === browserSessionId &&
+          receivedObservation.browserSessionId === browserSessionId &&
+          selectedTarget?.browserSessionId === browserSessionId &&
+          selectedTarget.id === fence.targetId &&
+          receivedObservation.target.id === fence.targetId &&
+          selectedTarget.controllerGeneration === expectedControllerGeneration &&
+          receivedObservation.target.controllerGeneration === expectedControllerGeneration &&
+          selectedTarget.targetGeneration === fence.expectedTargetGeneration &&
+          receivedObservation.target.targetGeneration === fence.expectedTargetGeneration &&
+          (selectedTarget.documentGeneration === fence.expectedDocumentGeneration ||
+            selectedTarget.documentGeneration === receivedObservation.target.documentGeneration)
+        ) {
+          // A receipt updates its own selected page only. Its operation outcome
+          // remains available even when the human has moved to another page.
+          projectedObservation = receivedObservation;
           observationRef.current = {
             browserSessionId,
-            observation: receipt.observation,
+            observation: receivedObservation,
           };
-          setState((current) =>
-            current.browserSessionId === browserSessionId
-              ? {
-                  ...current,
-                  observation: receipt.observation,
-                  targets: replaceTarget(current.targets, receipt.observation!.target),
-                }
-              : current,
-          );
+          selectedTargetRef.current = receivedObservation.target;
+          lastObservationAtRef.current = Date.now();
         }
+        setState((current) =>
+          isCurrentResultView() &&
+          current.source === source &&
+          current.browserSessionId === browserSessionId &&
+          current.actionResultOrder <= resultOrder
+            ? {
+                ...current,
+                actionResultOrder: settled ? resultOrder : current.actionResultOrder,
+                error: receipt.state === "completed" ? null : current.error,
+                inputFailure:
+                  receipt.state === "completed"
+                    ? current.inputFailure
+                    : {
+                        operationId: receipt.operationId,
+                        state: receipt.state,
+                        error: receipt.error,
+                      },
+                ...(projectedObservation
+                  ? {
+                      observation: projectedObservation,
+                      targets: replaceTarget(current.targets, projectedObservation.target),
+                    }
+                  : {}),
+              }
+            : current,
+        );
         return receipt;
       } catch (cause) {
         const error = cause instanceof Error ? cause : new Error(String(cause));
-        setState((current) =>
-          current.browserSessionId === browserSessionId ? { ...current, error } : current,
-        );
+        if (settleResult()) {
+          setState((current) =>
+            isCurrentResultView() &&
+            current.source === source &&
+            current.browserSessionId === browserSessionId &&
+            current.actionResultOrder <= resultOrder
+              ? { ...current, error, actionResultOrder: resultOrder }
+              : current,
+          );
+        }
         throw error;
       }
     },
-    [browserSessionId, client, workspaceId],
+    [browserSessionId, client, enabled, invalidateRefresh, isCurrentSource, source, workspaceId],
   );
 
   const act = useCallback(
@@ -457,14 +871,53 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
   const actFromFrame = useCallback(
     async (
       action: BrowserAction | BrowserActionBatch,
-      frame: BrowserFrame,
+      frame: BrowserFrameInputFence,
       operationId: string = crypto.randomUUID(),
-    ): Promise<BrowserActionReceipt> => await dispatchAction(action, operationId, frame),
+      observationMode: "none" | "input" = "none",
+    ): Promise<BrowserActionReceipt> =>
+      await dispatchAction(action, operationId, frame, observationMode),
+    [dispatchAction],
+  );
+
+  const observeForInput = useCallback(async (): Promise<BrowserObservation> => {
+    const target = selectedTargetRef.current;
+    if (!enabled || !isCurrentSource()) {
+      throw new Error("The browser source is no longer selected.");
+    }
+    if (!browserSessionId || !target) throw new Error("No browser tab is selected.");
+    const observation = await client.observeBrowserTarget(workspaceId, browserSessionId, target.id);
+    if (
+      !isCurrentSource() ||
+      observation.browserSessionId !== browserSessionId ||
+      !sameObservationTarget(observation, selectedTargetRef.current)
+    ) {
+      throw new Error("The browser page changed. Open the options again.");
+    }
+    return observation;
+  }, [browserSessionId, client, enabled, isCurrentSource, workspaceId]);
+
+  const actFromObservation = useCallback(
+    async (action: BrowserAction, observation: BrowserObservation) => {
+      if (!sameObservationTarget(observation, selectedTargetRef.current)) {
+        throw new Error("The browser page changed. Open the options again.");
+      }
+      return await dispatchAction(action, crypto.randomUUID(), {
+        browserSessionId: observation.browserSessionId,
+        controllerGeneration: observation.target.controllerGeneration,
+        targetId: observation.target.id,
+        targetGeneration: observation.target.targetGeneration,
+        documentGeneration: observation.target.documentGeneration,
+        frameId: observation.frameId,
+      });
+    },
     [dispatchAction],
   );
 
   const diagnostics = useCallback(
     async (diagnosticOptions: BrowserDiagnosticsOptions = {}): Promise<BrowserDiagnosticBatch> => {
+      if (!enabled || !isCurrentSource()) {
+        throw new Error("The browser source is no longer selected.");
+      }
       const targetId = selectedTargetIdRef.current;
       if (!browserSessionId || !targetId) {
         throw new Error("No browser tab is selected.");
@@ -476,17 +929,20 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         diagnosticOptions,
       );
     },
-    [browserSessionId, client, workspaceId],
+    [browserSessionId, client, enabled, isCurrentSource, workspaceId],
   );
 
   const readClipboard = useCallback(async (): Promise<BrowserClipboard> => {
+    if (!enabled || !isCurrentSource()) {
+      throw new Error("The browser source is no longer selected.");
+    }
     if (!browserSessionId) throw new Error("No BrowserSession is selected.");
     const clipboard = await client.readBrowserClipboard(workspaceId, browserSessionId);
-    if (clipboard.browserSessionId !== browserSessionId) {
+    if (!isCurrentSource() || clipboard.browserSessionId !== browserSessionId) {
       throw new Error("Browser clipboard belongs to another BrowserSession.");
     }
     return clipboard;
-  }, [browserSessionId, client, workspaceId]);
+  }, [browserSessionId, client, enabled, isCurrentSource, workspaceId]);
 
   return {
     session: visible.session,
@@ -497,7 +953,10 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     loading: visible.loading,
     mutating: visible.mutating,
     error: visible.error,
+    inputFailure: visible.inputFailure,
     refresh,
+    observeForInput,
+    actFromObservation,
     selectTarget,
     openTarget,
     closeTarget,
@@ -518,6 +977,8 @@ function emptyState(browserSessionId: string | null, loading: boolean) {
     loading,
     mutating: false,
     error: null as Error | null,
+    inputFailure: null as BrowserInputFailure | null,
+    actionResultOrder: 0,
   };
 }
 
@@ -540,6 +1001,20 @@ function replaceTarget(targets: readonly BrowserTarget[], target: BrowserTarget)
   return next.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
 }
 
+function sameObservationTarget(
+  observation: BrowserObservation,
+  target: BrowserTarget | null,
+): boolean {
+  return (
+    target !== null &&
+    observation.browserSessionId === target.browserSessionId &&
+    observation.target.id === target.id &&
+    observation.target.controllerGeneration === target.controllerGeneration &&
+    observation.target.targetGeneration === target.targetGeneration &&
+    observation.target.documentGeneration === target.documentGeneration
+  );
+}
+
 function isMissingBrowserTarget(error: unknown): boolean {
   return error instanceof OpenGeniApiError && error.code === "target_not_found";
 }