@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.249.1

package/shared/browser-display-preferences.ts

@@ -0,0 +1,46 @@
+/**
+ * Host-persisted display favorites through Paseo's settings service. These values
+ * affect viewing quality and picker convenience, never input ownership, page
+ * navigation, emulation or pixel density. Version1 migration retains the bitrate
+ * formerly coupled to JPEG quality.
+ * Retired IDs remain parseable; the current catalogue prunes them at the view.
+ */
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { DEFAULT_CAPTURE_QUALITY } from "./capture-settings";
+import { DEVICE_PRESETS } from "./device-presets";
+import {
+  resolveVideoEncoderSettings,
+  videoBitrateSchema,
+  videoFrameRateSchema,
+} from "./video-settings";
+
+export const browserDisplayPreferencesSchema = z.object({
+  captureQuality: z.enum(["low", "medium", "high", "maximum"]).default(DEFAULT_CAPTURE_QUALITY),
+  videoBitrate: videoBitrateSchema.default(12_000_000),
+  videoFps: videoFrameRateSchema.default(30),
+  favoritePresetIds: z.array(z.string().min(1).max(128)).max(DEVICE_PRESETS.length).default([]),
+});
+
+export type BrowserDisplayPreferences = z.output<typeof browserDisplayPreferencesSchema>;
+
+/** One revisioned document per plugin host, shared across that host's panels. */
+export const browserDisplayPreferences = defineSettings({
+  id: "display-preferences",
+  scope: "host",
+  version: 2,
+  migrate(values, fromVersion) {
+    if (fromVersion !== 1 || !values || typeof values !== "object") return values;
+    const previous = values as Record<string, unknown>;
+    const quality =
+      previous.captureQuality === "low" || previous.captureQuality === "medium"
+        ? previous.captureQuality
+        : "high";
+    return {
+      ...previous,
+      videoBitrate: resolveVideoEncoderSettings({ quality }).bitrate,
+      videoFps: 30,
+    };
+  },
+  schema: browserDisplayPreferencesSchema,
+});

package/shared/browser-video.ts

