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

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

@@ -0,0 +1,230 @@
+/**
+ * Focused web keyboard/IME bridge. Its invisible editable sink gives the browser
+ * a real composition target without modifying image children. Only controlled
+ * canvas focus consumes host keys; blur releases the original remote channel.
+ * Browser-reserved shortcuts are outside JavaScript's interception guarantees.
+ */
+import {
+  type CanvasKeyboardEvent,
+  type CanvasKeyEnvelope,
+  createBrowserCanvasKeyboard,
+} from "./browser-canvas-keyboard";
+
+interface KeyboardDomEvent extends CanvasKeyEnvelope {
+  data?: string | null;
+  inputType?: string;
+  clipboardData?: { getData(type: string): string } | null;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+interface KeyboardElement {
+  tabIndex: number;
+  value: string;
+  style: Record<string, string>;
+  setAttribute(name: string, value: string): void;
+  focus(options?: { preventScroll: boolean }): void;
+  remove(): void;
+  addEventListener(
+    type: string,
+    listener: (event: KeyboardDomEvent) => void,
+    options?: { capture?: boolean },
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: (event: KeyboardDomEvent) => void,
+    options?: { capture?: boolean },
+  ): void;
+}
+export interface KeyboardCanvasNode extends KeyboardElement {
+  appendChild(child: KeyboardElement): void;
+  ownerDocument: {
+    activeElement: unknown;
+    hidden: boolean;
+    createElement(tag: "textarea"): KeyboardElement;
+    addEventListener(type: string, listener: (event: KeyboardDomEvent) => void): void;
+    removeEventListener(type: string, listener: (event: KeyboardDomEvent) => void): void;
+    defaultView: {
+      addEventListener(type: string, listener: () => void): void;
+      removeEventListener(type: string, listener: () => void): void;
+    } | null;
+  };
+}
+interface BindingOptions {
+  enabled(): boolean;
+  enqueue(event: CanvasKeyboardEvent): boolean;
+  finish(): void;
+  cancel(): void;
+  onError(error: Error): void;
+}
+
+/** DOM-only binding; callers must dispose it and reset on route/control changes. */
+export function bindBrowserCanvasKeyboard(node: KeyboardCanvasNode, options: BindingOptions) {
+  const document = node.ownerDocument;
+  const previousTabIndex = node.tabIndex;
+  const sink = document.createElement("textarea");
+  sink.tabIndex = -1;
+  sink.setAttribute("aria-label", "Type in the shared browser");
+  sink.setAttribute("autocomplete", "off");
+  sink.setAttribute("autocapitalize", "off");
+  sink.setAttribute("spellcheck", "false");
+  Object.assign(sink.style, {
+    position: "absolute",
+    width: "1px",
+    height: "1px",
+    opacity: "0",
+    left: "0",
+    top: "0",
+    padding: "0",
+    border: "0",
+    pointerEvents: "none",
+  });
+  node.tabIndex = 0;
+  node.appendChild(sink);
+  let composing = false;
+  let compositionAdmitted = false;
+  let altTextPending: string | null = null;
+  const focused = () => document.activeElement === sink || document.activeElement === node;
+  const keyboard = createBrowserCanvasKeyboard({
+    ...options,
+    enabled: () => options.enabled() && focused() && !document.hidden,
+  });
+  const consume = (event: KeyboardDomEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+  };
+  const reset = () => {
+    keyboard.reset();
+    compositionAdmitted = false;
+    composing = false;
+    altTextPending = null;
+    sink.value = "";
+  };
+  const cancel = () => {
+    reset();
+    options.cancel();
+  };
+  const focus = () => {
+    if (options.enabled() && !document.hidden) {
+      sink.focus({ preventScroll: true });
+    }
+  };
+  const down = (event: KeyboardDomEvent) => {
+    if (!focused()) {
+      return;
+    }
+    // Local paste supplies clipboard bytes separately. Sending Ctrl/Meta+V would
+    // additionally paste an unrelated remote clipboard and duplicate the action.
+    const pasteShortcut =
+      !event.altKey &&
+      (((event.ctrlKey || event.metaKey) && event.code === "KeyV") ||
+        (event.shiftKey && !event.ctrlKey && !event.metaKey && event.code === "Insert"));
+    if (pasteShortcut) {
+      if (options.enabled()) {
+        event.stopPropagation();
+      }
+      return;
+    }
+    if (keyboard.key("down", event)) {
+      const altPrintable =
+        event.altKey &&
+        !event.ctrlKey &&
+        !event.metaKey &&
+        !event.getModifierState?.("AltGraph") &&
+        Array.from(event.key).length === 1;
+      altTextPending = altPrintable ? event.key : null;
+      if (altTextPending) {
+        // Option layouts can produce text with Alt held. Only the browser's
+        // ensuing insertion event qualifies it; an Alt shortcut may emit none.
+        event.stopPropagation();
+      } else {
+        consume(event);
+      }
+    } else if (options.enabled() && (composing || event.isComposing)) {
+      event.stopPropagation();
+    }
+  };
+  const up = (event: KeyboardDomEvent) => {
+    // Document observes releases after focus loss without consuming Paseo input.
+    if (keyboard.key("up", event) && focused()) {
+      consume(event);
+    }
+    altTextPending = null;
+  };
+  const compositionStart = () => {
+    altTextPending = null;
+    composing = true;
+    compositionAdmitted = options.enabled() && focused() && !document.hidden;
+  };
+  const commitText = (value: string) => {
+    if (value.length > 16_000) {
+      options.onError(new Error("Text is too long. Send up to 16,000 characters at once."));
+      return;
+    }
+    keyboard.text(value);
+  };
+  const compositionEnd = (event: KeyboardDomEvent) => {
+    const accepted = compositionAdmitted && options.enabled() && focused();
+    composing = false;
+    compositionAdmitted = false;
+    if (accepted) {
+      commitText(event.data ?? "");
+    }
+    sink.value = "";
+  };
+  const beforeInput = (event: KeyboardDomEvent) => {
+    if (!composing && options.enabled() && focused()) {
+      consume(event);
+      if (altTextPending && event.inputType === "insertText" && event.data === altTextPending) {
+        commitText(event.data);
+      }
+      altTextPending = null;
+    }
+  };
+  const paste = (event: KeyboardDomEvent) => {
+    if (!options.enabled() || !focused()) {
+      return;
+    }
+    consume(event);
+    altTextPending = null;
+    commitText(event.clipboardData?.getData("text/plain") ?? "");
+    sink.value = "";
+  };
+  const visibility = () => {
+    if (document.hidden) {
+      cancel();
+    }
+  };
+  const listeners: Array<[KeyboardElement, string, (event: KeyboardDomEvent) => void]> = [
+    [node, "pointerdown", focus],
+    [node, "mousedown", focus],
+    [node, "touchstart", focus],
+    [node, "focus", focus],
+    [sink, "keydown", down],
+    [node, "keydown", down],
+    [sink, "compositionstart", compositionStart],
+    [sink, "compositionend", compositionEnd],
+    [sink, "beforeinput", beforeInput],
+    [sink, "paste", paste],
+    [sink, "blur", cancel],
+  ];
+  for (const [element, type, listener] of listeners) {
+    element.addEventListener(type, listener);
+  }
+  document.addEventListener("keyup", up);
+  document.addEventListener("visibilitychange", visibility);
+  document.defaultView?.addEventListener("blur", cancel);
+  return {
+    reset,
+    dispose() {
+      cancel();
+      for (const [element, type, listener] of listeners) {
+        element.removeEventListener(type, listener);
+      }
+      document.removeEventListener("keyup", up);
+      document.removeEventListener("visibilitychange", visibility);
+      document.defaultView?.removeEventListener("blur", cancel);
+      node.tabIndex = previousTabIndex;
+      sink.remove();
+    },
+  };
+}

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

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import {
+  type CanvasKeyboardEvent,
+  type CanvasKeyEnvelope,
+  canvasKeyModifiers,
+  createBrowserCanvasKeyboard,
+} from "./browser-canvas-keyboard";
+
+const envelope = (overrides: Partial<CanvasKeyEnvelope> = {}): CanvasKeyEnvelope => ({
+  key: "a",
+  code: "KeyA",
+  altKey: false,
+  ctrlKey: false,
+  metaKey: false,
+  shiftKey: false,
+  repeat: false,
+  ...overrides,
+});
+function fixture() {
+  const events: CanvasKeyboardEvent[] = [];
+  let enabled = true;
+  let finishes = 0;
+  const input = createBrowserCanvasKeyboard({
+    enabled: () => enabled,
+    enqueue: (event) => {
+      events.push(event);
+      return true;
+    },
+    finish: () => {
+      finishes += 1;
+    },
+  });
+  return {
+    input,
+    events,
+    disable: () => {
+      enabled = false;
+    },
+    enable: () => {
+      enabled = true;
+    },
+    finishes: () => finishes,
+  };
+}
+describe("physical canvas keyboard", () => {
+  it("commits qualified AltGraph text once but never converts Ctrl+Alt shortcuts", () => {
+    const f = fixture();
+    const euro = envelope({
+      key: "€",
+      code: "KeyE",
+      ctrlKey: true,
+      altKey: true,
+      getModifierState: (value) => value === "AltGraph",
+    });
+    f.input.key("down", euro);
+    f.input.key("up", euro);
+    f.input.key("down", envelope({ key: "e", code: "KeyE", ctrlKey: true, altKey: true }));
+    expect(f.events.filter((event) => event.kind === "text")).toEqual([
+      { kind: "text", text: "€" },
+    ]);
+    expect(f.events.filter((event) => event.kind === "key")).toHaveLength(3);
+    expect(
+      f.events.filter((event) => event.kind === "key").every((event) => event.text === undefined),
+    ).toBe(true);
+    const separate = fixture();
+    separate.input.key(
+      "down",
+      envelope({ key: "€", getModifierState: (value) => value === "AltGraph" }),
+    );
+    expect(separate.events).toEqual([
+      { kind: "key", type: "down", key: "€", code: "KeyA", modifiers: 0, repeat: false, text: "€" },
+    ]);
+  });
+  it("preserves Unicode text, physical repeat/code and all modifier bits", () => {
+    const f = fixture();
+    f.input.key("down", envelope({ key: "é" }));
+    f.input.key("down", envelope({ key: "é", repeat: true }));
+    f.input.key("up", envelope({ key: "é", repeat: true }));
+    expect(f.events).toEqual([
+      { kind: "key", type: "down", key: "é", code: "KeyA", modifiers: 0, repeat: false, text: "é" },
+      { kind: "key", type: "down", key: "é", code: "KeyA", modifiers: 0, repeat: true, text: "é" },
+      { kind: "key", type: "up", key: "é", code: "KeyA", modifiers: 0, repeat: false },
+    ]);
+    expect(
+      canvasKeyModifiers(envelope({ altKey: true, ctrlKey: true, metaKey: true, shiftKey: true })),
+    ).toBe(15);
+    f.input.key("down", envelope({ ctrlKey: true }));
+    expect(f.events.at(-1)).not.toHaveProperty("text");
+  });
+  it("never starts from a cancelled repeat or a repeat that began observe-only", () => {
+    const f = fixture();
+    f.input.key("down", envelope());
+    f.input.reset();
+    expect(f.input.key("down", envelope({ repeat: true }))).toBe(false);
+    expect(f.input.key("up", envelope())).toBe(false);
+    f.disable();
+    f.input.key("down", envelope());
+    f.enable();
+    expect(f.input.key("down", envelope({ repeat: true }))).toBe(false);
+    expect(f.input.key("up", envelope())).toBe(false);
+    expect(f.input.key("down", envelope())).toBe(true);
+    expect(f.events).toHaveLength(2);
+  });
+  it("does not type composition intermediates; commits bounded text separately", () => {
+    const f = fixture();
+    expect(f.input.key("down", envelope({ isComposing: true }))).toBe(false);
+    expect(f.input.key("down", envelope({ key: "Dead" }))).toBe(false);
+    expect(f.input.key("down", envelope({ keyCode: 229 }))).toBe(false);
+    expect(f.input.text("日本語🙂")).toBe(true);
+    expect(f.input.text("x".repeat(16_001))).toBe(false);
+    expect(f.events).toEqual([{ kind: "text", text: "日本語🙂" }]);
+  });
+  it("keeps modifier holds through other keys and finishes only after last keyup", () => {
+    const f = fixture();
+    const ctrl = envelope({ key: "Control", code: "ControlLeft", ctrlKey: true });
+    f.input.key("down", ctrl);
+    f.input.key("down", envelope({ ctrlKey: true }));
+    f.input.key("up", envelope({ ctrlKey: true }));
+    expect(f.finishes()).toBe(0);
+    f.input.key("up", { ...ctrl, ctrlKey: false });
+    expect(f.finishes()).toBe(1);
+  });
+});

package/client/browser-canvas-keyboard.ts

@@ -0,0 +1,126 @@
+/**
+ * Normalize physical canvas keys without inventing presses after control loss.
+ * IME and clipboard commits use text insertion; ordinary typing retains real
+ * key/code/repeat/modifier events. The DOM adapter owns focus and composition.
+ */
+import type { BrowserGestureEvent } from "../shared/browser";
+
+export interface CanvasKeyEnvelope {
+  key: string;
+  code: string;
+  altKey: boolean;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  repeat: boolean;
+  isComposing?: boolean;
+  keyCode?: number;
+  getModifierState?(key: string): boolean;
+}
+export type CanvasKeyboardEvent = Extract<BrowserGestureEvent, { kind: "key" | "text" }>;
+interface KeyboardOptions {
+  enabled(): boolean;
+  enqueue(event: CanvasKeyboardEvent): boolean;
+  finish(): void;
+}
+
+/** CDP modifier bits preserve the actual host combination, including Shift. */
+export function canvasKeyModifiers(event: CanvasKeyEnvelope): number {
+  return (
+    (event.altKey ? 1 : 0) |
+    (event.ctrlKey ? 2 : 0) |
+    (event.metaKey ? 4 : 0) |
+    (event.shiftKey ? 8 : 0)
+  );
+}
+
+/** A cancelled held key's repeat/up cannot begin input on a replacement page. */
+export function createBrowserCanvasKeyboard(options: KeyboardOptions) {
+  const admitted = new Set<string>();
+  const blocked = new Set<string>();
+  const identity = (event: CanvasKeyEnvelope) => event.code || event.key;
+  const reset = () => {
+    for (const key of admitted) blocked.add(key);
+    admitted.clear();
+  };
+  const key = (type: "down" | "up", event: CanvasKeyEnvelope): boolean => {
+    const id = identity(event);
+    if (type === "up") {
+      blocked.delete(id);
+      if (!admitted.delete(id)) {
+        return false;
+      }
+    } else {
+      if (!options.enabled()) {
+        blocked.add(id);
+        return false;
+      }
+      if (
+        event.isComposing ||
+        event.key === "Dead" ||
+        event.key === "Process" ||
+        event.keyCode === 229
+      ) {
+        return false;
+      }
+      // A non-repeat is an authentic new physical edge after a missed blur keyup.
+      if (!event.repeat) {
+        blocked.delete(id);
+      }
+      if (blocked.has(id) || (event.repeat && !admitted.has(id))) {
+        return false;
+      }
+    }
+    if (
+      !options.enabled() ||
+      !event.key ||
+      event.key.length > 64 ||
+      !/^[A-Za-z][A-Za-z0-9]{0,63}$/.test(event.code)
+    ) {
+      return false;
+    }
+    const modifiers = canvasKeyModifiers(event);
+    const printable =
+      type === "down" &&
+      !event.altKey &&
+      !event.ctrlKey &&
+      !event.metaKey &&
+      Array.from(event.key).length === 1;
+    const accepted = options.enqueue({
+      kind: "key",
+      type,
+      key: event.key,
+      code: event.code,
+      modifiers,
+      repeat: type === "down" && event.repeat,
+      ...(printable ? { text: event.key } : {}),
+    });
+    if (accepted && type === "down") {
+      admitted.add(id);
+      // AltGraph can report Ctrl+Alt on international layouts. The real host
+      // qualifier permits one text commit without rewriting a genuine shortcut.
+      if (
+        event.getModifierState?.("AltGraph") &&
+        (modifiers & 7) !== 0 &&
+        Array.from(event.key).length === 1
+      ) {
+        options.enqueue({ kind: "text", text: event.key });
+      }
+    }
+    if (accepted && type === "up" && !admitted.size) {
+      options.finish();
+    }
+    return accepted;
+  };
+  const text = (value: string): boolean => {
+    if (!options.enabled() || !value || value.length > 16_000) {
+      return false;
+    }
+    const accepted = options.enqueue({ kind: "text", text: value });
+    if (accepted && !admitted.size) {
+      options.finish();
+    }
+    return accepted;
+  };
+  return { key, text, reset };
+}

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

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { containedRect } from "../shared/browser";
+import { getBrowserCanvasLayout } from "./browser-canvas-layout";
+
+describe("local browser canvas geometry", () => {
+  it("defaults to Fit and exactly preserves containedRect's letterboxing", () => {
+    const container = { width: 1000, height: 700 };
+    const frame = { width: 824, height: 1678 };
+    expect(getBrowserCanvasLayout(container, frame, { width: 412, height: 839 })).toEqual({
+      contentSize: container,
+      frameRect: containedRect(container, frame),
+    });
+  });
+
+  it("displays sharp Pixel capture at canonical CSS size rather than twice its size", () => {
+    expect(
+      getBrowserCanvasLayout(
+        { width: 300, height: 600 },
+        { width: 824, height: 1678 },
+        { width: 412, height: 839 },
+        "actual",
+      ),
+    ).toEqual({
+      contentSize: { width: 412, height: 839 },
+      frameRect: { x: 0, y: 0, width: 412, height: 839 },
+    });
+  });
+
+  it("keeps Actual size unchanged at DPR1,2 or3", () => {
+    const viewport = { width: 1280, height: 800 };
+    for (const scale of [1, 2, 3]) {
+      expect(
+        getBrowserCanvasLayout(
+          { width: 600, height: 400 },
+          { width: viewport.width * scale, height: viewport.height * scale },
+          viewport,
+          "actual",
+        ),
+      ).toEqual({
+        contentSize: viewport,
+        frameRect: { x: 0, y: 0, ...viewport },
+      });
+    }
+  });
+
+  it("lets the scroll host center a smaller Actual frame without an outer-sized spacer", () => {
+    expect(
+      getBrowserCanvasLayout(
+        { width: 1000, height: 1000 },
+        { width: 824, height: 1678 },
+        { width: 412, height: 839 },
+        "actual",
+      ),
+    ).toEqual({
+      contentSize: { width: 412, height: 839 },
+      frameRect: { x: 0, y: 0, width: 412, height: 839 },
+    });
+  });
+
+  it("uses exact frame extents on both axes so scrollbar allocation cannot create unused overflow", () => {
+    expect(
+      getBrowserCanvasLayout(
+        { width: 1000, height: 500 },
+        { width: 824, height: 1678 },
+        { width: 412, height: 839 },
+        "actual",
+      ),
+    ).toEqual({
+      contentSize: { width: 412, height: 839 },
+      frameRect: { x: 0, y: 0, width: 412, height: 839 },
+    });
+    expect(
+      getBrowserCanvasLayout(
+        { width: 300, height: 1000 },
+        { width: 824, height: 1678 },
+        { width: 412, height: 839 },
+        "actual",
+      ),
+    ).toEqual({
+      contentSize: { width: 412, height: 839 },
+      frameRect: { x: 0, y: 0, width: 412, height: 839 },
+    });
+  });
+
+  it("rejects invalid/unmeasured dimensions without publishing NaN overlay coordinates", () => {
+    const valid = { width: 600, height: 400 };
+    for (const invalid of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      for (const axis of ["width", "height"] as const) {
+        const size = { ...valid, [axis]: invalid };
+        expect(getBrowserCanvasLayout(size, valid, valid)).toBeNull();
+        expect(getBrowserCanvasLayout(valid, size, valid)).toBeNull();
+        expect(getBrowserCanvasLayout(valid, valid, size, "actual")).toBeNull();
+      }
+    }
+  });
+
+  it("does not require resolved remote CSS size before the existing Fit geometry can render", () => {
+    expect(
+      getBrowserCanvasLayout(
+        { width: 800, height: 600 },
+        { width: 1280, height: 800 },
+        { width: 0, height: 0 },
+      ),
+    ).toEqual({
+      contentSize: { width: 800, height: 600 },
+      frameRect: containedRect({ width: 800, height: 600 }, { width: 1280, height: 800 }),
+    });
+  });
+});

package/client/browser-canvas-layout.ts

@@ -0,0 +1,51 @@
+/**
+ * Local viewer geometry only. Frame pixels determine Fit's aspect ratio; Actual
+ * size uses the remote viewport's CSS dimensions, independently of capture DPR.
+ * Neither mode changes the remote viewport or its frame/input authority.
+ */
+import { containedRect, type FrameRect, type FrameSize } from "../shared/browser";
+
+export type BrowserCanvasDisplayMode = "fit" | "actual";
+
+export interface BrowserCanvasLayout {
+  /** Frame wrapper size; Actual's scroll host centers it within the available inner viewport. */
+  contentSize: FrameSize;
+  /** Position and displayed size inside that extent, also used by the input overlay. */
+  frameRect: FrameRect;
+}
+
+/**
+ * Calculate displayed geometry without treating sharp capture pixels as CSS
+ * dimensions. Invalid/unmeasured sizes return null so no frame or input overlay
+ * receives non-finite coordinates. Fit preserves containedRect's exact geometry.
+ */
+export function getBrowserCanvasLayout(
+  containerSize: FrameSize,
+  framePixelSize: FrameSize,
+  viewportCssSize: FrameSize,
+  mode: BrowserCanvasDisplayMode = "fit",
+): BrowserCanvasLayout | null {
+  if (!validSize(containerSize) || !validSize(framePixelSize)) return null;
+
+  if (mode === "fit") {
+    const frameRect = containedRect(containerSize, framePixelSize);
+    return frameRect ? { contentSize: { ...containerSize }, frameRect } : null;
+  }
+
+  if (!validSize(viewportCssSize)) return null;
+  return {
+    contentSize: { ...viewportCssSize },
+    frameRect: {
+      x: 0,
+      y: 0,
+      width: viewportCssSize.width,
+      height: viewportCssSize.height,
+    },
+  };
+}
+
+function validSize(size: FrameSize): boolean {
+  return (
+    Number.isFinite(size.width) && size.width > 0 && Number.isFinite(size.height) && size.height > 0
+  );
+}