@omercnet/paseo-shared-browser 1.2.1 → 1.2.2-next.237.1

package/client/browser-auto-capture-density.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { getAutomaticCaptureDensity } from "./browser-auto-capture-density";
+
+describe("automatic capture density", () => {
+  it("sharpens the reported phone layout without enlarging CSS dimensions", () => {
+    const viewport = { width: 411, height: 653 };
+    expect(getAutomaticCaptureDensity(viewport, viewport, 3, "fit")).toBe(2);
+    expect(getAutomaticCaptureDensity(viewport, viewport, 1, "fit")).toBe(1);
+  });
+
+  it("accounts for both high DPI screens and enlarged low DPI presentations", () => {
+    const viewport = { width: 800, height: 600 };
+    expect(getAutomaticCaptureDensity(viewport, viewport, 1.5, "fit")).toBe(2);
+    expect(getAutomaticCaptureDensity(viewport, { width: 1200, height: 900 }, 1, "fit")).toBe(2);
+  });
+
+  it("does not double density for fractional layout rounding alone", () => {
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 411, height: 653 },
+        { width: 411.1, height: 653.1 },
+        1,
+        "fit",
+      ),
+    ).toBe(1);
+  });
+
+  it("avoids unnecessary density when a large page is shrunk on a phone", () => {
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 1920, height: 1080 },
+        { width: 411, height: 653 },
+        3,
+        "fit",
+      ),
+    ).toBe(1);
+  });
+
+  it("uses the contained frame rather than letterboxed container height", () => {
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 1000, height: 500 },
+        { width: 400, height: 2000 },
+        2,
+        "fit",
+      ),
+    ).toBe(1);
+  });
+
+  it("uses CSS dimensions for Actual size even when the panel clips the page", () => {
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 1280, height: 800 },
+        { width: 400, height: 600 },
+        2,
+        "actual",
+      ),
+    ).toBe(2);
+  });
+
+  it("reduces density at the physical capture limit without substituting a layout size", () => {
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 1920, height: 1920 },
+        { width: 1920, height: 1920 },
+        3,
+        "fit",
+      ),
+    ).toBe(2);
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 1921, height: 700 },
+        { width: 1921, height: 700 },
+        3,
+        "fit",
+      ),
+    ).toBe(1);
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 3840, height: 3840 },
+        { width: 3840, height: 3840 },
+        3,
+        "fit",
+      ),
+    ).toBe(1);
+    expect(
+      getAutomaticCaptureDensity(
+        { width: 3841, height: 700 },
+        { width: 3841, height: 700 },
+        3,
+        "fit",
+      ),
+    ).toBeNull();
+  });
+
+  it("waits for usable geometry and screen metrics", () => {
+    const size = { width: 411, height: 653 };
+    expect(getAutomaticCaptureDensity(size, { width: 0, height: 0 }, 3, "fit")).toBeNull();
+    expect(getAutomaticCaptureDensity(size, size, Number.NaN, "fit")).toBeNull();
+    expect(getAutomaticCaptureDensity(size, size, 0, "fit")).toBeNull();
+  });
+});

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

