@omercnet/paseo-shared-browser 1.2.2 → 2.0.0

package/client/use-browser-capture-density.ts

@@ -0,0 +1,87 @@
+/** Density writes reuse controller snapshots and mutation settlement without preset substitution.
+ * The latest callback authority is checked before publication, and pending writes
+ * are never retried. A settings change preserves page/CSS/mode at the server seam.
+ */
+import { useMutation } from "@tanstack/react-query";
+import { useEffect, useRef } from "react";
+import {
+  type BrowserState,
+  type CaptureDensity,
+  canUseCaptureDensity,
+  type setCaptureDensityRpc,
+} from "../shared/browser";
+
+type Request = ReturnType<typeof setCaptureDensityRpc.input.parse>;
+interface Options {
+  identity: string;
+  current(): {
+    state: BrowserState;
+    context: Omit<Request, "density">;
+  } | null;
+  change(input: Request): Promise<{ state: BrowserState }>;
+  beforeChange(): void;
+  onSuccess(state: BrowserState): void;
+  onError(error: unknown): void;
+}
+
+/** Retained menu callbacks recheck the current controller and actual CSS size before sending. */
+export function useBrowserCaptureDensity(options: Options) {
+  const latest = useRef(options);
+  latest.current = options;
+  const active = useRef(false);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const isCurrent = (request: { input: Request; identity: string }) => {
+    const current = latest.current.current();
+    return (
+      mounted.current &&
+      request.identity === latest.current.identity &&
+      current !== null &&
+      current.state.controller === "self" &&
+      current.context.viewerToken === request.input.viewerToken &&
+      current.context.controlToken === request.input.controlToken &&
+      current.context.expected.sessionId === request.input.expected.sessionId &&
+      current.context.expected.runtimeId === request.input.expected.runtimeId &&
+      current.context.expected.bridgeEpoch === request.input.expected.bridgeEpoch
+    );
+  };
+  const mutation = useMutation({
+    mutationFn: (request: { input: Request; identity: string }) => options.change(request.input),
+    retry: false,
+    onSuccess: (result, request) => {
+      if (isCurrent(request)) latest.current.onSuccess(result.state);
+    },
+    onError: (error, request) => {
+      if (isCurrent(request)) latest.current.onError(error);
+    },
+    onSettled: () => {
+      active.current = false;
+    },
+  });
+  return {
+    pending: mutation.isPending,
+    select(density: CaptureDensity) {
+      const current = latest.current.current();
+      if (
+        !mounted.current ||
+        latest.current.identity !== options.identity ||
+        active.current ||
+        !current ||
+        current.state.controller !== "self" ||
+        current.state.status !== "ready" ||
+        !canUseCaptureDensity(current.state.viewport, density) ||
+        current.state.captureScale === density
+      ) {
+        return;
+      }
+      active.current = true;
+      latest.current.beforeChange();
+      mutation.mutate({ input: { ...current.context, density }, identity: options.identity });
+    },
+  };
+}

package/client/use-browser-emulation-mode.ts