@@ -0,0 +1,83 @@
+/**
+ * Encoded browser-tab video over the existing authenticated Paseo RPC transport.
+ * Opt-in on the daemon and decoded by WebCodecs on the web; every other client retains JPEG.
+ * Packets never grant control; only a decoded
+ * presentation with current browser authority can provide an input target.
+ */
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { browserFrameSchema, browserStateSchema } from "./browser";
+import { videoBitrateSchema, videoFrameRateSchema } from "./video-settings";
+import { MAX_VIEWPORT } from "./viewport-limits";
+
+export const VIDEO_MAX_PACKET_BYTES = 2 * 1024 * 1024;
+export const VIDEO_MAX_BATCH_BYTES = 4 * 1024 * 1024;
+export const VIDEO_MAX_BATCH_PACKETS = 32;
+export const VIDEO_MAX_WAIT_MS = 500;
+export const VIDEO_FRAME_RATE = 30;
+/** Maximum future source-clock skew admitted by the calibrated native capture. */
+export const VIDEO_SOURCE_CLOCK_TOLERANCE_MS = 50;
+
+const opaqueIdSchema = browserFrameSchema.shape.frameId;
+const sequenceSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const base64PacketSchema = z
+  .string()
+  .min(1)
+  .max(Math.ceil(VIDEO_MAX_PACKET_BYTES / 3) * 4);
+
+/** Geometry and generation shared by JPEG and decoded video input admission. */
+export const browserFrameAuthoritySchema = browserFrameSchema.omit({
+  mimeType: true,
+  transport: true,
+  dataBase64: true,
+  byteLength: true,
+});
+export type BrowserFrameAuthority = z.infer<typeof browserFrameAuthoritySchema>;
+
+/** Native encoded output; timestamps are source VideoFrame microseconds, not wall-clock time. */
+export const nativeVideoPacketSchema = z.object({
+  streamId: opaqueIdSchema,
+  captureGeneration: sequenceSchema,
+  sequence: sequenceSchema,
+  timestampUs: sequenceSchema,
+  type: z.enum(["key", "delta"]),
+  codec: z.string().min(1).max(64),
+  width: z.number().int().positive().max(MAX_VIEWPORT.width),
+  height: z.number().int().positive().max(MAX_VIEWPORT.height),
+  descriptionBase64: z.string().max(16_384).optional(),
+  dataBase64: base64PacketSchema,
+  capturedAt: z.string().datetime(),
+});
+export type NativeVideoPacket = z.infer<typeof nativeVideoPacketSchema>;
+
+export const browserVideoPacketSchema = nativeVideoPacketSchema.extend({
+  frame: browserFrameAuthoritySchema,
+  /** False when the host refused this capture as an input receipt (it predates
+   * acknowledged input). It may still be painted. Absent from older hosts. */
+  actionable: z.boolean().optional(),
+});
+export type BrowserVideoPacket = z.infer<typeof browserVideoPacketSchema>;
+
+export const readBrowserVideoRpc = defineRpc({
+  name: "shared-browser.video.read",
+  input: z.object({
+    viewerToken: opaqueIdSchema,
+    quality: z.enum(["low", "medium", "high"]).default("high"),
+    bitrate: videoBitrateSchema.optional(),
+    fps: videoFrameRateSchema.optional(),
+    streamId: opaqueIdSchema.nullable().default(null),
+    afterSequence: sequenceSchema.default(0),
+    requestKeyFrame: z.boolean().default(false),
+    waitMs: z.number().int().min(0).max(VIDEO_MAX_WAIT_MS).default(250),
+  }),
+  output: z.object({
+    state: browserStateSchema,
+    status: z.enum(["ready", "waiting", "reset", "unsupported"]),
+    streamId: opaqueIdSchema.nullable(),
+    packets: z.array(browserVideoPacketSchema).max(VIDEO_MAX_BATCH_PACKETS),
+    reason: z.string().max(256).optional(),
+    reasonCode: z.enum(["encoder-capacity", "video-disabled"]).optional(),
+  }),
+});
+export type BrowserVideoReadInput = z.infer<typeof readBrowserVideoRpc.input>;
+export type BrowserVideoReadReply = z.infer<typeof readBrowserVideoRpc.output>;

package/shared/browser.ts

@@ -1,71 +1,28 @@
+import { captureDensitySchema } from "./capture-density";
+
+export { type CaptureDensity, canUseCaptureDensity, captureDensitySchema } from "./capture-density";
+
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
+import {
+  DEFAULT_CAPTURE_QUALITY,
+  FRAME_MAX_BASE64_CHARS,
+  FRAME_MAX_BYTES,
+} from "./capture-settings";
+import { DEVICE_PRESET_IDS } from "./device-presets";
+import { MAX_VIEWPORT, MIN_VIEWPORT } from "./viewport-limits";
+
+export {
+  DEFAULT_CAPTURE_QUALITY,
+  FRAME_MAX_BASE64_CHARS,
+  FRAME_MAX_BYTES,
+} from "./capture-settings";
+export { DEVICE_PRESET_IDS, DEVICE_PRESETS, type DevicePresetId } from "./device-presets";
 
 export const DEFAULT_VIEWPORT = { width: 1280, height: 800 } as const;