@@ -0,0 +1,30 @@
+/** Select capture detail from actual displayed size, independently of page layout. */
+import { type CaptureDensity, canUseCaptureDensity } from "../shared/capture-density";
+import { type BrowserCanvasDisplayMode, getBrowserCanvasLayout } from "./browser-canvas-layout";
+
+export type CaptureDensityMode = "auto" | CaptureDensity;
+
+/**
+ * Choose the smallest supported density that covers the display's physical
+ * pixels, or the highest available density when 2x cannot fully cover them.
+ * Fit accounts for letterboxing; Actual uses CSS size even when clipped.
+ * Unmeasured geometry returns null so it cannot trigger speculative writes.
+ */
+export function getAutomaticCaptureDensity(
+  viewport: { width: number; height: number },
+  container: { width: number; height: number },
+  pixelRatio: number,
+  mode: BrowserCanvasDisplayMode,
+): CaptureDensity | null {
+  if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) return null;
+  const layout = getBrowserCanvasLayout(container, viewport, viewport, mode);
+  if (!layout) return null;
+  const requiredDensity =
+    Math.max(layout.frameRect.width / viewport.width, layout.frameRect.height / viewport.height) *
+    pixelRatio;
+  // Fractional panel measurements can differ from rounded CSS layout by one
+  // physical pixel. That alone should not double source resolution on a 1x screen.
+  const roundingTolerance = 1 / Math.max(viewport.width, viewport.height);
+  if (requiredDensity > 1 + roundingTolerance && canUseCaptureDensity(viewport, 2)) return 2;
+  return canUseCaptureDensity(viewport, 1) ? 1 : null;
+}