@@ -0,0 +1,56 @@
+/** Apply the local device default only after this viewer first owns the shared browser. */
+import { useEffect, useRef } from "react";
+import type { BrowserState } from "../shared/browser";
+import {
+  createEmulationChoices,
+  type EmulationSelection,
+  readLocalDevice,
+  selectionMode,
+} from "./browser-emulation-mode";
+
+interface ModeOptions {
+  identity: string;
+  platform: "ios" | "android" | "web";
+  state: BrowserState | null;
+  canControl: boolean;
+  pending: boolean;
+  apply(selection: EmulationSelection): void;
+}
+
+/** Observers never mutate emulation; failed changes remain explicit errors and are not retried. */
+export function useBrowserEmulationMode(options: ModeOptions) {
+  const owned = useRef({
+    identity: options.identity,
+    choices: createEmulationChoices(readLocalDevice(options.platform)),
+  });
+  if (owned.current.identity !== options.identity) {
+    owned.current = {
+      identity: options.identity,
+      choices: createEmulationChoices(readLocalDevice(options.platform)),
+    };
+  }
+  const choices = owned.current.choices;
+  const presetId = options.state?.devicePresetId ?? null;
+  const mode = selectionMode(presetId);
+  useEffect(() => {
+    if (options.state) choices.remember(presetId);
+  }, [choices, presetId, Boolean(options.state)]);
+  useEffect(() => {
+    if (!options.canControl || options.pending || options.state?.status !== "ready") return;
+    const selection = choices.claimDefault(mode);
+    if (selection) options.apply(selection);
+  }, [choices, mode, options.canControl, options.pending, options.state?.status, options.apply]);
+  return {
+    mode,
+    toggle: () => {
+      if (
+        owned.current.choices !== choices ||
+        !options.canControl ||
+        options.pending ||
+        options.state?.status !== "ready"
+      )
+        return;
+      options.apply(choices.toggle(mode));
+    },
+  };
+}

package/client/use-browser-fill-viewport.test.ts

@@ -0,0 +1,108 @@
+/** Exercise debounce and cancellation with the repository's lightweight hook harness. */
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+const fixture = vi.hoisted(() => ({
+  ref: null as { current: unknown } | null,
+  dependencies: null as unknown[] | null,
+  cleanup: null as (() => void) | null,
+  deferEffects: false,
+}));
+
+vi.mock("react", () => ({
+  useRef(value: unknown) {
+    fixture.ref ??= { current: value };
+    return fixture.ref;
+  },
+  useEffect(operation: () => (() => void) | undefined, dependencies: unknown[]) {
+    if (fixture.deferEffects) return;
+    if (
+      fixture.dependencies &&
+      dependencies.every((value, index) => Object.is(value, fixture.dependencies?.[index]))
+    ) {
+      return;
+    }
+    fixture.cleanup?.();
+    fixture.dependencies = dependencies;
+    fixture.cleanup = operation() ?? null;
+  },
+}));
+
+import { useBrowserFillViewport } from "./use-browser-fill-viewport";
+
+const apply = vi.fn();
+const defaults = {
+  identity: "host/workspace/viewer/control",
+  enabled: true,
+  canResize: true,
+  target: { width: 1000, height: 700 },
+  viewport: { width: 1280, height: 720 },
+  apply,
+};
+
+beforeEach(() => {
+  fixture.ref = null;
+  fixture.dependencies = null;
+  fixture.cleanup = null;
+  fixture.deferEffects = false;
+  vi.clearAllMocks();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  fixture.cleanup?.();
+  vi.useRealTimers();
+});
+
+it("coalesces rapid panel changes into one resize using the latest action", () => {
+  useBrowserFillViewport(defaults);
+  vi.advanceTimersByTime(100);
+  const latest = vi.fn();
+  useBrowserFillViewport({ ...defaults, target: { width: 900, height: 600 }, apply: latest });
+  vi.advanceTimersByTime(199);
+  expect(latest).not.toHaveBeenCalled();
+  vi.advanceTimersByTime(1);
+  expect(latest).toHaveBeenCalledOnce();
+  expect(apply).not.toHaveBeenCalled();
+});
+
+it("cancels queued work when control is released, a mutation starts, or following stops", () => {
+  for (const override of [{ canResize: false }, { enabled: false }, { target: null }]) {
+    useBrowserFillViewport(defaults);
+    vi.advanceTimersByTime(100);
+    useBrowserFillViewport({ ...defaults, ...override });
+    vi.advanceTimersByTime(300);
+    expect(apply).not.toHaveBeenCalled();
+  }
+});
+
+it("resumes after control returns without repeatedly resizing an acknowledged resolution", () => {
+  useBrowserFillViewport({ ...defaults, canResize: false });
+  vi.advanceTimersByTime(500);
+  expect(apply).not.toHaveBeenCalled();
+  useBrowserFillViewport(defaults);
+  vi.advanceTimersByTime(200);
+  expect(apply).toHaveBeenCalledOnce();
+  useBrowserFillViewport({ ...defaults, viewport: defaults.target });
+  vi.advanceTimersByTime(500);
+  expect(apply).toHaveBeenCalledOnce();
+});
+
+it("cancels work when moving to another workspace or unmounting", () => {
+  useBrowserFillViewport(defaults);
+  vi.advanceTimersByTime(100);
+  useBrowserFillViewport({ ...defaults, identity: "other/workspace", enabled: false });
+  vi.advanceTimersByTime(300);
+  expect(apply).not.toHaveBeenCalled();
+  useBrowserFillViewport(defaults);
+  fixture.cleanup?.();
+  vi.advanceTimersByTime(300);
+  expect(apply).not.toHaveBeenCalled();
+});
+
+it("rechecks render-time authority before effect cleanup can cancel a queued resize", () => {
+  useBrowserFillViewport(defaults);
+  fixture.deferEffects = true;
+  useBrowserFillViewport({ ...defaults, identity: "other/workspace", canResize: false });
+  vi.advanceTimersByTime(200);
+  expect(apply).not.toHaveBeenCalled();
+});