-export const MIN_VIEWPORT = { width: 320, height: 480 } as const;
-export const MAX_VIEWPORT = { width: 1600, height: 1200 } as const;
-export const FRAME_MAX_BYTES = 800_000;
-export const FRAME_MAX_BASE64_CHARS = Math.ceil(FRAME_MAX_BYTES / 3) * 4;
-
-export const DEVICE_PRESETS = [
-  {
-    id: "desktop-chrome",
-    label: "Desktop Chrome",
-    shortLabel: "Desktop",
-    viewport: { width: 1280, height: 720 },
-    deviceScaleFactor: 1,
-    isMobile: false,
-    hasTouch: false,
-    platform: "Win32",
-    userAgent:
-      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Safari/537.36",
-  },
-  {
-    id: "iphone-15-pro",
-    label: "iPhone 15 Pro",
-    shortLabel: "iPhone 15",
-    viewport: { width: 393, height: 659 },
-    deviceScaleFactor: 3,
-    isMobile: true,
-    hasTouch: true,
-    platform: "iPhone",
-    userAgent:
-      "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
-  },
-  {
-    id: "pixel-7",
-    label: "Pixel 7",
-    shortLabel: "Pixel 7",
-    viewport: { width: 412, height: 839 },
-    deviceScaleFactor: 2.625,
-    isMobile: true,
-    hasTouch: true,
-    platform: "Linux armv81",
-    userAgent:
-      "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Mobile Safari/537.36",
-  },
-  {
-    id: "ipad-pro-11",
-    label: "iPad Pro 11",
-    shortLabel: "iPad 11",
-    viewport: { width: 834, height: 1194 },
-    deviceScaleFactor: 2,
-    isMobile: true,
-    hasTouch: true,
-    platform: "iPad",
-    userAgent:
-      "Mozilla/5.0 (iPad; CPU OS 12_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
-  },
-] as const;
-
-export const DEVICE_PRESET_IDS = [
-  "desktop-chrome",
-  "iphone-15-pro",
-  "pixel-7",
-  "ipad-pro-11",
-] as const;
-
-export type DevicePresetId = (typeof DEVICE_PRESET_IDS)[number];
+export const MAX_BROWSER_TABS = 8;
+export { MAX_VIEWPORT, MIN_VIEWPORT } from "./viewport-limits";
+
 const devicePresetIdSchema = z.enum(DEVICE_PRESET_IDS);
 
 const workspaceIdSchema = z
@@ -81,6 +38,20 @@ const opaqueTokenSchema = z
 const generationSchema = z.number().int().nonnegative();
 const epochSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
 const runtimeIdSchema = opaqueTokenSchema;