package/client/browser-canvas-input.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from "vitest";
+import type { BrowserGestureEvent } from "../shared/browser";
+import { createBrowserCanvasInput } from "./browser-canvas-input";
+
+const point = { x: 40, y: 20, width: 400, height: 300 };
+function fixture() {
+  const events: BrowserGestureEvent[] = [];
+  let ended = 0;
+  const input = createBrowserCanvasInput({
+    enabled: () => true,
+    viewport: () => ({ width: 800, height: 600 }),
+    enqueue: (event) => {
+      events.push(event);
+      return true;
+    },
+    finish: () => {
+      ended += 1;
+    },
+    cancel: () => {},
+    onPoint: () => {},
+    onActivity: () => {},
+  });
+  return { input, events, ended: () => ended };
+}
+
+describe("natural canvas input", () => {
+  it("quarantines a refused touch start until all physical contacts are released", () => {
+    const enqueue = vi.fn().mockReturnValueOnce(false).mockReturnValue(true);
+    const activity = vi.fn();
+    const cancel = vi.fn();
+    const input = createBrowserCanvasInput({
+      enabled: () => true,
+      viewport: () => ({ width: 800, height: 600 }),
+      enqueue,
+      finish: vi.fn(),
+      cancel,
+      onPoint: vi.fn(),
+      onActivity: activity,
+    });
+    const first = { ...point, id: 7 };
+    const second = { ...point, id: 9 };
+    expect(input.touch("start", [first])).toBe(false);
+    expect(input.isTouchQuarantined()).toBe(true);
+    expect(activity).not.toHaveBeenCalledWith(true);
+    // A fresh decoded frame must not turn this held contact into an orphan move.
+    input.touch("move", [{ ...first, x: 60 }]);
+    input.touch("start", [first, second]);
+    input.touch("end", [second]);
+    expect(enqueue).toHaveBeenCalledTimes(1);
+    input.touch("end", []);
+    expect(input.isTouchQuarantined()).toBe(false);
+    expect(input.touch("start", [first])).toBe(true);
+    expect(enqueue).toHaveBeenLastCalledWith({ kind: "touch", type: "start", points: [first] });
+    expect(cancel).toHaveBeenCalledOnce();
+  });
+
+  it("does not restore held touch state after a synchronous queue failure resets the model", () => {
+    const events: BrowserGestureEvent[] = [];
+    let reject = false;
+    const input = createBrowserCanvasInput({
+      enabled: () => true,
+      viewport: () => ({ width: 800, height: 600 }),
+      enqueue: (event) => {
+        events.push(event);
+        if (reject) {
+          input.reset();
+          return false;
+        }
+        return true;
+      },
+      finish: vi.fn(),
+      cancel: vi.fn(),
+      onPoint: vi.fn(),
+      onActivity: vi.fn(),
+    });
+    const first = { ...point, id: 7 };
+    input.touch("start", [first]);
+    reject = true;
+    expect(input.touch("move", [{ ...first, x: 60 }])).toBe(false);
+    expect(input.isTouchQuarantined()).toBe(true);
+    reject = false;
+    input.touch("move", [{ ...first, x: 100 }]);
+    expect(events).toHaveLength(2);
+    input.touch("end", []);
+    input.touch("start", [first]);
+    expect(events.at(-1)).toEqual({ kind: "touch", type: "start", points: [first] });
+  });
+
+  it("allows a new physical touch after a refused final release", () => {
+    const enqueue = vi
+      .fn()
+      .mockReturnValueOnce(true)
+      .mockReturnValueOnce(false)
+      .mockReturnValue(true);
+    const input = createBrowserCanvasInput({
+      enabled: () => true,
+      viewport: () => ({ width: 800, height: 600 }),
+      enqueue,
+      finish: vi.fn(),
+      cancel: vi.fn(),
+      onPoint: vi.fn(),
+      onActivity: vi.fn(),
+    });
+    const contact = { ...point, id: 7 };
+    input.touch("start", [contact]);
+    expect(input.touch("end", [])).toBe(false);
+    expect(input.isTouchQuarantined()).toBe(false);
+    expect(input.touch("start", [contact])).toBe(true);
+    expect(enqueue).toHaveBeenLastCalledWith({ kind: "touch", type: "start", points: [contact] });
+  });
+
+  it("keeps actual right, middle and double-click edges without a mode override", () => {
+    const f = fixture();
+    for (const [button, clickCount] of [
+      ["left", 1],
+      ["left", 2],
+      ["right", 1],
+      ["middle", 1],
+    ] as const) {
+      f.input.mouseDown(point, button, clickCount);
+      f.input.mouseUp(point, button, clickCount);
+    }
+    expect(
+      f.events.map((event) =>
+        event.kind === "down" || event.kind === "up"
+          ? [event.kind, event.button, event.clickCount]
+          : null,
+      ),
+    ).toEqual([
+      ["down", "left", 1],
+      ["up", "left", 1],
+      ["down", "left", 2],
+      ["up", "left", 2],
+      ["down", "right", 1],
+      ["up", "right", 1],
+      ["down", "middle", 1],
+      ["up", "middle", 1],
+    ]);
+  });
+
+  it("forwards held mouse motion before release rather than synthesizing a final drag", () => {
+    const f = fixture();
+    f.input.mouseDown(point, "left", 1);
+    f.input.mouseMove({ ...point, x: 60 });
+    f.input.mouseMove({ ...point, x: 100 });
+    expect(f.ended()).toBe(0);
+    expect(f.events.map((event) => event.kind)).toEqual(["down", "move", "move"]);
+    f.input.mouseUp({ ...point, x: 100 }, "left", 1);
+    expect(f.ended()).toBe(1);
+  });
+
+  it("always forwards genuine touch contacts, including held press and pinch partial release", () => {
+    const f = fixture();
+    const first = { ...point, id: 7 };
+    const second = { ...point, x: 200, id: 9 };
+    f.input.touch("start", [first]);
+    expect(f.events).toEqual([{ kind: "touch", type: "start", points: [first] }]);
+    expect(f.ended()).toBe(0);
+    f.input.touch("start", [first, second]);
+    f.input.touch("move", [
+      { ...first, x: 20 },
+      { ...second, x: 240 },
+    ]);
+    f.input.touch("end", [second]);
+    f.input.touch("end", []);
+    expect(
+      f.events.map((event) =>
+        event.kind === "touch"
+          ? [event.type, event.points.map((contact) => contact.id)]
+          : event.kind,
+      ),
+    ).toEqual([
+      ["start", [7]],
+      ["start", [7, 9]],
+      ["move", [7, 9]],
+      ["move", [9]],
+      ["end", []],
+    ]);
+    expect(f.ended()).toBe(1);
+  });
+});
+
+it("preserves genuine pointer modifier snapshots without fabricating held keys", () => {
+  const f = fixture();
+  f.input.mouseDown(point, "left", 1, 10);
+  f.input.mouseMove(point, 2);
+  f.input.mouseUp(point, "left", 1, 0);
+  f.input.wheel(point, 0, 5000, 4);
+  expect(
+    f.events.slice(0, 3).map((event) => ("modifiers" in event ? event.modifiers : undefined)),
+  ).toEqual([10, 2, 0]);
+  expect(f.events.slice(3).every((event) => event.kind === "scroll" && event.modifiers === 4)).toBe(
+    true,
+  );
+  expect(f.events.some((event) => event.kind === "key")).toBe(false);
+  f.input.mouseMove(point); // Native callers preserve existing held-key inference.
+  expect(f.events.at(-1)).not.toHaveProperty("modifiers");
+});

