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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-browser",
-  "version": "0.3.0-beta.15",
+  "version": "0.3.0-beta.19",
   "description": "Effect browser sessions, page control, screencast and moments over Playwright and CDP.",
   "license": "MIT",
   "repository": {

package/src/Browser.ts

@@ -492,7 +492,7 @@ export const make = Effect.fn("Browser.make")(function* (
 ) {
   const clock = yield* Clock.Clock;
   const connection = yield* Identity.make;
-  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  const now = () => BrowserClock.monotonicMillis(clock);
   const { settings, eventHistory, maxPages } = yield* settingsOf(options);
   // Measured on first need: the first capture of any page measures it, and input never waits.
   const mapping = BrowserClock.mapping(now);

package/src/BrowserEvent.ts

@@ -119,8 +119,7 @@ const Button = Schema.Literals(["left", "right", "middle"]);
 
 /** An element's box in viewport CSS pixels; it may lie partly or wholly outside the viewport. */
 export const Box = Schema.Struct({
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Motion.Point.fields,
   width: Schema.Finite,
   height: Schema.Finite,
 });
@@ -169,8 +168,8 @@ export class Action extends Schema.TaggedClass<Action>()("Action", {
   /** For an action at a point, the box of what it found there. */
   box: Schema.optional(Box),
   text: Schema.optional(Schema.String),
-  x: Schema.optional(Schema.Finite),
-  y: Schema.optional(Schema.Finite),
+  x: Schema.optional(Motion.Point.fields.x),
+  y: Schema.optional(Motion.Point.fields.y),
   ok: Schema.Boolean,
   dispatched: Schema.Boolean,
   error: Schema.optional(Schema.String),
@@ -196,16 +195,14 @@ export class TrackPerformed extends Schema.TaggedClass<TrackPerformed>()("TrackP
   page: Schema.String,
   plan: Sequence,
   dispatched: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Motion.Point.fields,
   complete: Schema.Boolean,
 }) {}
 
 export class PointerPressed extends Schema.TaggedClass<PointerPressed>()("PointerPressed", {
   at: Schema.Finite,
   page: Schema.String,
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Motion.Point.fields,
   button: Button,
   clickCount: Schema.Int.check(Schema.isGreaterThan(0)),
 }) {}
@@ -213,8 +210,7 @@ export class PointerPressed extends Schema.TaggedClass<PointerPressed>()("Pointe
 export class PointerReleased extends Schema.TaggedClass<PointerReleased>()("PointerReleased", {
   at: Schema.Finite,
   page: Schema.String,
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Motion.Point.fields,
   button: Button,
   clickCount: Schema.Int.check(Schema.isGreaterThan(0)),
 }) {}
@@ -222,8 +218,7 @@ export class PointerReleased extends Schema.TaggedClass<PointerReleased>()("Poin
 export class WheelScrolled extends Schema.TaggedClass<WheelScrolled>()("WheelScrolled", {
   at: Schema.Finite,
   page: Schema.String,
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Motion.Point.fields,
   dx: Schema.Finite,
   dy: Schema.Finite,
 }) {}

package/src/Moment.ts

@@ -27,11 +27,11 @@
 import { Duration, Effect, Option, Result, Schema } from "effect";
 import { Prompt } from "effect/ai";
 
-import { BrowserError, InvalidRequest } from "./BrowserError.ts";
+import { BrowserError } from "./BrowserError.ts";
 import { type Action, BrowserEvent } from "./BrowserEvent.ts";
 import { type Change, Changes } from "./Change.ts";
 import { Frame } from "./Frame.ts";
-import { undispatched } from "./internal/page/context.ts";
+import { refuse } from "./internal/page/context.ts";
 import { describe, named, quoted, where } from "./internal/timeline/words.ts";
 import type * as Page from "./Page.ts";
 import { Snapshot, type SnapshotOptions } from "./Snapshot.ts";
@@ -116,10 +116,7 @@ export const capture = Effect.fn("Moment.capture")(function* (
   const count = options.frames ?? 2;
 
   if (!Number.isSafeInteger(count) || count < 1)
-    return yield* undispatched(
-      "moment",
-      new InvalidRequest({ detail: "frames must be a positive safe integer" }),
-    );
+    return yield* refuse("moment", "frames must be a positive safe integer");
   const outline = options.snapshot ?? false;
 
   // The picture comes first, at no call with a running screencast, and the window ends at its

package/src/Motion.ts

@@ -13,8 +13,7 @@ export const Point = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
 export type Point = typeof Point.Type;
 
 export const Sample = Schema.Struct({
-  x: Schema.Finite,
-  y: Schema.Finite,
+  ...Point.fields,
   afterMillis: Schema.Finite.check(
     Schema.isGreaterThanOrEqualTo(0),
     Schema.isLessThanOrEqualTo(maximumDurationMillis),

package/src/Page.ts

@@ -19,7 +19,7 @@ import { type Duration, Effect, Schema, type Stream } from "effect";
 import type { Page as PlaywrightPage } from "playwright-core";
 
 import { type BrowserError, type PolicyDenied } from "./BrowserError.ts";
-import { Box, type BrowserEvent, PageLoaded, Subject, SubjectContext } from "./BrowserEvent.ts";
+import { Box, type BrowserEvent, PageLoaded, Subject } from "./BrowserEvent.ts";
 import type { Changes } from "./Change.ts";
 import { type CaptureStats, Frame, Image, type ScreencastOptions } from "./Frame.ts";
 import { FormFieldSchema } from "./internal/input/evidence.inpage.ts";
@@ -27,12 +27,10 @@ import * as Guard from "./internal/input/guard.inpage.ts";
 import { Correlation, FailFast } from "./internal/page/lane.ts";
 import * as Url from "./internal/page/url.ts";
 import type { Window } from "./Moment.ts";
+import * as Motion from "./Motion.ts";
 import { type Snapshot, type SnapshotOptions } from "./Snapshot.ts";
 
-export interface Point {
-  readonly x: number;
-  readonly y: number;
-}
+export type Point = Motion.Point;
 
 /** A ref from a snapshot, such as `"e12"`, or a viewport point. */
 export type Target = string | Point;
@@ -54,13 +52,9 @@ export class Zoom extends Schema.Class<Zoom>("effect-browser/Zoom")({
 
 /** The target as it read before input. Point coordinates are never snapped to another position. */
 export class ResolvedTarget extends Schema.Class<ResolvedTarget>("effect-browser/ResolvedTarget")({
-  point: Schema.Struct({ x: Schema.Finite, y: Schema.Finite }),
+  point: Motion.Point,
+  ...Subject.fields,
   element: Schema.String,
-  /** The element's lowercase tag name. */
-  tag: Schema.String,
-  role: Schema.NullOr(Schema.String),
-  name: Schema.String,
-  context: SubjectContext,
   /** For a point target, the box of what it found there. */
   box: Schema.optional(Box),
   cursor: Schema.String,
@@ -131,9 +125,7 @@ export interface ScreenshotOptions {
   /** The oldest a reused frame may be, as for `frame`. Defaults to 250 milliseconds. */
   readonly maxAge?: Duration.Input | undefined;
   /** A region of the viewport, captured in CSS pixels at the viewport's own scale; always new. */
-  readonly clip?:
-    | { readonly x: number; readonly y: number; readonly width: number; readonly height: number }
-    | undefined;
+  readonly clip?: Box | undefined;
   /** JPEG quality, 0 to 100. Defaults to 80. */
   readonly quality?: number | undefined;
   /** `"jpeg"`, the default, or `"png"`, which is always a new picture. */
@@ -226,8 +218,11 @@ export interface WaitCondition {
 }
 
 export interface ReadyOptions {
-  /** What must stay still during quietMillis: screen paint (default), or recorded content. */
-  readonly still?: "screen" | "content" | undefined;
+  /**
+   * What must stay still during quietMillis: screen paint (default); recorded content; or the
+   * `"foreground"`, the screen but for what was already moving before the page's latest input.
+   */
+  readonly still?: "screen" | "content" | "foreground" | undefined;
   /** How long the selected evidence must stay still; screen paint by default. */
   readonly quietMillis?: number | undefined;
   readonly timeout?: Duration.Input | undefined;
@@ -335,7 +330,7 @@ export class InputRequest extends Schema.Class<InputRequest>("effect-browser/Inp
   target: Schema.optional(Schema.String),
   element: Schema.optional(Schema.String),
   /** Literal pixel targets only; ref coordinates are resolved after the policy allows them. */
-  point: Schema.optional(Schema.Struct({ x: Schema.Finite, y: Schema.Finite })),
+  point: Schema.optional(Motion.Point),
   text: Schema.optional(Schema.String),
   role: Schema.optional(Schema.NullOr(Schema.String)),
   name: Schema.optional(Schema.String),
@@ -497,9 +492,12 @@ export interface Page {
    * view have loaded, and the viewport shows something. With `quietMillis`, the screen must then
    * also stay still that long: nothing in view changed, where the page's changes are recorded, and
    * no frame comes, counted from the first frame of a capture the wait starts itself. A canvas
-   * that keeps drawing, such as a live chart, is never still, and a page
-   * is never ready without a painted frame, as a hidden tab may be. `Timeout` after `timeout`,
-   * 15 seconds by default.
+   * that keeps drawing, such as a live chart, is never still. With `still: "foreground"`, frames
+   * may keep coming, but nothing may move in them outside what moved in the frames of the 1.5 s
+   * before the page's latest input, such as an idle animation; reels set spinning, or a counter
+   * set rolling, by the input keep the wait going. Without those frames, as where they are older
+   * than the browser's `frameHistory`, nothing may move at all. A page is never ready without a
+   * painted frame, as a hidden tab may be. `Timeout` after `timeout`, 15 seconds by default.
    */
   readonly ready: (options?: ReadyOptions) => Effect.Effect<void, BrowserError>;
 

package/src/Plan.ts

@@ -33,6 +33,7 @@ import {
 } from "./BrowserEvent.ts";
 import { undispatched } from "./internal/page/context.ts";
 import { Ambiguous, choose, Drifted, Missing } from "./internal/reading/choose.ts";
+import { Point as ViewportPoint } from "./Motion.ts";
 import {
   type Found,
   type Page,
@@ -44,8 +45,6 @@ import {
 
 export { Ambiguous, Drifted, Missing } from "./internal/reading/choose.ts";
 
-const ViewportPoint = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
-
 export const StepAction = Schema.Literals([
   "navigate",
   "back",

package/src/Presentation.ts

@@ -20,6 +20,7 @@ import { Clock, Duration, Effect, Fiber, MutableRef, Option, Semaphore } from "e
 import type { BrowserError } from "./BrowserError.ts";
 import * as Style from "./internal/input/style.ts";
 import { type Internals, internalsOf, viewOf } from "./internal/page/page.ts";
+import { monotonicMillis } from "./internal/pictures/clock.ts";
 import * as Motion from "./Motion.ts";
 import type { Page, Point, Target } from "./Page.ts";
 
@@ -81,7 +82,7 @@ export const make = Effect.fn("Presentation.make")(function* (options: Options =
   const pacing = options.pacing ?? human;
   const clock = yield* Clock.Clock;
   const scope = yield* Effect.scope;
-  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  const now = () => monotonicMillis(clock);
   const pointer = MutableRef.make(Option.none<Point>());
   const hand = yield* Semaphore.make(1);
 

package/src/Stage.ts

@@ -24,8 +24,9 @@ import {
 
 import { type BrowserError, Closed, consequence, InvalidRequest, Timeout } from "./BrowserError.ts";
 import type { CaptureStats, Frame, ScreencastOptions } from "./Frame.ts";
-import { failWith, undispatched } from "./internal/page/context.ts";
+import { failWith, refuse, undispatched } from "./internal/page/context.ts";
 import { internalsOf } from "./internal/page/page.ts";
+import { monotonicMillis } from "./internal/pictures/clock.ts";
 import type { Page } from "./Page.ts";
 
 export interface Options extends ScreencastOptions {
@@ -239,16 +240,14 @@ const evidence = (
 
       const probe = Effect.gen(function* () {
         yield* until(Math.max(checkedAt, current()?.changedAt ?? checkedAt) + millis, now);
-        checkedAt = now();
         const before = current();
         const frame = before?.frame;
 
-        if (
-          before === undefined ||
-          frame === undefined ||
-          gone === before.feed ||
-          checkedAt - before.changedAt < millis
-        )
+        // Paint during the wait moves the deadline; an early wake is not a silence check.
+        if (before !== undefined && now() - before.changedAt < millis)
+          return Option.none<Evidence>();
+        checkedAt = now();
+        if (before === undefined || frame === undefined || gone === before.feed)
           return Option.none<Evidence>();
         const { feed } = before;
 
@@ -390,7 +389,7 @@ export const make = Effect.fn("Stage.make")(function* (
 ): Effect.fn.Return<Stage, BrowserError, Scope.Scope> {
   const clock = yield* Clock.Clock;
   const owner = yield* Effect.scope;
-  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  const now = () => monotonicMillis(clock);
   const waited = Duration.fromInput(options.firstFrame ?? Duration.seconds(5));
 
   if (
@@ -398,10 +397,7 @@ export const make = Effect.fn("Stage.make")(function* (
     !Duration.isFinite(waited.value) ||
     !Duration.isPositive(waited.value)
   )
-    return yield* failWith(
-      "stage",
-      new InvalidRequest({ detail: "firstFrame must be a finite positive duration" }),
-    );
+    return yield* refuse("stage", "firstFrame must be a finite positive duration");
   const firstFrame = waited.value;
   const settings = { quality: options.quality, size: options.size };
   const output = yield* PubSub.sliding<Paint>(16);
@@ -433,10 +429,7 @@ export const make = Effect.fn("Stage.make")(function* (
       return switching(
         Effect.gen(function* () {
           if (!Number.isFinite(asked))
-            return yield* failWith(
-              "cue",
-              new InvalidRequest({ detail: "at must be finite host milliseconds" }),
-            );
+            return yield* refuse("cue", "at must be finite host milliseconds");
           yield* firstOf(feed, firstFrame);
           const old = showing;
 

package/src/Supervisor.ts

@@ -107,7 +107,8 @@ export interface Admission {
 /**
  * Optional service supplied during `open`. Providers report failed-attempt cleanup here before
  * their scope closes; successful generations instead return `Opened.release`. Reporting does
- * not release resources or replace the original acquisition failure.
+ * not release resources or replace the original acquisition failure. Terminal `Down` and opening
+ * `Closed` states publish the reported outcomes of their own generation's tries.
  */
 export class Releasing extends Context.Service<
   Releasing,
@@ -556,7 +557,7 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
         return yield* options.open.pipe(
           Effect.provideService(Releasing, {
             released: (released) =>
-              apply({ _tag: "AttemptReleased", released }).pipe(Effect.asVoid),
+              apply({ _tag: "AttemptReleased", number, released }).pipe(Effect.asVoid),
           }),
         );
       }),
@@ -597,21 +598,20 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
 
   const retire = yield* Effect.cached(stop({ _tag: "Retire" }));
 
+  // The browser of the generation serving, or of the one `target` names once it serves.
+  const browserOf = (target?: number) =>
+    Effect.map(waitFor(state, waitTimeout, clock, target), (live) => live.value.opened.browser);
+
   yield* Effect.addFinalizer(() => (options.keep === true ? stop({ _tag: "Keep" }) : retire));
   yield* perform(started);
 
   return {
-    browser: Effect.map(waitFor(state, waitTimeout, clock), (live) => live.value.opened.browser),
+    browser: browserOf(),
     use: leasing(state, apply, waitTimeout, now, clock),
     states: Stream.fromPubSubTake(events),
     rotate: apply({ _tag: "Rotate" }).pipe(
       Effect.flatMap(({ reply }) =>
-        reply === undefined
-          ? Effect.fail(retired())
-          : Effect.map(
-              waitFor(state, waitTimeout, clock, reply),
-              (live) => live.value.opened.browser,
-            ),
+        reply === undefined ? Effect.fail(retired()) : browserOf(reply),
       ),
     ),
     retire,