+export const browserTabIdSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_-]+$/);
+
+export const browserTabSchema = z.object({
+  id: browserTabIdSchema,
+  title: z.string().max(1_024),
+  url: z.string().max(8_192),
+  viewerCount: z.number().int().nonnegative(),
+  controllerLabel: z.string().max(64).nullable(),
+});
+export type BrowserTab = z.output<typeof browserTabSchema>;
 
 export const browserRecoveryStateSchema = z.enum([
   "available",
@@ -102,6 +73,7 @@ export const browserStateSchema = z.object({
   canGoBack: z.boolean(),
   canGoForward: z.boolean(),
   viewport: viewportSchema,
+  captureScale: z.number().min(1).max(2).default(1),
   navigationGeneration: generationSchema,
   viewportGeneration: generationSchema,
   devicePresetId: devicePresetIdSchema.nullable(),
@@ -111,7 +83,9 @@ export const browserStateSchema = z.object({
   controllerExpiresAt: z.string().datetime().nullable(),
   viewerCount: z.number().int().nonnegative(),
   error: z.string().max(2_048).nullable(),
+  notice: z.string().max(256).optional(),
   runtimeId: runtimeIdSchema.optional(),
+  tabId: browserTabIdSchema.optional(),
   runtimeCreatedAt: epochSchema.optional(),
   bridgeEpoch: epochSchema.optional(),
   recoveryState: browserRecoveryStateSchema.optional(),
@@ -138,6 +112,7 @@ export const attachBrowserRpc = defineRpc({
   input: z.object({
     workspaceId: workspaceIdSchema,
     viewerLabel: z.string().trim().min(1).max(64),
+    tabId: browserTabIdSchema.optional(),
   }),
   output: z.object({
     viewerToken: opaqueTokenSchema,
@@ -145,12 +120,53 @@ export const attachBrowserRpc = defineRpc({
   }),
 });
 
+export const listBrowserTabsRpc = defineRpc({
+  name: "shared-browser.tabs.list",
+  input: z.object({ viewerToken: opaqueTokenSchema }),
+  output: z.object({ tabs: z.array(browserTabSchema).max(MAX_BROWSER_TABS) }),
+});
+
+export const createBrowserTabRpc = defineRpc({
+  name: "shared-browser.tabs.create",
+  input: z.object({ viewerToken: opaqueTokenSchema }),
+  output: z.object({ tabId: browserTabIdSchema }),
+});
+
+export const closeBrowserTabRpc = defineRpc({
+  name: "shared-browser.tabs.close",
+  input: z.object({
+    viewerToken: opaqueTokenSchema,
+    controlToken: opaqueTokenSchema,
+    tabId: browserTabIdSchema,
+  }),
+  output: z.object({ closed: z.literal(true) }),
+});
+
 export const detachBrowserRpc = defineRpc({
   name: "shared-browser.detach",
   input: z.object({ viewerToken: opaqueTokenSchema }),
   output: z.object({ detached: z.boolean() }),
 });
 
+/** Stop the current workspace runtime only when its controller still owns this session. */
+export const closeBrowserRpc = defineRpc({
+  name: "shared-browser.close",
+  input: z.object({
+    viewerToken: opaqueTokenSchema,
+    controlToken: opaqueTokenSchema,
+    sessionId: opaqueTokenSchema,
+    runtimeId: runtimeIdSchema,
+  }),
+  output: z.object({ closed: z.literal(true) }),
+});
+
+/** Reopen a deliberately closed workspace browser using its retained profile. */
+export const reopenBrowserRpc = defineRpc({
+  name: "shared-browser.reopen",
+  input: z.object({ workspaceId: workspaceIdSchema }),
+  output: z.object({ opened: z.literal(true) }),
+});
+
 export const listOpenBrowserWorkspacesRpc = defineRpc({
   name: "shared-browser.presence",
   input: z.object({}),
@@ -161,7 +177,7 @@ export const captureBrowserRpc = defineRpc({
   name: "shared-browser.capture",
   input: z.object({
     viewerToken: opaqueTokenSchema,
-    quality: z.enum(["low", "medium", "high"]).default("medium"),
+    quality: z.enum(["low", "medium", "high", "maximum"]).default(DEFAULT_CAPTURE_QUALITY),
     knownFrameId: opaqueTokenSchema.nullable().default(null),
   }),
   output: z.object({
@@ -225,6 +241,22 @@ export const resizeBrowserRpc = defineRpc({
     controlToken: opaqueTokenSchema,
     expected: expectedStateSchema,
     viewport: viewportSchema,
+    /** Panel following changes layout size without resetting device behavior or density. */
+    preserveEmulation: z.boolean().optional(),
+    /** Resolve automatic density and panel geometry in one controlled transition. */
+    captureDensity: captureDensitySchema.optional(),
+  }),
+  output: z.object({ state: browserStateSchema }),
+});
+
+/** Independent, controller-authorized density selection; no page navigation or preset substitution. */
+export const setCaptureDensityRpc = defineRpc({
+  name: "shared-browser.capture.density",
+  input: z.object({
+    viewerToken: opaqueTokenSchema,
+    controlToken: opaqueTokenSchema,
+    expected: expectedStateSchema,
+    density: captureDensitySchema,
   }),
   output: z.object({ state: browserStateSchema }),
 });
@@ -236,6 +268,8 @@ export const applyDevicePresetRpc = defineRpc({
     controlToken: opaqueTokenSchema,
     expected: expectedStateSchema,
     presetId: devicePresetIdSchema,
+    /** Mode-only changes retain current CSS dimensions and JPEG capture density. */
+    preserveDisplay: z.boolean().optional(),
   }),
   output: z.object({ state: browserStateSchema }),
 });
@@ -312,6 +346,193 @@ export const sendBrowserInputRpc = defineRpc({
   output: z.object({ state: browserStateSchema }),
 });
 
+/** Safe CSS cursor names only. Custom cursor URLs never reach the local client. */
+export const browserCursorSchema = z.enum([
+  "default",
+  "none",
+  "pointer",
+  "text",
+  "vertical-text",
+  "crosshair",
+  "move",
+  "grab",
+  "grabbing",
+  "wait",
+  "progress",
+  "help",
+  "not-allowed",
+  "no-drop",
+  "copy",
+  "alias",
+  "context-menu",
+  "cell",
+  "all-scroll",
+  "col-resize",
+  "row-resize",
+  "n-resize",
+  "s-resize",
+  "e-resize",
+  "w-resize",
+  "ne-resize",
+  "nw-resize",
+  "se-resize",
+  "sw-resize",
+  "ew-resize",
+  "ns-resize",
+  "nesw-resize",
+  "nwse-resize",
+  "zoom-in",
+  "zoom-out",
+]);
+export type BrowserCursor = z.output<typeof browserCursorSchema>;
+
+const touchPointSchema = displayedPointSchema.extend({
+  id: z.number().int().min(0).max(2_147_483_647),
+});
+/** Native keyboard modifiers use CDP's bits: Alt 1, Control 2, Meta 4, Shift 8. */
+/** Bound simultaneous physical-key cleanup work without restricting layout codes. */
+export const MAX_HELD_BROWSER_KEYS = 32;
+
+export const browserGestureKeySchema = z
+  .object({
+    kind: z.literal("key"),
+    type: z.enum(["down", "up"]),
+    key: z.string().min(1).max(64),
+    code: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[A-Za-z][A-Za-z0-9]*$/),
+    modifiers: z.number().int().min(0).max(15),
+    repeat: z.boolean().default(false),
+    text: z.string().min(1).max(32).optional(),
+  })
+  .superRefine((event, context) => {
+    if (event.type === "up" && (event.repeat || event.text !== undefined)) {
+      context.addIssue({ code: "custom", message: "Key release cannot repeat or insert text" });
+    }
+    if (event.text !== undefined && (event.modifiers & 7) !== 0) {
+      context.addIssue({ code: "custom", message: "Shortcut keys cannot insert printable text" });
+    }
+  });
+export type BrowserGestureKeyEvent = z.output<typeof browserGestureKeySchema>;
+
+/**
+ * Ordered live input, in displayed-image coordinates. Touch start/move contain
+ * the complete active ID set; removing contacts in move releases those contacts.
+ * End/cancel contain no points. Wheel deltas are bounded browser CSS pixels.
+ */
+// Pointer snapshots use the same CDP modifier bits as key events. Omission
+// preserves native/older callers' held-key inference; explicit zero means none.
+const pointerModifiersSchema = z.number().int().min(0).max(15).optional();
+export const browserGestureEventSchema = z.discriminatedUnion("kind", [
+  browserGestureKeySchema,
+  z.object({ kind: z.literal("text"), text: z.string().min(1).max(16_000) }),
+  z.object({ kind: z.literal("leave") }),
+  z.object({
+    kind: z.literal("move"),
+    point: displayedPointSchema,
+    modifiers: pointerModifiersSchema,
+  }),
+  z.object({
+    kind: z.literal("down"),
+    point: displayedPointSchema,
+    modifiers: pointerModifiersSchema,
+    button: z.enum(["left", "right", "middle"]).default("left"),
+    clickCount: z.union([z.literal(1), z.literal(2)]).default(1),
+  }),
+  z.object({
+    kind: z.literal("up"),
+    point: displayedPointSchema,
+    modifiers: pointerModifiersSchema,
+    button: z.enum(["left", "right", "middle"]).default("left"),
+    clickCount: z.union([z.literal(1), z.literal(2)]).default(1),
+  }),
+  z.object({
+    kind: z.literal("scroll"),
+    point: displayedPointSchema,
+    modifiers: pointerModifiersSchema,
+    deltaX: z.number().finite().min(-4_000).max(4_000),
+    deltaY: z.number().finite().min(-4_000).max(4_000),
+  }),
+  z
+    .object({
+      kind: z.literal("touch"),
+      type: z.enum(["start", "move", "end", "cancel"]),
+      points: z.array(touchPointSchema).max(5),
+    })
+    .superRefine((event, context) => {
+      if ((event.type === "end" || event.type === "cancel") !== (event.points.length === 0)) {
+        context.addIssue({
+          code: "custom",
+          message: "Touch start/move require points; end/cancel require none",
+        });
+      }
+      if (new Set(event.points.map((point) => point.id)).size !== event.points.length) {
+        context.addIssue({ code: "custom", message: "Touch identifiers must be unique" });
+      }
+    }),
+]);
+export type BrowserGestureEvent = z.output<typeof browserGestureEventSchema>;
+
+const gestureContextSchema = z.object({
+  viewerToken: opaqueTokenSchema,
+  controlToken: opaqueTokenSchema,
+  expected: expectedStateSchema.extend({ runtimeId: runtimeIdSchema, bridgeEpoch: epochSchema }),
+});
+const gestureContinuationSchema = gestureContextSchema.extend({
+  gestureId: opaqueTokenSchema,
+  sequence: z.number().int().positive().max(100_000),
+});
+/** Begin pins a decoded recent frame but sends no physical input. One live channel per controller. Keyboard events may share either pointer channel. */
+export const beginBrowserGestureRpc = defineRpc({
+  name: "shared-browser.gesture.begin",
+  input: gestureContextSchema.extend({
+    target: targetFrameSchema,
+    pointerKind: z.enum(["mouse", "touch"]),
+  }),
+  output: z.union([
+    z.object({
+      state: browserStateSchema,
+      gestureId: opaqueTokenSchema,
+      nextSequence: z.number().int().positive(),
+    }),
+    // This receipt exists only before input.begin, so no physical action or channel is replayed.
+    z.object({ state: browserStateSchema, admission: z.literal("stale-frame") }),
+  ]),
+});
+/**
+ * Strict sequence continues the original frame context despite this channel's
+ * input invalidations. Independent mouse down/initial touch start require target;
+ * additional contacts in a held touch gesture continue its pinned geometry.
+ */
+export const updateBrowserGestureRpc = defineRpc({
+  name: "shared-browser.gesture.update",
+  input: gestureContinuationSchema.extend({
+    event: browserGestureEventSchema,
+    target: targetFrameSchema.optional(),
+  }),
+  // The native input was acknowledged and navigated on its original attachment.
+  // This closes the old channel; it never authorizes a continuation or a replay.
+  output: z.object({
+    state: browserStateSchema,
+    gestureId: opaqueTokenSchema,
+    nextSequence: z.number().int().positive(),
+    cursor: browserCursorSchema.nullable(),
+    completion: z.literal("navigation").optional(),
+  }),
+});
+/**
+ * End/cancel releases the original held input without retrying an uncertain action.
+ * cancel permits a stale sequence after a lost reply, but still requires the exact
+ * owned gesture/controller. Normal end requires the acknowledged next sequence.
+ */
+export const endBrowserGestureRpc = defineRpc({
+  name: "shared-browser.gesture.end",
+  input: gestureContinuationSchema.extend({ cancel: z.boolean().default(false) }),
+  output: z.object({ state: browserStateSchema, cursor: browserCursorSchema.nullable() }),
+});
+
 export type BrowserState = z.output<typeof browserStateSchema>;
 export type BrowserFrame = z.output<typeof browserFrameSchema>;
 export type BrowserInputEvent = z.output<typeof browserInputEventSchema>;

package/shared/capture-density.ts

@@ -0,0 +1,16 @@
+/** Density changes physical capture pixels, never CSS layout or pointer coordinates. */
+import { z } from "zod";
+import { MAX_VIEWPORT } from "./viewport-limits";
+export const captureDensitySchema = z.union([z.literal(1), z.literal(2)]);
+export type CaptureDensity = z.infer<typeof captureDensitySchema>;
+
+/** UI and server share the exact bound; an unsupported choice must not resize the page. */
+export function canUseCaptureDensity(
+  viewport: { width: number; height: number },
+  density: CaptureDensity,
+): boolean {
+  return (
+    viewport.width * density <= MAX_VIEWPORT.width &&
+    viewport.height * density <= MAX_VIEWPORT.height
+  );
+}

package/shared/capture-settings.ts

@@ -0,0 +1,17 @@
+/** JPEG quality and byte bounds shared by the human viewer, agent adapter and browser runtime. */
+export const DEFAULT_CAPTURE_QUALITY = "medium" as const;
+export const JPEG_QUALITY = { low: 40, medium: 65, high: 85, maximum: 100 } as const;
+export type CaptureQuality = keyof typeof JPEG_QUALITY;
+export const DEFAULT_JPEG_QUALITY = JPEG_QUALITY[DEFAULT_CAPTURE_QUALITY];
+
+// Preserve the original RPC frame bound; large captures reduce JPEG quality to fit.
+export const FRAME_MAX_BYTES = 800_000;
+export const FRAME_MAX_BASE64_CHARS = Math.ceil(FRAME_MAX_BYTES / 3) * 4;
+
+/** Actual image pixels are independent of CSS layout and input coordinates for sharper phone capture. */
+export function captureDimensions(viewport: { width: number; height: number }, captureScale = 1) {
+  return {
+    width: Math.round(viewport.width * captureScale),
+    height: Math.round(viewport.height * captureScale),
+  };
+}

package/shared/device-presets.ts

@@ -0,0 +1,90 @@
+/** Device emulation facts and display sizes shared by the picker and server policy. */
+const DESKTOP_CHROME_EMULATION = {
+  deviceScaleFactor: 1,
+  captureScale: 1,
+  isMobile: false,
+  hasTouch: false,
+  platform: "Win32",
+  userAgent:
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Safari/537.36",
+} as const;
+
+/** Larger desktop presets change resolution while retaining the same input and browser behavior. */
+function createDesktopPreset<const Id extends string>(id: Id, width: number, height: number) {
+  const name = width === height ? `${width} square` : `${height}p`;
+
+  return {
+    ...DESKTOP_CHROME_EMULATION,
+    id,
+    label: name,
+    shortLabel: name,
+    viewport: { width, height },
+  } as const;
+}
+
+const PIXEL_7_EMULATION = {
+  id: "pixel-7",
+  label: "Pixel 7",
+  shortLabel: "Pixel 7",
+  viewport: { width: 412, height: 839 },
+  deviceScaleFactor: 2.625,
+  captureScale: 1,
+  isMobile: true,
+  hasTouch: true,
+  platform: "Linux armv81",
+  userAgent:
+    "Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.8010.12 Mobile Safari/537.36",
+} as const;
+
+export const DEVICE_PRESETS = [
+  createDesktopPreset("desktop-chrome", 1280, 720),
+  createDesktopPreset("desktop-1280x800", 1280, 800),
+  createDesktopPreset("desktop-1280x1280", 1280, 1280),
+  createDesktopPreset("desktop-1440x810", 1440, 810),
+  createDesktopPreset("desktop-1440x900", 1440, 900),
+  createDesktopPreset("desktop-1440x1440", 1440, 1440),
+  createDesktopPreset("desktop-1920x1080", 1920, 1080),
+  createDesktopPreset("desktop-2560x1440", 2560, 1440),
+  createDesktopPreset("desktop-1920x1200", 1920, 1200),
+  createDesktopPreset("desktop-2560x1600", 2560, 1600),
+  createDesktopPreset("desktop-1920x1920", 1920, 1920),
+  createDesktopPreset("desktop-2560x2560", 2560, 2560),
+  {
+    id: "iphone-15-pro",
+    label: "iPhone 15 Pro",
+    shortLabel: "iPhone 15",
+    viewport: { width: 393, height: 659 },
+    deviceScaleFactor: 3,
+    captureScale: 1,
+    isMobile: true,
+    hasTouch: true,
+    platform: "iPhone",
+    userAgent:
+      "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
+  },
+  PIXEL_7_EMULATION,
+  {
+    ...PIXEL_7_EMULATION,
+    id: "pixel-7-sharp",
+    label: "Pixel 7 (high resolution)",
+    shortLabel: "Pixel 7 HD",
+    captureScale: 2,
+  },
+  {
+    id: "ipad-pro-11",
+    label: "iPad Pro 11",
+    shortLabel: "iPad 11",
+    viewport: { width: 834, height: 1194 },
+    deviceScaleFactor: 2,
+    captureScale: 1,
+    isMobile: true,
+    hasTouch: true,
+    platform: "iPad",
+    userAgent:
+      "Mozilla/5.0 (iPad; CPU OS 12_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
+  },
+] as const;
+
+// The schema and picker derive from one catalogue, so adding a preset cannot leave it unselectable.
+export const DEVICE_PRESET_IDS = DEVICE_PRESETS.map((preset) => preset.id);
+export type DevicePresetId = (typeof DEVICE_PRESET_IDS)[number];