package/client/browser-canvas-input.ts

@@ -0,0 +1,202 @@
+/**
+ * Platform-neutral canvas gestures. Coordinate mapping belongs to the actual
+ * displayed image rectangle, not capture pixels (including sharp mobile images).
+ * Touch is always genuine multi-touch on every remote preset. Mouse buttons and
+ * click counts come from physical events; surrounding Paseo chrome is untouched.
+ */
+import type { BrowserGestureEvent } from "../shared/browser";
+import type { BrowserGesturePoint, BrowserTouchPoint } from "./browser-input-queue";
+
+export interface CanvasInputOptions {
+  enabled(): boolean;
+  viewport(): { width: number; height: number } | null;
+  enqueue(event: BrowserGestureEvent): boolean;
+  finish(): void;
+  cancel(): void;
+  onPoint(point: BrowserGesturePoint): void;
+  onActivity(active: boolean): void;
+}
+const MAX_SCROLL_DELTA = 4_000;
+
+/** Preserve wheel distance by splitting oversized deltas instead of clipping it. */
+function scroll(
+  options: CanvasInputOptions,
+  point: BrowserGesturePoint,
+  deltaX: number,
+  deltaY: number,
+  modifiers?: number,
+) {
+  let remainingX = deltaX;
+  let remainingY = deltaY;
+  while (Math.abs(remainingX) > 0.001 || Math.abs(remainingY) > 0.001) {
+    const x = Math.max(-MAX_SCROLL_DELTA, Math.min(MAX_SCROLL_DELTA, remainingX));
+    const y = Math.max(-MAX_SCROLL_DELTA, Math.min(MAX_SCROLL_DELTA, remainingY));
+    if (
+      !options.enqueue({
+        kind: "scroll",
+        point,
+        deltaX: x,
+        deltaY: y,
+        ...(modifiers === undefined ? {} : { modifiers }),
+      })
+    )
+      return;
+    remainingX -= x;
+    remainingY -= y;
+  }
+}
+
+/** Consume normalized real pointer/touch events with stable touch identities. */
+export function createBrowserCanvasInput(options: CanvasInputOptions) {
+  const mouseButtons = new Set<"left" | "right" | "middle">();
+  let activeTouchIds = new Set<number>();
+  let touchBlockedUntilRelease = false;
+
+  // Quarantine cancelled held contacts until actual liftoff. A move or added
+  // finger cannot invent a new press on a replacement page or controller.
+  const reset = () => {
+    if (activeTouchIds.size) touchBlockedUntilRelease = true;
+    mouseButtons.clear();
+    activeTouchIds.clear();
+    options.onActivity(false);
+  };
+  const cancel = () => {
+    reset();
+    options.cancel();
+  };
+  const mouseMove = (point: BrowserGesturePoint, modifiers?: number) => {
+    if (!options.enabled()) return false;
+    options.onPoint(point);
+    if (!mouseButtons.size) options.onActivity(false);
+    return options.enqueue({
+      kind: "move",
+      point,
+      ...(modifiers === undefined ? {} : { modifiers }),
+    });
+  };
+  const mouseDown = (
+    point: BrowserGesturePoint,
+    button: "left" | "right" | "middle",
+    clickCount: 1 | 2,
+    modifiers?: number,
+  ) => {
+    if (!options.enabled()) return false;
+    options.onPoint(point);
+    const accepted = options.enqueue({
+      kind: "down",
+      point,
+      button,
+      clickCount,
+      ...(modifiers === undefined ? {} : { modifiers }),
+    });
+    if (accepted) {
+      mouseButtons.add(button);
+      options.onActivity(true);
+    }
+    return accepted;
+  };
+  const mouseUp = (
+    point: BrowserGesturePoint,
+    button: "left" | "right" | "middle",
+    clickCount: 1 | 2,
+    modifiers?: number,
+  ) => {
+    if (!mouseButtons.has(button)) return false;
+    options.onPoint(point);
+    const accepted = options.enqueue({
+      kind: "up",
+      point,
+      button,
+      clickCount,
+      ...(modifiers === undefined ? {} : { modifiers }),
+    });
+    mouseButtons.delete(button);
+    if (!mouseButtons.size) {
+      options.onActivity(false);
+      options.finish();
+    }
+    return accepted;
+  };
+  const wheel = (
+    point: BrowserGesturePoint,
+    deltaX: number,
+    deltaY: number,
+    modifiers?: number,
+  ) => {
+    if (!options.enabled()) return false;
+    const viewport = options.viewport();
+    if (!viewport) return false;
+    options.onPoint(point);
+    options.onActivity(true);
+    scroll(
+      options,
+      point,
+      (deltaX * viewport.width) / point.width,
+      (deltaY * viewport.height) / point.height,
+      modifiers,
+    );
+    return true;
+  };
+
+  const touch = (phase: "start" | "move" | "end" | "cancel", points: BrowserTouchPoint[]) => {
+    if (phase === "cancel") {
+      cancel();
+      // Native touchCancel terminates the physical contact session itself.
+      touchBlockedUntilRelease = false;
+      return true;
+    }
+    if (touchBlockedUntilRelease) {
+      if (points.length === 0) touchBlockedUntilRelease = false;
+      return true;
+    }
+    if (!activeTouchIds.size && phase !== "start") return true;
+    if (!options.enabled()) {
+      cancel();
+      touchBlockedUntilRelease = points.length > 0;
+      return false;
+    }
+    if (points.length > 5 || new Set(points.map((point) => point.id)).size !== points.length) {
+      cancel();
+      return false;
+    }
+    const hasNewPoint = points.some((point) => !activeTouchIds.has(point.id));
+    if (hasNewPoint && phase !== "start") {
+      cancel();
+      return true;
+    }
+    const type = points.length === 0 ? "end" : hasNewPoint ? "start" : "move";
+    if (points.length === 0 && activeTouchIds.size === 0) return false;
+    const accepted = options.enqueue({ kind: "touch", type, points });
+    if (!accepted) {
+      // An unavailable decoded frame or synchronous queue failure did not admit
+      // these contacts. Never let a later move invent their missing start, or
+      // overwrite a reset performed by the queue's error callback.
+      cancel();
+      touchBlockedUntilRelease = points.length > 0;
+      return false;
+    }
+    activeTouchIds = new Set(points.map((point) => point.id));
+    options.onActivity(points.length > 0);
+    if (points.length === 0) options.finish();
+    if (points[0]) options.onPoint(points[0]);
+    return accepted;
+  };
+
+  return {
+    mouseMove,
+    mouseDown,
+    mouseUp,
+    wheel,
+    touch,
+    cancel,
+    reset,
+    isHoldingMouse: () => mouseButtons.size > 0,
+    isTouchQuarantined: () => touchBlockedUntilRelease,
+    leave: () => {
+      if (!mouseButtons.size && !activeTouchIds.size) {
+        options.enqueue({ kind: "leave" });
+        options.finish();
+      }
+    },
+  };
+}

