@reticlehq/server 3.8.2 → 3.10.0

package/dist/portal/pool/context-permissions.js

@@ -1,3 +1,22 @@
+/**
+ * Browser permissions on a leased context: granted before the first navigation, and read back where
+ * the browser can contradict the grant.
+ *
+ * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
+ * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
+ * is. A different set means a fresh lease.
+ *
+ * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
+ * is not handed the same grant as the app.
+ *
+ * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
+ * when Playwright's own Chromium is installed — has no notification support: after a grant,
+ * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
+ * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
+ * "granted" there would be reporting something the page cannot see.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
+import { allowDaemonInCsp, allowDaemonInHtml } from './csp-widen.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export const NOTIFICATIONS_PERMISSION = 'notifications';
 /** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
@@ -19,8 +38,9 @@ function reasonOf(err) {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export async function grantLeasePermissions(context, permissions, url) {
-    if (0 === permissions.length)
+    if (0 === permissions.length) {
         return;
+    }
     if (context.grantPermissions === undefined) {
         throw new LeasePermissionError('this browser context cannot grant permissions');
     }
@@ -31,6 +51,36 @@ export async function grantLeasePermissions(context, permissions, url) {
         throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
     }
 }
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export function offLoopbackOrigin(url) {
+    if (url === undefined || !URL.canParse(url)) {
+        return undefined;
+    }
+    const target = new URL(url);
+    return isLoopbackHostname(target.hostname) ? undefined : target.origin;
+}
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export const LOCAL_NETWORK_ACCESS = 'local-network-access';
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export async function grantLocalNetworkAccess(context, url) {
+    const origin = offLoopbackOrigin(url);
+    if (context.grantPermissions === undefined || origin === undefined) {
+        return;
+    }
+    try {
+        await context.grantPermissions([LOCAL_NETWORK_ACCESS], { origin });
+    }
+    catch {
+        // An unknown permission name on an older Playwright: open the lease without it.
+    }
+}
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -57,3 +107,46 @@ export async function readNotificationPermission(page) {
         clearTimeout(timer);
     }
 }
+/** How long the loopback CSP probe may take. Bounded because acquire waits on it. */
+export const CSP_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * Whether the document at `url` sends a CSP (header or meta tag) that would block a dial to
+ * `daemonOrigin` (#2163). False when it cannot be asked: the lease then opens as before.
+ */
+export async function pageCspBlocksDaemon(url, daemonOrigin, probe = fetch) {
+    try {
+        const response = await probe(url, { signal: AbortSignal.timeout(CSP_PROBE_TIMEOUT_MS) });
+        const header = response.headers.get('content-security-policy');
+        if (header !== null && allowDaemonInCsp(header, daemonOrigin).changed) {
+            return true;
+        }
+        if (!/html/i.test(response.headers.get('content-type') ?? '')) {
+            return false;
+        }
+        return allowDaemonInHtml(await response.text(), daemonOrigin).changed;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * On a lease whose page's CSP would block the daemon, add `daemonOrigin` to its `connect-src`
+ * (#2016). Off loopback this always installs the route. On loopback it installs it only when a
+ * probe of the page finds a CSP that blocks the dial (#2163), because the route sees every request
+ * in the context, and a dev server that sends no CSP should not pay for it. The returned record
+ * gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export async function widenLeaseCsp(context, url, daemonOrigin, probe) {
+    const widening = {};
+    if (daemonOrigin === undefined || context.widenCsp === undefined) {
+        return widening;
+    }
+    const needed = offLoopbackOrigin(url) !== undefined ||
+        (URL.canParse(url) && (await pageCspBlocksDaemon(url, daemonOrigin, probe)));
+    if (needed) {
+        await context.widenCsp(daemonOrigin, () => {
+            widening.widenedFor = daemonOrigin;
+        });
+    }
+    return widening;
+}

package/dist/portal/pool/csp-widen.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+/** The result of a rewrite: the new text, and whether it differs from the text that came in. */
+export interface CspRewrite {
+    policy: string;
+    changed: boolean;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export declare function allowDaemonInCsp(policy: string, origin: string): CspRewrite;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export declare function allowDaemonInHtml(html: string, origin: string): {
+    html: string;
+    changed: boolean;
+};
+/** The part of a Playwright `Route` the rewrite uses. A real `Route` satisfies it. */
+export interface CspRoute<R extends CspResponse = CspResponse> {
+    request(): {
+        resourceType(): string;
+        frame(): {
+            parentFrame(): unknown;
+        };
+    };
+    fallback(): Promise<void>;
+    fetch(opts: {
+        maxRedirects: number;
+    }): Promise<R>;
+    fulfill(opts: {
+        response: R;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<void>;
+}
+/** The part of a Playwright `APIResponse` the rewrite uses. */
+export interface CspResponse {
+    headers(): Record<string, string>;
+    headersArray(): {
+        name: string;
+        value: string;
+    }[];
+    text(): Promise<string>;
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export declare function widenDocumentCsp<R extends CspResponse>(route: CspRoute<R>, origin: string, onWidened: () => void): Promise<void>;

package/dist/portal/pool/csp-widen.js

@@ -0,0 +1,132 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+const CONNECT_SRC = 'connect-src';
+const DEFAULT_SRC = 'default-src';
+const NONE_SOURCE = "'none'";
+const CSP_HEADER = 'content-security-policy';
+const DOCUMENT = 'document';
+const tokensOf = (directive) => directive.trim().split(/\s+/);
+const nameOf = (directive) => (tokensOf(directive)[0] ?? '').toLowerCase();
+/** `name` plus its sources plus `origin`. `'none'` goes, because it is valid only alone. */
+function withOrigin(name, sources, origin) {
+    const kept = sources.filter((s) => s.toLowerCase() !== NONE_SOURCE);
+    return [name, ...kept, origin].join(' ');
+}
+/** One policy (no commas). Only the first `connect-src` counts; a browser ignores a repeat. */
+function allowInOnePolicy(policy, origin) {
+    const directives = policy.split(';');
+    const connect = directives.findIndex((d) => nameOf(d) === CONNECT_SRC);
+    if (connect !== -1) {
+        const [name = CONNECT_SRC, ...sources] = tokensOf(directives[connect] ?? '');
+        if (sources.includes(origin)) {
+            return policy;
+        }
+        const lead = /^\s*/.exec(directives[connect] ?? '')?.[0] ?? '';
+        directives[connect] = `${lead}${withOrigin(name, sources, origin)}`;
+        return directives.join(';');
+    }
+    const fallback = directives.find((d) => nameOf(d) === DEFAULT_SRC);
+    if (fallback === undefined) {
+        return policy;
+    }
+    const head = policy.replace(/[\s;]+$/, '');
+    return `${head}; ${withOrigin(CONNECT_SRC, tokensOf(fallback).slice(1), origin)}`;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export function allowDaemonInCsp(policy, origin) {
+    const next = policy
+        .split(',')
+        .map((one) => allowInOnePolicy(one, origin))
+        .join(',');
+    return { policy: next, changed: next !== policy };
+}
+const META_TAG = /<meta\b[^>]*>/gi;
+const CSP_EQUIV = /\bhttp-equiv\s*=\s*["']?content-security-policy["']?(?=[\s/>])/i;
+const CONTENT_ATTR = /(\bcontent\s*=\s*)("([^"]*)"|'([^']*)')/i;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export function allowDaemonInHtml(html, origin) {
+    const next = html.replace(META_TAG, (tag) => {
+        if (!CSP_EQUIV.test(tag)) {
+            return tag;
+        }
+        return tag.replace(CONTENT_ATTR, (_all, prefix, quoted) => {
+            const quote = quoted.charAt(0);
+            const widened = allowDaemonInCsp(quoted.slice(1, -1), origin).policy;
+            return `${prefix}${quote}${widened}${quote}`;
+        });
+    });
+    return { html: next, changed: next !== html };
+}
+function isTopDocument(route) {
+    const request = route.request();
+    if (request.resourceType() !== DOCUMENT) {
+        return false;
+    }
+    try {
+        return null === request.frame().parentFrame();
+    }
+    catch {
+        // A request with no frame (a service worker's own fetch) is no page the reader runs in.
+        return false;
+    }
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export async function widenDocumentCsp(route, origin, onWidened) {
+    if (!isTopDocument(route)) {
+        await route.fallback();
+        return;
+    }
+    let response;
+    try {
+        // No redirects followed here: a redirect goes back to the browser, so the page URL stays true.
+        response = await route.fetch({ maxRedirects: 0 });
+    }
+    catch {
+        await route.fallback();
+        return;
+    }
+    const policies = response
+        .headersArray()
+        .filter((h) => h.name.toLowerCase() === CSP_HEADER)
+        .map((h) => h.value);
+    const header = allowDaemonInCsp(policies.join(', '), origin);
+    const isHtml = /html/i.test(response.headers()['content-type'] ?? '');
+    const meta = isHtml ? allowDaemonInHtml(await response.text(), origin) : undefined;
+    if (!header.changed && true !== meta?.changed) {
+        await route.fulfill({ response });
+        return;
+    }
+    const headers = { ...response.headers() };
+    if (header.changed) {
+        headers[CSP_HEADER] = header.policy;
+    }
+    if (true === meta?.changed) {
+        // The new body is plain text: the old encoding and length describe a body that is gone.
+        delete headers['content-encoding'];
+        delete headers['content-length'];
+        await route.fulfill({ response, headers, body: meta.html });
+    }
+    else {
+        await route.fulfill({ response, headers });
+    }
+    onWidened();
+}

package/dist/portal/pool/determinism.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A deterministic lease: the same page, driven the same way, gives the same pixels and text.
+ *
+ * Two runs of a canvas game differ because time and randomness differ. This script replaces both
+ * before any page script runs. Math.random and crypto take values from a seeded generator. Date,
+ * performance.now, the timers and requestAnimationFrame read a virtual clock that starts at a fixed
+ * epoch. The clock moves only when the caller steps frames, through `reticle_clock { stepFrames }`.
+ *
+ * The SDK in the page must keep real time, or it cannot wait, reconnect or send its heartbeat. The
+ * script keeps the real timers under `DETERMINISM_GLOBAL_KEY`, and the SDK reads them from there.
+ */
+import { z } from 'zod';
+/** What the caller asks for. */
+export interface DeterminismOptions {
+    seed?: number;
+    /** The value of `navigator.platform`, for example "Linux x86_64". Absent keeps the real one. */
+    platform?: string;
+}
+/** What the page script is given. Plain data, because Playwright sends it as JSON. */
+export interface DeterminismConfig {
+    key: string;
+    seed: number;
+    epochMs: number;
+    frameMs: number;
+    platform?: string;
+}
+/** What one step reports: the frames stepped since the page loaded, and the virtual time. */
+export interface DeterminismStep {
+    frame: number;
+    nowMs: number;
+}
+export declare const DeterminismSchema: z.ZodObject<{
+    seed: z.ZodOptional<z.ZodNumber>;
+    platform: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const LEASE_DETERMINISTIC_ARG: z.ZodOptional<z.ZodObject<{
+    seed: z.ZodOptional<z.ZodNumber>;
+    platform: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+/** A lease's `deterministic` argument, read; a field it does not know is refused by name. */
+export declare function leaseDeterminismOf(raw: unknown): DeterminismOptions | undefined;
+export declare function determinismConfigOf(opts: DeterminismOptions): DeterminismConfig;
+export declare const StepFramesSchema: z.ZodNumber;
+/** Step the page's virtual clock by `frames` frames. Undefined when the page runs no such clock. */
+export declare function stepPage(page: {
+    evaluate?(script: string): Promise<unknown>;
+}, frames: number): Promise<DeterminismStep | undefined>;
+/**
+ * The page script. It must stay self-contained: Playwright sends its source text into the page, so
+ * it can read nothing from this module. The unit test runs it from its source text for that reason.
+ */
+export declare function installDeterminism(config: DeterminismConfig): void;

package/dist/portal/pool/determinism.js

@@ -0,0 +1,259 @@
+/**
+ * A deterministic lease: the same page, driven the same way, gives the same pixels and text.
+ *
+ * Two runs of a canvas game differ because time and randomness differ. This script replaces both
+ * before any page script runs. Math.random and crypto take values from a seeded generator. Date,
+ * performance.now, the timers and requestAnimationFrame read a virtual clock that starts at a fixed
+ * epoch. The clock moves only when the caller steps frames, through `reticle_clock { stepFrames }`.
+ *
+ * The SDK in the page must keep real time, or it cannot wait, reconnect or send its heartbeat. The
+ * script keeps the real timers under `DETERMINISM_GLOBAL_KEY`, and the SDK reads them from there.
+ */
+import { z } from 'zod';
+import { DETERMINISM_DEFAULT_SEED, DETERMINISM_EPOCH_MS, DETERMINISM_FRAME_MS, DETERMINISM_GLOBAL_KEY, DETERMINISM_MAX_STEP_FRAMES, } from '@reticlehq/core';
+export const DeterminismSchema = z
+    .object({
+    seed: z.number().int().min(0).max(0xffffffff).optional(),
+    platform: z.string().min(1).max(64).optional(),
+})
+    .strict();
+export const LEASE_DETERMINISTIC_ARG = DeterminismSchema.optional().describe('Make the leased tab deterministic, for canvas games and animations. Before any page script ' +
+    'runs, Math.random and crypto.getRandomValues use a seeded generator (seed, default 1). Date, ' +
+    'performance.now, setTimeout, setInterval and requestAnimationFrame use a virtual clock that ' +
+    'starts at 2026-01-01T00:00:00Z and moves only when you call reticle_clock { stepFrames: N }. ' +
+    'devicePixelRatio is 1. platform sets navigator.platform, for example "Linux x86_64". CSS ' +
+    'animations, workers and media still run on real time. Example: deterministic: { seed: 7 }.');
+/** A lease's `deterministic` argument, read; a field it does not know is refused by name. */
+export function leaseDeterminismOf(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = DeterminismSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const field = issue?.path.join('.') ?? '';
+        throw new Error(`deterministic${'' === field ? '' : `.${field}`}: ${issue?.message ?? 'not valid'}`);
+    }
+    const { seed, platform } = parsed.data;
+    return {
+        ...(seed === undefined ? {} : { seed }),
+        ...(platform === undefined ? {} : { platform }),
+    };
+}
+export function determinismConfigOf(opts) {
+    return {
+        key: DETERMINISM_GLOBAL_KEY,
+        seed: opts.seed ?? DETERMINISM_DEFAULT_SEED,
+        epochMs: DETERMINISM_EPOCH_MS,
+        frameMs: DETERMINISM_FRAME_MS,
+        ...(opts.platform === undefined ? {} : { platform: opts.platform }),
+    };
+}
+export const StepFramesSchema = z.number().int().min(1).max(DETERMINISM_MAX_STEP_FRAMES);
+const StepResultSchema = z.object({ frame: z.number(), nowMs: z.number() });
+/** Step the page's virtual clock by `frames` frames. Undefined when the page runs no such clock. */
+export async function stepPage(page, frames) {
+    if (page.evaluate === undefined) {
+        return undefined;
+    }
+    const key = JSON.stringify(DETERMINISM_GLOBAL_KEY);
+    const script = `globalThis[Symbol.for(${key})]?.step(${String(StepFramesSchema.parse(frames))})`;
+    const parsed = StepResultSchema.safeParse(await page.evaluate(script));
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * The page script. It must stay self-contained: Playwright sends its source text into the page, so
+ * it can read nothing from this module. The unit test runs it from its source text for that reason.
+ */
+export function installDeterminism(config) {
+    const g = globalThis;
+    const define = (target, name, value) => {
+        Object.defineProperty(target, name, { value, configurable: true, writable: true });
+    };
+    const getter = (target, name, value) => {
+        Object.defineProperty(target, name, { get: () => value, configurable: true });
+    };
+    // The real timers, kept before anything is replaced, for the SDK and for this script.
+    const realSetTimeout = g.setTimeout?.bind(g);
+    const realClearTimeout = g.clearTimeout?.bind(g);
+    const realFrame = 'function' === typeof g.requestAnimationFrame ? g.requestAnimationFrame.bind(g) : undefined;
+    const realPerformanceNow = g.performance?.now.bind(g.performance);
+    // Random: mulberry32, a small 32-bit generator. The same seed gives the same sequence.
+    let state = config.seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    g.Math.random = next;
+    const fill = (view) => {
+        const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+        for (let i = 0; i < bytes.length; i += 1) {
+            bytes[i] = Math.floor(next() * 256);
+        }
+        return view;
+    };
+    if (g.crypto !== undefined) {
+        define(g.crypto, 'getRandomValues', fill);
+        define(g.crypto, 'randomUUID', () => {
+            const b = fill(new Uint8Array(16));
+            b[6] = ((b[6] ?? 0) & 0x0f) | 0x40;
+            b[8] = ((b[8] ?? 0) & 0x3f) | 0x80;
+            const hex = Array.from(b, (n) => n.toString(16).padStart(2, '0')).join('');
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        });
+    }
+    // Clock: `elapsed` is the virtual performance.now. It moves only in `step`.
+    let elapsed = 0;
+    let frame = 0;
+    const RealDate = g.Date;
+    const wallNow = () => config.epochMs + elapsed;
+    const VirtualDate = function (...args) {
+        if (new.target === undefined) {
+            return new RealDate(wallNow()).toString();
+        }
+        return Reflect.construct(RealDate, 0 === args.length ? [wallNow()] : args, new.target);
+    };
+    VirtualDate.prototype = RealDate.prototype;
+    define(VirtualDate, 'now', wallNow);
+    define(VirtualDate, 'parse', RealDate.parse.bind(RealDate));
+    define(VirtualDate, 'UTC', RealDate.UTC.bind(RealDate));
+    g.Date = VirtualDate;
+    if (g.performance !== undefined) {
+        define(g.performance, 'now', () => elapsed);
+    }
+    let nextId = 1;
+    const timers = new Map();
+    const schedule = (cb, ms, args, repeat) => {
+        const id = nextId;
+        nextId += 1;
+        if ('function' !== typeof cb) {
+            return id;
+        }
+        const delay = Math.max(0, Number(ms) || 0);
+        const run = () => {
+            cb(...args);
+        };
+        timers.set(id, {
+            id,
+            at: elapsed + delay,
+            run,
+            ...(repeat ? { every: Math.max(1, delay) } : {}),
+        });
+        return id;
+    };
+    const cancel = (id) => {
+        timers.delete(Number(id));
+    };
+    g.setTimeout = (cb, ms, ...args) => schedule(cb, ms, args, false);
+    g.setInterval = (cb, ms, ...args) => schedule(cb, ms, args, true);
+    g.clearTimeout = cancel;
+    g.clearInterval = cancel;
+    let frames = [];
+    g.requestAnimationFrame = (cb) => {
+        const id = nextId;
+        nextId += 1;
+        if ('function' === typeof cb) {
+            frames.push({ id, cb: cb });
+        }
+        return id;
+    };
+    g.cancelAnimationFrame = (id) => {
+        frames = frames.filter((f) => f.id !== Number(id));
+    };
+    // A callback that throws is reported as the page reports it, and the rest still run. After each
+    // callback the microtasks run, as they do in a browser between two tasks.
+    const settle = () => new Promise((resolve) => {
+        if (g.MessageChannel === undefined) {
+            void Promise.resolve().then(resolve);
+            return;
+        }
+        const channel = new g.MessageChannel();
+        channel.port1.onmessage = () => {
+            resolve();
+        };
+        channel.port2.postMessage(0);
+    });
+    const invoke = async (run) => {
+        try {
+            run();
+        }
+        catch (error) {
+            realSetTimeout?.(() => {
+                throw error;
+            }, 0);
+        }
+        await settle();
+    };
+    const earliestDue = (until) => {
+        let found;
+        for (const t of timers.values()) {
+            if (t.at <= until && (found === undefined || t.at < found.at)) {
+                found = t;
+            }
+        }
+        return found;
+    };
+    const step = async (count) => {
+        for (let i = 0; i < count; i += 1) {
+            frame += 1;
+            const target = frame * config.frameMs;
+            for (let guard = 0; guard < 100000; guard += 1) {
+                const due = earliestDue(target);
+                if (due === undefined) {
+                    break;
+                }
+                elapsed = Math.max(elapsed, due.at);
+                timers.delete(due.id);
+                if (due.every !== undefined) {
+                    timers.set(due.id, { ...due, at: due.at + due.every });
+                }
+                await invoke(due.run);
+            }
+            elapsed = target;
+            const flush = frames;
+            frames = [];
+            for (const f of flush) {
+                await invoke(() => {
+                    f.cb(target);
+                });
+            }
+        }
+        return { frame, nowMs: elapsed };
+    };
+    // Keyboard labels and shortcuts differ between Mac and Linux, so the platform can be set.
+    const nav = g.navigator;
+    if (config.platform !== undefined && nav !== undefined) {
+        const platform = config.platform;
+        const families = [
+            ['Mac', 'macOS', '(Macintosh; Intel Mac OS X 10_15_7)'],
+            ['Win', 'Windows', '(Windows NT 10.0; Win64; x64)'],
+            ['Linux', 'Linux', `(X11; ${platform})`],
+        ];
+        const family = families.find(([prefix]) => platform.startsWith(prefix));
+        getter(nav, 'platform', platform);
+        if (family !== undefined) {
+            if (nav.userAgentData !== undefined) {
+                getter(nav.userAgentData, 'platform', family[1]);
+            }
+            if (nav.userAgent !== undefined) {
+                getter(nav, 'userAgent', nav.userAgent.replace(/\([^)]*\)/, family[2]));
+            }
+        }
+    }
+    Object.defineProperty(g, Symbol.for(config.key), {
+        value: {
+            step,
+            natives: {
+                setTimeout: realSetTimeout,
+                clearTimeout: realClearTimeout,
+                requestAnimationFrame: realFrame,
+                performanceNow: realPerformanceNow,
+            },
+        },
+        configurable: false,
+        enumerable: false,
+    });
+}

package/dist/portal/pool/lease-emulation.d.ts

@@ -5,6 +5,7 @@
  * so the CSS half of reduced motion and the dark theme could not be checked live. A lease is a
  * Playwright context, which takes all three before the first paint and the media again per call.
  */
+import type { DeterminismOptions } from './determinism.js';
 export declare const ColorScheme: {
     readonly LIGHT: "light";
     readonly DARK: "dark";
@@ -16,18 +17,50 @@ export declare const ReducedMotion: {
     readonly NO_PREFERENCE: "no-preference";
 };
 export type ReducedMotion = (typeof ReducedMotion)[keyof typeof ReducedMotion];
+export declare const Pointer: {
+    readonly FINE: "fine";
+    readonly COARSE: "coarse";
+};
+export type Pointer = (typeof Pointer)[keyof typeof Pointer];
 /** The media features a page reads with matchMedia. */
 export interface LeaseMedia {
     colorScheme?: ColorScheme;
     reducedMotion?: ReducedMotion;
 }
-/** What a lease opens with: the media, and a viewport. */
+/** What a lease opens with: the media, a viewport, and the pointer the page reads. */
 export interface LeaseEmulation extends LeaseMedia {
     viewport?: {
         width: number;
         height: number;
     };
+    /**
+     * The primary pointer `@media (pointer: ...)` reports. Unlike the media features, it is fixed
+     * when the context opens: Playwright's touch support is a context option, so a live lease cannot
+     * be given one. Without it a touch-only rule could not be reached at all, and a lease answered
+     * every `(pointer: coarse)` query with a mouse (#1903).
+     */
+    pointer?: Pointer;
+    /** A seeded random source and a stepped clock, installed before any page script (determinism.ts). */
+    deterministic?: DeterminismOptions;
 }
+/** The same emulation in the names Playwright's own context options use. */
+export interface ContextEmulation extends LeaseMedia {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    hasTouch?: boolean;
+    deviceScaleFactor?: number;
+}
+/**
+ * Translate a lease's emulation into context options. `pointer` is not one of Playwright's: a
+ * coarse primary pointer is what touch support produces, so it travels as `hasTouch`.
+ *
+ * Measured in real headless Chromium: `hasTouch: true` makes `(pointer: coarse)` match and
+ * `(pointer: fine)` stop matching, with `maxTouchPoints` at 1. `isMobile` does the same and also
+ * changes viewport-meta handling, so it is deliberately left out.
+ */
+export declare function contextEmulationOf(emulate: LeaseEmulation): ContextEmulation;
 /** The size a page reports for itself, or undefined when it cannot be read. */
 export declare function readViewport(page: {
     evaluate?(script: string): Promise<unknown>;