effect-browser 0.3.0-beta.15 → 0.3.0-beta.19

package/src/internal/input/pointer.ts

@@ -5,11 +5,10 @@
  */
 import { Duration, Effect, MutableRef, Option, Schema } from "effect";
 
-import { InvalidRequest } from "../../BrowserError.ts";
 import { CursorChanged, TrackPerformed, TrackPlanned } from "../../BrowserEvent.ts";
 import * as Motion from "../../Motion.ts";
 import type { Point } from "../../Page.ts";
-import { failWith, type PageContext } from "../page/context.ts";
+import { type PageContext, refuse } from "../page/context.ts";
 import type { Viewport } from "../page/viewport.ts";
 import type { Dispatch } from "./dispatch.ts";
 import type { InputMarks } from "./perform.ts";
@@ -47,11 +46,9 @@ export const make = (page: PageContext, dispatch: Dispatch, viewport: Viewport)
 
       // A custom planner is a boundary. Decoding reads each sample once into a fresh copy and
       // checks that copy, so neither accessors nor later mutation can change what is admitted.
-      const invalid = failWith(
+      const invalid = refuse(
         operation,
-        new InvalidRequest({
-          detail: "motion must be a bounded, ordered schedule ending at the target",
-        }),
+        "motion must be a bounded, ordered schedule ending at the target",
       );
 
       const samples = yield* Schema.decodeEffect(Motion.Plan)(planned).pipe(

package/src/internal/input/replies.ts

@@ -3,7 +3,7 @@
  * Canceling a caller cannot cancel a protocol command already sent. The next action waits for
  * those replies, while a stopped run releases only held keys or buttons whose release was never submitted.
  */
-import { Context, Data, Effect } from "effect";
+import { Context, Data, Effect, type Scope } from "effect";
 
 import { maximumSamples } from "../../Motion.ts";
 
@@ -18,6 +18,8 @@ export interface Run {
   readonly track: <A>(reply: Promise<A>) => Promise<A>;
   /** End ownership after the record and all this operation's native replies have settled. */
   readonly afterIdle: (ended: () => void) => void;
+  /** Retain authority through scoped cleanup after the replies already submitted. */
+  readonly recover: (cleanup: Effect.Effect<void>, scope: Scope.Scope) => Effect.Effect<void>;
   /** Reserve a complete stroke, including its releases, before sending its first event. */
   readonly reserve: (commands: number) => Effect.Effect<void, InputFailure>;
   /** Admit every sample before a motion starts its published clock; ordinary input stays bounded separately. */
@@ -105,17 +107,11 @@ export const make = () => {
     const submit = (command: () => Promise<unknown>) => {
       if (reserved < 1) throw new Error("input must reserve capacity before dispatch");
       reserved--;
-      let response: Promise<unknown>;
-
       try {
-        response = command();
+        void track(command(), true);
       } catch (cause) {
         failure ??= new InputFailure({ cause });
-
-        return;
       }
-
-      void track(response, true);
     };
 
     const reserve = (commands: number, maximum: number, limit: number) =>
@@ -138,6 +134,21 @@ export const make = () => {
         if (pending.size === 0) end();
         else endings.add(end);
       },
+      recover: (cleanup, scope) =>
+        Effect.gen(function* () {
+          const replies = [...pending];
+          const done = Promise.withResolvers<void>();
+
+          // This reservation prevents a new action or suspension from overtaking cleanup.
+          void track(done.promise);
+          yield* Effect.promise(() => Promise.all(replies)).pipe(
+            Effect.andThen(cleanup),
+            Effect.ensuring(Effect.sync(() => done.resolve())),
+            Effect.provideService(Current, run),
+            Effect.interruptible,
+            Effect.forkIn(scope),
+          );
+        }),
       reserve: (commands) => reserve(commands, capacity, capacity),
       // A dense stroke cannot wait for replies midway without changing its published timing.
       // Its finite reservation also leaves room for the ordinary pool's already-owned releases.

package/src/internal/input/settle.ts

@@ -39,12 +39,13 @@ export const make = (page: PageContext, bridge: Bridge) => {
         // evaluate after the settling deadline, without retaining browser input authority.
         Effect.provideService(Current, undefined),
         Effect.catchIf(contextGone, () => Effect.void),
-        Effect.onError(() => page.stopLoading),
       );
       while (document() > before.document && parsed < document()) yield* Deferred.await(changed);
     }).pipe(
       Effect.timeoutOrElse({ duration: settling, orElse: () => Effect.fail("unsettled") }),
-      Effect.catch(() => Effect.annotateCurrentSpan("settled", false)),
+      Effect.catch(() =>
+        page.stopLoading.pipe(Effect.andThen(Effect.annotateCurrentSpan("settled", false))),
+      ),
       Effect.andThen(page.openings.settle(before.openings)),
       page.span("Page.settle", {}, "Debug"),
     );

package/src/internal/input/targets.inpage.ts

@@ -5,7 +5,8 @@
  */
 import { Schema } from "effect";
 
-import { Box, SubjectContext } from "../../BrowserEvent.ts";
+import { Box, Subject } from "../../BrowserEvent.ts";
+import { Point } from "../../Motion.ts";
 import type { ContextReader } from "../reading/context.inpage.ts";
 import type { Names } from "../reading/names.inpage.ts";
 import type { Walk } from "../reading/walk.inpage.ts";
@@ -78,10 +79,7 @@ export const targets = (names: Names, walked: Walk, placing: ContextReader) => {
     };
   };
 
-  const point = (
-    target: string | { readonly x: number; readonly y: number },
-    scroll = true,
-  ): PointResult => {
+  const point = (target: string | Point, scroll = true): PointResult => {
     if (typeof target !== "string") {
       const { x, y } = target;
 
@@ -263,13 +261,9 @@ export const targets = (names: Names, walked: Walk, placing: ContextReader) => {
 export type Targets = ReturnType<typeof targets>;
 
 const ResolvedPointSchema = Schema.Struct({
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Point.fields,
+  ...Subject.fields,
   element: Schema.String,
-  tag: Schema.String,
-  role: Schema.NullOr(Schema.String),
-  name: Schema.String,
-  context: SubjectContext,
   box: Schema.optional(Box),
   cursor: Schema.String,
   href: Schema.optional(Schema.String),
@@ -285,8 +279,7 @@ export const PointResultSchema = Schema.Union([
 
 export const ScrollPlanSchema = Schema.NullOr(
   Schema.Struct({
-    x: Schema.Finite,
-    y: Schema.Finite,
+    ...Point.fields,
     dx: Schema.Finite,
     dy: Schema.Finite,
   }),

package/src/internal/input/targets.ts

@@ -7,11 +7,11 @@ import { Effect } from "effect";
 
 import { InvalidRequest, NotActionable, StaleRef } from "../../BrowserError.ts";
 import { ResolvedTarget, type Target } from "../../Page.ts";
-import { type Bridge, scriptCall } from "../page/bridge.ts";
-import { decodeWith, failWith } from "../page/context.ts";
+import { scriptCall } from "../page/bridge.ts";
+import { decodeWith, failWith, refuse } from "../page/context.ts";
 import type { Viewport } from "../page/viewport.ts";
 import type { Dispatch } from "./dispatch.ts";
-import type { Approval, Guard } from "./guard.ts";
+import { type Approval, check, type Guard } from "./guard.ts";
 import type { InputMarks } from "./perform.ts";
 import type { Pointer } from "./pointer.ts";
 import type { Settle } from "./settle.ts";
@@ -31,29 +31,17 @@ const pointFailure = (
         : new NotActionable({ detail: result.detail }),
   );
 
-const resolvedTarget = (result: Script.ResolvedPoint): ResolvedTarget =>
-  new ResolvedTarget({
-    point: { x: result.x, y: result.y },
-    element: result.element,
-    tag: result.tag,
-    role: result.role,
-    name: result.name,
-    context: result.context,
-    box: result.box,
-    cursor: result.cursor,
-    ...(result.href === undefined ? {} : { href: result.href }),
-  });
+const resolvedTarget = ({ x, y, box, ...target }: Script.ResolvedPoint): ResolvedTarget =>
+  new ResolvedTarget({ point: { x, y }, box, ...target });
 
 export const make = (
-  bridge: Bridge,
   viewport: Viewport,
   guard: Guard,
   pointer: Pointer,
   dispatch: Dispatch,
   settling: Settle,
 ) => {
-  const { evaluate } = bridge;
-  const { mutate } = guard;
+  const { evaluate, mutate } = guard;
   const { moveTo, wheel } = pointer;
   const { flush } = dispatch;
 
@@ -63,22 +51,15 @@ export const make = (
     approval: Approval | undefined,
     scroll: boolean,
   ) =>
-    (approval === undefined
-      ? evaluate(operation, scriptCall("point", target, scroll))
-      : mutate(operation, scriptCall("point", target, scroll), approval)
-    ).pipe(Effect.flatMap(decodeWith(operation, Script.PointResultSchema)));
+    evaluate(operation, scriptCall("point", target, scroll), approval).pipe(
+      Effect.flatMap(decodeWith(operation, Script.PointResultSchema)),
+    );
 
   const resolve = (operation: string, target: Target, approval?: Approval, scroll = true) => {
     if (typeof target === "string" && !/^e\d+$/.test(target))
-      return failWith(
-        operation,
-        new InvalidRequest({ detail: target + " is not a ref; refs look like e12" }),
-      );
+      return refuse(operation, target + " is not a ref; refs look like e12");
     if (typeof target !== "string" && (!Number.isFinite(target.x) || !Number.isFinite(target.y)))
-      return failWith(
-        operation,
-        new InvalidRequest({ detail: "point coordinates must be finite" }),
-      );
+      return refuse(operation, "point coordinates must be finite");
 
     return readPoint(operation, target, approval, scroll).pipe(
       Effect.flatMap((result) =>
@@ -127,7 +108,7 @@ export const make = (
       );
       yield* flush(operation, marks.input);
       yield* settling.settle(operation, before);
-      if (approval !== undefined) yield* approval.check();
+      yield* check(approval);
     }
 
     // Wheels may be prevented or the target may need unsupported nested/frame geometry. One
@@ -137,7 +118,7 @@ export const make = (
 
     yield* resolve(operation, target, approval);
     yield* settling.settle(operation, before);
-    if (approval !== undefined) yield* approval.check();
+    yield* check(approval);
 
     return yield* resolve(operation, target, approval, false);
   });

package/src/internal/page/bridge.ts

@@ -90,7 +90,7 @@ const install = (
 ): PageApi => {
   const installed = globalThis.__effectBrowser;
 
-  if (installed !== undefined && installed.version === 19) return installed;
+  if (installed !== undefined && installed.version === 20) return installed;
   const named = makeNames();
   const walked = makeWalk(named);
   const placing = makeContext(named, walked);
@@ -108,7 +108,7 @@ const install = (
   const readiness = makeReady(walked, texts, kept, recorder);
 
   const api: PageApi = {
-    version: 19,
+    version: 20,
     snapshot: read.snapshot,
     find: subjected.find,
     until: makeExpectations(named, subjected).until,

package/src/internal/page/context.ts

@@ -17,12 +17,19 @@ import {
 import type { CDPSession, Page as PlaywrightPage } from "playwright-core";
 
 import type { CaptureSource } from "../../Browser.ts";
-import { BrowserError, Closed, Failed, type Reason, Timeout } from "../../BrowserError.ts";
+import {
+  BrowserError,
+  Closed,
+  Failed,
+  InvalidRequest,
+  type Reason,
+  Timeout,
+} from "../../BrowserError.ts";
 import type { BrowserEvent } from "../../BrowserEvent.ts";
 import type { InputGuard, Point } from "../../Page.ts";
 import type { Gate } from "../input/gate.ts";
 import { Current } from "../input/replies.ts";
-import type * as BrowserClock from "../pictures/clock.ts";
+import * as BrowserClock from "../pictures/clock.ts";
 import * as Lane from "./lane.ts";
 import type { Openings } from "./openings.ts";
 import * as Url from "./url.ts";
@@ -159,6 +166,10 @@ export const undispatched = (operation: string, reason: Reason) =>
 export const failWith = (operation: string, reason: Reason) =>
   Effect.fail(undispatched(operation, reason));
 
+/** Refuse a request to `operation` that could never succeed, before sending anything. */
+export const refuse = (operation: string, detail: string) =>
+  failWith(operation, new InvalidRequest({ detail }));
+
 export const decodeWith =
   <A>(operation: string, schema: Schema.Codec<A, unknown>) =>
   (value: unknown) =>
@@ -168,7 +179,7 @@ export const decodeWith =
 
 export const make = (options: MakeOptions, scope: Scope.Scope) => {
   const { id, clock } = options;
-  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  const now = () => BrowserClock.monotonicMillis(clock);
   // Deadlines and pacing guard the page's lane, so page operations run on the owner's clock; a
   // caller's clock, such as a TestClock, cannot stall or stretch them.
   const owned = Effect.provideService(Clock.Clock, clock);
@@ -308,6 +319,7 @@ export const make = (options: MakeOptions, scope: Scope.Scope) => {
     lane,
     pointer,
     now,
+    scope,
     owned,
     span,
     protocol,

package/src/internal/page/navigation.ts

@@ -5,17 +5,11 @@
  */
 import { Deferred, Duration, Effect, Schedule } from "effect";
 
-import {
-  BrowserError,
-  InvalidRequest,
-  NavigationFailed,
-  NotActionable,
-  NotFound,
-} from "../../BrowserError.ts";
+import { BrowserError, NavigationFailed, NotActionable, NotFound } from "../../BrowserError.ts";
 import type { Guard } from "../input/guard.ts";
 import type { InputMarks, Perform } from "../input/perform.ts";
 import { Current } from "../input/replies.ts";
-import { failWith, type PageContext } from "./context.ts";
+import { failWith, type PageContext, refuse } from "./context.ts";
 import * as Url from "./url.ts";
 
 export const make = (
@@ -157,10 +151,7 @@ export const make = (
       parsed === null ||
       !["http:", "https:", "about:", "data:", "file:"].includes(parsed.protocol)
     )
-      return failWith(
-        "navigate",
-        new InvalidRequest({ detail: `"${Url.redact(url)}" is not a URL` }),
-      );
+      return refuse("navigate", `"${Url.redact(url)}" is not a URL`);
 
     return navigation(
       "navigate",

package/src/internal/pictures/capture.ts

@@ -18,7 +18,7 @@ import {
 import { type BrowserError, InvalidRequest } from "../../BrowserError.ts";
 import { BrowserPaint, CaptureStats, Frame, type ScreencastOptions } from "../../Frame.ts";
 import { undispatched } from "../page/context.ts";
-import { type Estimate, toHostTime, uncertaintyAt } from "./clock.ts";
+import { type Estimate, monotonicMillis, toHostTime, uncertaintyAt } from "./clock.ts";
 import { tally } from "./counts.ts";
 import * as Quiescence from "./quiescence.ts";
 import type { NativeFrame, Transport } from "./transport.ts";
@@ -47,6 +47,8 @@ interface Options {
   readonly frameHistory: Duration.Duration;
   /** The viewport in CSS pixels; a capture is scaled to fit it, as screenshots are. */
   readonly viewport: Effect.Effect<Size, BrowserError>;
+  /** Copies the restored whole surface before native capture can restart. */
+  readonly restore: () => Promise<unknown>;
   readonly imageSize: (data: Uint8Array) => Size | undefined;
   readonly error: (cause: unknown) => BrowserError;
 }
@@ -154,7 +156,7 @@ const timed = (
       hostTime,
       uncertaintyMillis: uncertaintyAt(estimate, hostTime),
     }),
-    receivedAt: Number(options.clock.monotonicTimeNanosUnsafe()) / 1e6,
+    receivedAt: monotonicMillis(options.clock),
     width: size.width,
     height: size.height,
     ...generation.transport.frameTag(),
@@ -222,7 +224,7 @@ const sizeFilter = (
       Queue.offerUnsafe(wake, undefined);
     };
 
-    const now = () => Number(options.clock.monotonicTimeNanosUnsafe()) / 1e6;
+    const now = () => monotonicMillis(options.clock);
 
     const adopt = (adopted: Run) => {
       run = undefined;
@@ -470,7 +472,7 @@ export const make = (options: Options) =>
     let latest = Option.none<Frame>();
     let history: ReadonlyArray<Frame> = [];
     const keepMillis = Duration.toMillis(options.frameHistory);
-    const now = () => Number(options.clock.monotonicTimeNanosUnsafe()) / 1e6;
+    const now = () => monotonicMillis(options.clock);
     const counts = tally(now);
     // Frames delivered, which number them so that a reader can tell what it missed.
     let delivered = 0;
@@ -589,6 +591,11 @@ export const make = (options: Options) =>
           };
 
           if (current === undefined || !resumable()) return;
+          // Screenshot replies restore emulation before the compositor has necessarily painted
+          // it. Copy the whole restored surface while stopped, retaining its actual native reply.
+          void pictures.track("picture restoration", options.restore(), failed(current));
+          yield* pictures.wait("picture restoration");
+          yield* healthy(current);
           const viewport = yield* readViewport(options);
 
           if (!resumable()) return;

package/src/internal/pictures/clock.ts

@@ -1,8 +1,13 @@
 /**
- * The browser's clock read on the owner's: estimates of their offset from timed probes, how an
- * estimate ages, and the one mapping a browser's pages share. `pictures.ts` takes the probes.
+ * Host monotonic milliseconds and the browser's clock read on the owner's: estimates of their
+ * offset from timed probes, how an estimate ages, and the mapping a browser's pages share.
+ * `pictures.ts` takes the probes.
  */
-import { Duration, Effect, Option } from "effect";
+import { type Clock, Duration, Effect, Option } from "effect";
+
+/** Read the captured owner's clock, including from native callbacks, without changing its origin. */
+export const monotonicMillis = (clock: Clock.Clock): number =>
+  Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
 
 export interface Probe {
   readonly hostStart: number;

package/src/internal/pictures/motion.ts

@@ -0,0 +1,65 @@
+/**
+ * Where a page's screen moves, from its screencast frames: each frame decoded and cut into
+ * 16-pixel blocks, a block moving where a few of its pixels, sampled every other one, changed by
+ * more than JPEG's noise in any color channel.
+ * What moved among the frames before an input is the page's background, such as an idle
+ * animation; foreground stillness ignores it.
+ *
+ * Frames are decoded with the JPEG decoder playwright-core bundles and exports as
+ * `playwright-core/lib/utilsBundle`: effect-browser depends on nothing else, and the runtime has
+ * no image decoder. That entry point has no types, so `utilsBundle.d.ts` declares what is used.
+ */
+// oxlint-disable-next-line typescript/triple-slash-reference -- a declaration of an untyped module cannot be imported, and every program that compiles this source needs it
+/// <reference path="./utilsBundle.d.ts" />
+import { jpegjs } from "playwright-core/lib/utilsBundle";
+
+import type { Frame } from "../../Frame.ts";
+
+/** A decoded frame: RGBA, `width` pixels a row. */
+export type Picture = ReturnType<typeof jpegjs.decode>;
+
+export const picture = (frame: Frame): Picture => jpegjs.decode(frame.data, { useTArray: true });
+
+/** A sample changed where any color channel moved more than this, beyond JPEG's noise. */
+const noise = 32;
+
+/** The blocks where two pictures differ, by `row * columns + column`; -1 for different sizes. */
+const moved = (from: Picture, to: Picture): ReadonlyArray<number> => {
+  if (from.width !== to.width || from.height !== to.height) return [-1];
+  const columns = Math.ceil(from.width / 16);
+  const counts = new Map<number, number>();
+  const differs = (at: number) => Math.abs((from.data[at] ?? 0) - (to.data[at] ?? 0)) > noise;
+
+  for (let y = 0; y < from.height; y += 2)
+    for (let x = 0; x < from.width; x += 2) {
+      const at = (y * from.width + x) * 4;
+      const block = Math.floor(y / 16) * columns + Math.floor(x / 16);
+
+      if (differs(at) || differs(at + 1) || differs(at + 2))
+        counts.set(block, (counts.get(block) ?? 0) + 1);
+    }
+
+  // At least three changed samples, so a stray one is no motion.
+  return [...counts].flatMap(([block, count]) => (count >= 3 ? [block] : []));
+};
+
+/** The blocks that moved from one picture to the next and their neighbours; none past a resize. */
+export const background = (pictures: ReadonlyArray<Picture>): ReadonlySet<number> => {
+  const columns = Math.ceil((pictures[0]?.width ?? 0) / 16);
+
+  const around = (block: number) =>
+    [-1, 0, 1].flatMap((row) =>
+      [-1, 0, 1]
+        .filter((step) => block >= 0 && (block % columns) + step >= 0)
+        .filter((step) => (block % columns) + step < columns)
+        .map((step) => block + row * columns + step),
+    );
+
+  return new Set(
+    pictures.flatMap((to, index) => moved(pictures[index - 1] ?? to, to).flatMap(around)),
+  );
+};
+
+/** Whether anything moved from one picture to another outside the background. */
+export const stirs = (from: Picture, to: Picture, mask: ReadonlySet<number>) =>
+  moved(from, to).some((block) => !mask.has(block));

package/src/internal/pictures/pictures.ts

@@ -8,9 +8,17 @@ import { Duration, Effect, Option, Schedule, Schema } from "effect";
 
 import { BrowserError, Failed, InvalidRequest } from "../../BrowserError.ts";
 import { Frame, Image, Screenshot } from "../../Frame.ts";
+import type { Point } from "../../Motion.ts";
 import { type FrameOptions, Region, type ScreenshotOptions, Zoom } from "../../Page.ts";
 import { type Bridge, scriptCall } from "../page/bridge.ts";
-import { decodeWith, failWith, type PageContext, reasonOf, undispatched } from "../page/context.ts";
+import {
+  decodeWith,
+  failWith,
+  type PageContext,
+  reasonOf,
+  refuse,
+  undispatched,
+} from "../page/context.ts";
 import type { Viewport } from "../page/viewport.ts";
 import * as Capture from "./capture.ts";
 import * as BrowserClock from "./clock.ts";
@@ -117,9 +125,7 @@ const calibrator = (page: PageContext, bridge: Bridge) => {
       yield* Effect.forEach(
         [1, 2, 3],
         () => Effect.map(probe(contextId), (one) => probes.push(one)),
-        {
-          discard: true,
-        },
+        { discard: true },
       ).pipe(
         within("calibrate", Duration.seconds(2)),
         Effect.catch((error) => (probes.length === 0 ? Effect.fail(error) : Effect.void)),
@@ -219,7 +225,7 @@ const camera = (
     operation: string,
     format: Format,
     quality: number,
-    clip?: Capture.Size & { readonly x: number; readonly y: number; readonly scale: number },
+    clip?: Capture.Size & Point & { readonly scale: number },
   ) =>
     take(operation, format, () =>
       send("Page.captureScreenshot", {
@@ -307,10 +313,7 @@ const reuse =
       const maxAge = millisOf(options.maxAge ?? defaultMaxAge);
 
       if (!(maxAge >= 0))
-        return yield* failWith(
-          operation,
-          new InvalidRequest({ detail: "maxAge must be a duration of zero or more" }),
-        );
+        return yield* refuse(operation, "maxAge must be a duration of zero or more");
       const latest = yield* capture.latest;
       const known = viewport.knownViewport();
       const { activity } = page;
@@ -370,6 +373,14 @@ export const make = Effect.fnUntraced(function* (
     watch: bridge.currentDocument("screencast"),
     frameHistory: settings.frameHistory,
     viewport: Effect.suspend(() => viewport.viewportFor("screencast")),
+    // An uncropped snapshot waits for the restored compositor surface. Its pixels are discarded;
+    // a renderer animation frame or viewport size alone cannot prove the compositor caught up.
+    restore: () =>
+      page.protocol.send("Page.captureScreenshot", {
+        format: "jpeg",
+        quality: 0,
+        optimizeForSpeed: true,
+      }),
     imageSize: jpegSize,
     error,
   });
@@ -467,10 +478,7 @@ export const make = Effect.fnUntraced(function* (
           const size = viewport.knownViewport() ?? (yield* viewport.viewportFor("zoom"));
 
           if (region.x + region.width > size.width || region.y + region.height > size.height)
-            return yield* failWith(
-              "zoom",
-              new InvalidRequest({ detail: "the crop must fit entirely within the viewport" }),
-            );
+            return yield* refuse("zoom", "the crop must fit entirely within the viewport");
           const image = yield* picture("zoom", 80, region);
 
           return new Zoom({ page: id, region, image });
@@ -484,10 +492,7 @@ export const make = Effect.fnUntraced(function* (
 
     return millis > 0 && millis <= Duration.toMillis(Capture.countsKept)
       ? capture.stats(millis)
-      : failWith(
-          "captureStats",
-          new InvalidRequest({ detail: "window must be over zero and at most a minute" }),
-        );
+      : refuse("captureStats", "window must be over zero and at most a minute");
   };
 
   // The browser's clock mapping, measured on this page only while the browser has none, as the

package/src/internal/pictures/utilsBundle.d.ts

@@ -0,0 +1,9 @@
+// What `motion.ts` uses of playwright-core's bundled JPEG decoder, which its untyped entry exports.
+declare module "playwright-core/lib/utilsBundle" {
+  export const jpegjs: {
+    decode(
+      data: Uint8Array,
+      options: { useTArray: true },
+    ): { readonly width: number; readonly height: number; readonly data: Uint8Array };
+  };
+}

package/src/internal/reading/controls.inpage.ts

@@ -3,6 +3,8 @@
  * read to; and a condition `Page.waitFor` waits for. See `names.inpage.ts` for what a page-side part
  * may use.
  */
+import { Schema } from "effect";
+
 import type { Control } from "../../Snapshot.ts";
 import type { Names } from "./names.inpage.ts";
 import type { Subjects } from "./subjects.inpage.ts";
@@ -17,7 +19,7 @@ export interface ConditionRequest {
 }
 
 /** Whether the condition held by the deadline, or why the selector is not CSS. */
-export type ConditionResult = { readonly met: boolean } | { readonly invalid: string };
+export type ConditionResult = typeof ConditionResultSchema.Encoded;
 
 export const controls = (names: Names, walked: Walk, subjects: Subjects, texts: Texts) => {
   const { clean, isDisabled, isHtml, isInput, isSelect, isTextArea, refFor, textOf } = names;
@@ -156,3 +158,8 @@ export const controls = (names: Names, walked: Walk, subjects: Subjects, texts:
 };
 
 export type Controls = ReturnType<typeof controls>;
+
+export const ConditionResultSchema = Schema.Union([
+  Schema.Struct({ met: Schema.Boolean }),
+  Schema.Struct({ invalid: Schema.String }),
+]);

package/src/internal/reading/match.inpage.ts

@@ -10,6 +10,7 @@
  *   its row, column, label or heading. Replay chooses among candidates by the same rule.
  */
 import type { SubjectContext } from "../../BrowserEvent.ts";
+import type { Point } from "../../Motion.ts";
 
 /** A string, or a pattern sent to the page as its source and flags. */
 export type Wanted = string | { readonly source: string; readonly flags: string };
@@ -19,7 +20,7 @@ export interface FindRequest {
   readonly name: Wanted | null;
   readonly text: Wanted | null;
   readonly near: string | null;
-  readonly at: { readonly x: number; readonly y: number } | null;
+  readonly at: Point | null;
   readonly scope: "viewport" | "document";
   readonly firstRef: number;
 }

package/src/internal/reading/outline.inpage.ts

@@ -4,7 +4,7 @@
  */
 import { Schema } from "effect";
 
-import type { Control, Snapshot } from "../../Snapshot.ts";
+import { type Control, Snapshot } from "../../Snapshot.ts";
 import type { addresses } from "../page/url.ts";
 import type { Controls } from "./controls.inpage.ts";
 import type { Names } from "./names.inpage.ts";
@@ -25,9 +25,7 @@ export interface SnapshotRequest {
  * The outline as a `Snapshot` reads it, and the next ref the page may give, or why `within` is not
  * a selector.
  */
-export type SnapshotResult =
-  | { readonly snapshot: typeof Snapshot.Encoded; readonly nextRef: number }
-  | { readonly invalid: string };
+export type SnapshotResult = typeof SnapshotResultSchema.Encoded;
 
 /** The rule every address the library reports goes by, which a link's address goes by too. */
 type Url = ReturnType<typeof addresses>;
@@ -254,6 +252,11 @@ export const outline = (
 
 export type Outline = ReturnType<typeof outline>;
 
+export const SnapshotResultSchema = Schema.Union([
+  Schema.Struct({ snapshot: Snapshot, nextRef: Schema.Finite }),
+  Schema.Struct({ invalid: Schema.String }),
+]);
+
 export const ViewportResultSchema = Schema.Struct({
   width: Schema.Finite,
   height: Schema.Finite,