package/client/browser-canvas-keyboard-web.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import type { CanvasKeyboardEvent } from "./browser-canvas-keyboard";
+import { bindBrowserCanvasKeyboard, type KeyboardCanvasNode } from "./browser-canvas-keyboard-web";
+
+type Listener = (event: never) => void;
+
+/** Minimal DOM: only listener registration and focus, enough to drive the real adapter. */
+function fakeDom() {
+  const registry = new Map<string, Set<Listener>>();
+  const target = (name: string) => ({
+    add(type: string, listener: Listener) {
+      const key = `${name}:${type}`;
+      registry.set(key, (registry.get(key) ?? new Set()).add(listener));
+    },
+    remove(type: string, listener: Listener) {
+      registry.get(`${name}:${type}`)?.delete(listener);
+    },
+  });
+  const nodeTarget = target("node");
+  const sinkTarget = target("sink");
+  const docTarget = target("doc");
+  const winTarget = target("win");
+  const document = {
+    activeElement: null as unknown,
+    hidden: false,
+    createElement: () => sink,
+    addEventListener: docTarget.add,
+    removeEventListener: docTarget.remove,
+    defaultView: { addEventListener: winTarget.add, removeEventListener: winTarget.remove },
+  };
+  const sink = {
+    tabIndex: 0,
+    value: "",
+    style: {},
+    setAttribute() {},
+    focus() {
+      document.activeElement = sink;
+    },
+    remove() {},
+    addEventListener: sinkTarget.add,
+    removeEventListener: sinkTarget.remove,
+  };
+  const node = {
+    ...sink,
+    appendChild() {},
+    ownerDocument: document,
+    addEventListener: nodeTarget.add,
+    removeEventListener: nodeTarget.remove,
+  } as unknown as KeyboardCanvasNode;
+  sink.focus();
+  const fire = (name: string, type: string, event: object = {}) => {
+    for (const listener of registry.get(`${name}:${type}`) ?? [])
+      (listener as (event: object) => void)({
+        preventDefault() {},
+        stopPropagation() {},
+        ...event,
+      });
+  };
+  return { node, document, fire };
+}
+
+const key = {
+  key: "a",
+  code: "KeyA",
+  altKey: false,
+  ctrlKey: false,
+  metaKey: false,
+  shiftKey: false,
+  repeat: false,
+};
+
+function bind() {
+  const dom = fakeDom();
+  const events: CanvasKeyboardEvent[] = [];
+  let cancels = 0;
+  const binding = bindBrowserCanvasKeyboard(dom.node, {
+    enabled: () => true,
+    enqueue: (event) => {
+      events.push(event);
+      return true;
+    },
+    finish: () => {},
+    cancel: () => {
+      cancels += 1;
+    },
+    onError: () => {},
+  });
+  return { ...dom, events, binding, cancels: () => cancels };
+}
+
+describe("web canvas keyboard adapter cancellation", () => {
+  it.each([
+    ["sink blur", (dom: ReturnType<typeof bind>) => dom.fire("sink", "blur")],
+    ["window blur", (dom: ReturnType<typeof bind>) => dom.fire("win", "blur")],
+    [
+      "page hidden",
+      (dom: ReturnType<typeof bind>) => {
+        dom.document.hidden = true;
+        dom.fire("doc", "visibilitychange");
+      },
+    ],
+  ])("%s cancels the held key and drops its late release", (_name, lose) => {
+    const dom = bind();
+    dom.fire("sink", "keydown", key);
+    expect(dom.events.map((event) => event.kind)).toEqual(["key"]);
+    lose(dom);
+    expect(dom.cancels()).toBe(1);
+    dom.document.hidden = false;
+    dom.fire("doc", "keyup", key);
+    dom.fire("sink", "keydown", { ...key, repeat: true });
+    expect(dom.events).toHaveLength(1);
+  });
+});