package/client/use-browser-fill-viewport.ts

@@ -0,0 +1,62 @@
+/** Follow local panel geometry only while this viewer owns the shared browser. */
+import { useEffect, useRef } from "react";
+
+interface FillViewportOptions {
+  identity: string;
+  enabled: boolean;
+  canResize: boolean;
+  target: { width: number; height: number } | null;
+  viewport: { width: number; height: number } | null;
+  apply(): void;
+}
+
+/**
+ * Coalesce layout changes and cancel scheduled work on authority, scope, or mode
+ * changes. Unsupported sizes pause following; RPC failures are handled by the
+ * caller, which disables the mode rather than retrying indefinitely.
+ */
+export function useBrowserFillViewport(options: FillViewportOptions): void {
+  const latest = useRef(options);
+  latest.current = options;
+  const width = options.target?.width;
+  const height = options.target?.height;
+  const viewportWidth = options.viewport?.width;
+  const viewportHeight = options.viewport?.height;
+
+  useEffect(() => {
+    if (
+      !options.enabled ||
+      !options.canResize ||
+      width === undefined ||
+      height === undefined ||
+      (width === viewportWidth && height === viewportHeight)
+    ) {
+      return;
+    }
+
+    const identity = options.identity;
+    const timer = setTimeout(() => {
+      // Recheck render-time authority even if effect cleanup has not run yet.
+      const current = latest.current;
+      if (
+        current.identity === identity &&
+        current.enabled &&
+        current.canResize &&
+        current.target?.width === width &&
+        current.target?.height === height &&
+        (current.viewport?.width !== width || current.viewport?.height !== height)
+      ) {
+        current.apply();
+      }
+    }, 200);
+    return () => clearTimeout(timer);
+  }, [
+    options.identity,
+    options.enabled,
+    options.canResize,
+    width,
+    height,
+    viewportWidth,
+    viewportHeight,
+  ]);
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Connects native Image decode callbacks to the bounded handoff model. The
+ * visible-frame ref is changed in a layout effect, after the image-layer commit,
+ * so transport metadata cannot authorize input against pixels not yet displayed.
+ */
+import { type RefObject, useCallback, useLayoutEffect, useState } from "react";
+import type { BrowserFrame } from "../shared/browser";
+import { createBrowserFrameBuffer, type FrameCandidate } from "./browser-frame-buffer";
+
+/** Bind qualified captures and native callbacks to committed visible input authority. */
+export function useBrowserFrameBuffer(
+  visibleFrameRef: RefObject<BrowserFrame | null>,
+  isCurrent: (candidate: FrameCandidate) => boolean,
+) {
+  const [model] = useState(createBrowserFrameBuffer);
+  const [buffer, setBuffer] = useState(model.snapshot);
+  const frame =
+    buffer.front === null ? null : (buffer.layers[buffer.front]?.candidate.frame ?? null);
+
+  useLayoutEffect(() => {
+    visibleFrameRef.current = frame;
+    return () => {
+      visibleFrameRef.current = null;
+    };
+  }, [frame, visibleFrameRef]);
+
+  const discardObsoletePending = useCallback(() => {
+    const current = model.snapshot();
+    const pending = current.pending === null ? null : current.layers[current.pending];
+    if (pending && !isCurrent(pending.candidate)) {
+      setBuffer(model.invalidatePending());
+    }
+  }, [isCurrent, model]);
+  const reset = useCallback(() => {
+    visibleFrameRef.current = null;
+    setBuffer(model.reset());
+  }, [model, visibleFrameRef]);
+  const receive = useCallback(
+    (candidate: FrameCandidate) => {
+      if (!isCurrent(candidate)) {
+        return;
+      }
+      const current = model.snapshot();
+      const pending = current.pending === null ? null : current.layers[current.pending];
+      if (pending && !isCurrent(pending.candidate)) {
+        model.invalidatePending();
+      }
+      setBuffer(model.offer(candidate));
+    },
+    [isCurrent, model],
+  );
+  const settled = useCallback(
+    (ticket: number, succeeded: boolean) => {
+      const current = model.snapshot();
+      const pending = current.pending === null ? null : current.layers[current.pending];
+      if (!pending || pending.ticket !== ticket || !isCurrent(pending.candidate)) {
+        return false;
+      }
+      setBuffer(model.settle(ticket, succeeded, isCurrent));
+      return true;
+    },
+    [isCurrent, model],
+  );
+
+  return { buffer, frame, receive, settled, discardObsoletePending, reset };
+}

package/client/use-browser-image-capture.ts

@@ -0,0 +1,139 @@
+/**
+ * Own the viewer's JPEG query and refresh scheduling. A current painted video
+ * front owns presentation and viewer renewal, so image polling, focus and input
+ * refresh cannot create redundant screenshots. Clearing video resumes the same
+ * image fallback query; already-published bounded RPCs are never replayed.
+ */
+import type { RpcInput } from "@getpaseo/plugin";
+import { CancelledError, useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef } from "react";
+import type { BrowserFrame, captureBrowserRpc } from "../shared/browser";
+import type { CaptureQuality } from "../shared/capture-settings";
+import { browserCaptureInterval } from "./browser-capture-cadence";
+
+interface ImageCaptureOptions {
+  /** Hidden retained panels keep state but publish no new media requests. */
+  active?: boolean;
+  viewerToken: string | null;
+  quality: CaptureQuality;
+  activeInput: boolean;
+  /** Exact held-video fallback request, zero during normal image playback. */
+  fallbackRevision?: number;
+  videoOwnsPresentation: boolean;
+  /** Read actual current video authority at request/follow-up time, before React commits. */
+  hasVideoPresentation(): boolean;
+  refreshVideo(): void;
+  mutationEpoch(): number;
+  knownFrame(): BrowserFrame | null;
+  capture(
+    input: RpcInput<typeof captureBrowserRpc>,
+  ): Promise<ReturnType<typeof captureBrowserRpc.output.parse>>;
+}
+
+/** Preserve captured query identity/epoch and the existing single-flight fallback refresh. */
+export function useBrowserImageCapture(options: ImageCaptureOptions) {
+  const latest = useRef(options);
+  latest.current = options;
+  const mounted = useRef(true);
+  const inFlight = useRef(false);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const query = useQuery({
+    queryKey: ["shared-browser", "capture", options.viewerToken, options.quality],
+    queryFn: async () => {
+      if (!options.viewerToken) throw new Error("The browser viewer is not attached.");
+      // A timer already queued before video paint must not publish a JPEG RPC.
+      if (
+        !mounted.current ||
+        latest.current.active === false ||
+        latest.current.viewerToken !== options.viewerToken ||
+        latest.current.quality !== options.quality ||
+        latest.current.videoOwnsPresentation ||
+        latest.current.hasVideoPresentation()
+      ) {
+        throw new CancelledError({ silent: true, revert: true });
+      }
+      const mutationEpoch = options.mutationEpoch();
+      const fallbackRevision = latest.current.fallbackRevision ?? 0;
+      inFlight.current = true;
+      try {
+        const result = await options.capture({
+          viewerToken: options.viewerToken,
+          quality: options.quality,
+          // A held-video handoff needs an actual image payload, even when the
+          // underlying JPEG still matches the server's incremental cache.
+          knownFrameId: fallbackRevision ? null : (options.knownFrame()?.frameId ?? null),
+        });
+        return {
+          ...result,
+          mutationEpoch,
+          fallbackRevision,
+          viewerToken: options.viewerToken,
+          captureQuality: options.quality,
+        };
+      } finally {
+        inFlight.current = false;
+      }
+    },
+    enabled:
+      options.active !== false &&
+      Boolean(options.viewerToken) &&
+      !options.videoOwnsPresentation &&
+      !options.hasVideoPresentation(),
+    retry: false,
+    refetchInterval: (query) =>
+      options.active === false || options.videoOwnsPresentation
+        ? false
+        : browserCaptureInterval(query.state.data?.state.status, options.activeInput),
+    refetchIntervalInBackground: false,
+    refetchOnWindowFocus: !options.videoOwnsPresentation,
+    staleTime: 0,
+  });
+
+  const refreshCapture = useCallback(() => {
+    const current = latest.current;
+    if (!mounted.current || current.active === false) return;
+    current.refreshVideo();
+    if (!current.viewerToken || current.videoOwnsPresentation || current.hasVideoPresentation())
+      return;
+    const requestWasInFlight = inFlight.current;
+    const viewerToken = current.viewerToken;
+    const quality = current.quality;
+    const request = query.refetch({ cancelRefetch: false });
+    if (requestWasInFlight) {
+      void request.then(() => {
+        const after = latest.current;
+        if (
+          !mounted.current ||
+          after.active === false ||
+          after.viewerToken !== viewerToken ||
+          after.quality !== quality ||
+          after.videoOwnsPresentation ||
+          after.hasVideoPresentation()
+        )
+          return;
+        void query.refetch({ cancelRefetch: false });
+      });
+    }
+  }, [query.refetch]);
+
+  const retryFrameCapture = useCallback(() => {
+    const current = latest.current;
+    if (
+      mounted.current &&
+      current.active !== false &&
+      current.viewerToken &&
+      !current.videoOwnsPresentation &&
+      !current.hasVideoPresentation()
+    ) {
+      void query.refetch({ cancelRefetch: false });
+    }
+  }, [query.refetch]);
+
+  return { query, refreshCapture, retryFrameCapture };
+}

package/client/use-browser-scoped-mutation.test.ts

@@ -0,0 +1,118 @@
+/** Exercise actual publication/settlement callbacks across render and mount boundaries. */
+import { beforeEach, expect, it, vi } from "vitest";
+
+const fixture = vi.hoisted(() => ({
+  slots: [] as { current: unknown }[],
+  index: 0,
+  cleanup: null as (() => void) | null,
+  options: null as unknown,
+  submissions: [] as unknown[],
+}));
+vi.mock("react", () => ({
+  useRef(value: unknown) {
+    const index = fixture.index++;
+    if (!fixture.slots[index]) fixture.slots[index] = { current: value };
+    return fixture.slots[index];
+  },
+  useLayoutEffect(operation: () => () => void) {
+    if (!fixture.cleanup) fixture.cleanup = operation();
+  },
+}));
+vi.mock("@tanstack/react-query", () => ({
+  useMutation(options: unknown) {
+    fixture.options = options;
+    return { isPending: false, mutate: (request: unknown) => fixture.submissions.push(request) };
+  },
+}));
+
+import { useBrowserScopedMutation } from "./use-browser-scoped-mutation";
+
+const send = vi.fn(async (input: string) => ({ value: input }));
+const success = vi.fn();
+const failure = vi.fn();
+function render(identity = "host/workspace/viewer/control", currentIdentity?: () => string) {
+  fixture.index = 0;
+  const hook = useBrowserScopedMutation({
+    identity,
+    ...(currentIdentity ? { currentIdentity } : {}),
+    mutationFn: send,
+    onSuccess: success,
+    onError: failure,
+  });
+  const options = fixture.options as {
+    mutationFn(request: { input: string; identity: string }): Promise<{ value: string }>;
+    onSuccess(result: { value: string }, request: { input: string; identity: string }): void;
+    onError(error: unknown, request: { input: string; identity: string }): void;
+    retry: boolean;
+  };
+  return { hook, options };
+}
+beforeEach(() => {
+  fixture.slots = [];
+  fixture.index = 0;
+  fixture.cleanup = null;
+  fixture.submissions = [];
+  vi.clearAllMocks();
+});
+it("captures submitted identity, keeps current settlement and never retries", async () => {
+  const { hook, options } = render();
+  hook.mutate("chosen");
+  const request = fixture.submissions[0] as { input: string; identity: string };
+  const result = await options.mutationFn(request);
+  options.onSuccess(result, request);
+  expect(send).toHaveBeenCalledExactlyOnceWith("chosen");
+  expect(success).toHaveBeenCalledExactlyOnceWith(result);
+  expect(options.retry).toBe(false);
+});
+for (const replacement of [
+  "new-host/workspace/viewer/control",
+  "host/new-workspace/viewer/control",
+  "host/workspace/new-viewer/control",
+  "host/workspace/viewer/new-control",
+]) {
+  it(`discards published success and failure after ${replacement}`, async () => {
+    const previous = render();
+    previous.hook.mutate("published");
+    const request = fixture.submissions[0] as { input: string; identity: string };
+    await previous.options.mutationFn(request);
+    const latest = render(replacement);
+    expect(() => latest.options.mutationFn(request)).toThrow("context changed");
+    latest.options.onSuccess({ value: "old" }, request);
+    latest.options.onError(new Error("old"), request);
+    previous.hook.mutate("retained callback");
+    expect(success).not.toHaveBeenCalled();
+    expect(failure).not.toHaveBeenCalled();
+    expect(fixture.submissions).toHaveLength(1);
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+}
+it("refuses stale queued publication and ignores callbacks after unmount", async () => {
+  const { hook, options } = render();
+  hook.mutate("unsent");
+  const request = fixture.submissions[0] as { input: string; identity: string };
+  fixture.cleanup?.();
+  expect(() => options.mutationFn(request)).toThrow("context changed");
+  options.onSuccess({ value: "late" }, request);
+  options.onError(new Error("late"), request);
+  hook.mutate("after unmount");
+  expect(send).not.toHaveBeenCalled();
+  expect(success).not.toHaveBeenCalled();
+  expect(failure).not.toHaveBeenCalled();
+  expect(fixture.submissions).toHaveLength(1);
+});
+
+it("synchronous authority observations revoke settlement before another render", async () => {
+  let observed = "host/workspace/viewer/control";
+  const { hook, options } = render(observed, () => observed);
+  hook.mutate("published");
+  const request = fixture.submissions[0] as { input: string; identity: string };
+  await options.mutationFn(request);
+  observed = "host/workspace/viewer/new-ownership";
+  options.onSuccess({ value: "late" }, request);
+  options.onError(new Error("late"), request);
+  hook.mutate("not yet rendered");
+  expect(success).not.toHaveBeenCalled();
+  expect(failure).not.toHaveBeenCalled();
+  expect(fixture.submissions).toHaveLength(1);
+  expect(send).toHaveBeenCalledTimes(1);
+});