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

package/package.json

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

package/src/Frame.ts

@@ -93,10 +93,8 @@ export class CaptureStats extends Schema.Class<CaptureStats>("effect-browser/Cap
    */
   foreignSize: Count,
   /**
-   * Frames dropped because they may have been painted, or arrived, while the library took a clipped
-   * or scaled picture of the page, such as a zoom: Chromium draws those into the screencast too.
-   * Where Playwright emulates the viewport, the page's own frames from that time are among them; a
-   * crop on the page's own session leaves out only frames of another size than the page's.
+   * Frames discarded while native capture is paused for a library picture and its restoration.
+   * A pause can produce no callbacks, so this count may remain zero even when pictures were taken.
    */
   duringPictures: Count,
   /**

package/src/Moment.ts

@@ -19,8 +19,8 @@
  * part it could not read, which it names with why.
  *
  * Frames come from a running screencast, as far back as the browser's `frameHistory` keeps them.
- * A moment's picture is the newest frame if it was painted after the page's latest input and at
- * most 250 ms ago, else a new screenshot timed by its capture.
+ * A moment's picture is the newest frame if it was painted after the page's latest input and
+ * completed action, at most 250 ms ago, else a new screenshot timed by its capture.
  *
  * @since 0.3.0
  */
@@ -98,6 +98,17 @@ const spread = (frames: ReadonlyArray<Frame>, count: number): ReadonlyArray<Fram
   );
 };
 
+// An action ends after its navigation settles, which can follow the last paint. A fresh picture
+// keeps that completed action inside the moment without moving events between adjacent windows.
+const pictureOf = Effect.fnUntraced(function* (page: Page.Page) {
+  const frame = yield* page.frame({ after: "input" });
+  const events = yield* page.recentEvents;
+
+  return events.some((event) => event._tag === "Action" && event.at > frame.hostTime)
+    ? yield* page.frame({ maxAge: 0 })
+    : frame;
+});
+
 export const capture = Effect.fn("Moment.capture")(function* (
   page: Page.Page,
   options: CaptureOptions = {},
@@ -116,7 +127,7 @@ export const capture = Effect.fn("Moment.capture")(function* (
   // outline is taken alongside. What cannot be read is missing from the moment, not its end.
   const { pictured, outlined } = yield* Effect.all(
     {
-      pictured: Effect.result(page.frame({ after: "input" })).pipe(
+      pictured: Effect.result(pictureOf(page)).pipe(
         Effect.flatMap((picture) =>
           Effect.map(
             page.window({

package/src/Plan.ts

@@ -7,7 +7,7 @@
  * as a named input slot, never the text itself. A navigation to an address whose credentials the
  * events withheld is an input slot too, so replay goes where the caller says, or nowhere, and
  * never to the address without them. `replay` takes the steps in turn. Before a step
- * that acts on the page, it waits for `Page.ready`; then it finds the one element the step's
+ * except an opening navigate, back or reload, it waits for `Page.ready`; then it finds the element its
  * subject names, by role and name among those that repeat all its recorded context, and acts on
  * it. Text typed into focus was typed into the focused field, which replay finds the same way, and
  * text typed into a secret field goes into nothing else. An element step never falls back to
@@ -382,7 +382,7 @@ const dispatch = (
 };
 
 export interface TakeOptions {
-  /** How each step waits for the page first, or false not to wait. */
+  /** How each step waits first, except an opening navigation, or false. No final-step wait. */
   readonly settle?: ReadyOptions | false | undefined;
   readonly inputs?: Readonly<Record<string, string>> | undefined;
   /**
@@ -527,9 +527,11 @@ export const take = Effect.fn("Plan.take")(function* (
       (unresolved || (expected !== undefined && "durable" in expected && expected.durable === true))
     )
       return yield* uncertain;
-    const settle = options.settle === false ? Effect.void : page.ready(options.settle);
-
-    if (!["navigate", "back", "reload"].includes(step.action)) yield* settle;
+    if (
+      options.settle !== false &&
+      (index > 0 || !["navigate", "back", "reload"].includes(step.action))
+    )
+      yield* page.ready(options.settle);
     const before = plan.steps[index - 1]?.url;
 
     if (before !== undefined)
@@ -551,7 +553,6 @@ export const take = Effect.fn("Plan.take")(function* (
 
     const receipt = (outcome: Receipt["outcome"]) =>
       Effect.gen(function* () {
-        if (index === plan.steps.length - 1) yield* settle;
         yield* arrived(page, [step.url], millis);
         const now = yield* page.state;
 

package/src/Stage.ts

@@ -50,9 +50,9 @@ export interface Cue {
   }) => Effect.Effect<Presented, BrowserError>;
 }
 
-/** What the output establishes about its last image; loss ends this page's evidence. */
+/** What the output establishes at nondecreasing host times; frames retain their capture times. */
 export type Shown =
-  | { readonly _tag: "Painted"; readonly frame: Frame }
+  | { readonly _tag: "Painted"; readonly frame: Frame; readonly at: number }
   | { readonly _tag: "Still"; readonly frame: Frame; readonly at: number }
   | { readonly _tag: "Stalled"; readonly frame: Frame; readonly at: number }
   | { readonly _tag: "Gone"; readonly page: string; readonly at: number };
@@ -65,7 +65,7 @@ export interface Stage {
   readonly cue: (page: Page) => Effect.Effect<Cue, BrowserError, Scope.Scope>;
   /** Paint and, after every finite positive hold without paint, current evidence or loss. */
   readonly shown: (options: { readonly hold: Duration.Input }) => Stream.Stream<Shown>;
-  /** Current-page paint; a reader more than 16 frames behind loses the oldest. */
+  /** Capture-timed current-page paint; use `shown` for output time. Readers retain 16 frames. */
   readonly frames: Stream.Stream<Frame>;
   readonly current: Effect.Effect<Option.Option<Page>>;
   readonly stats: (options?: {
@@ -87,9 +87,17 @@ interface Feed {
 interface Paint {
   readonly feed: Feed;
   readonly frame: Frame;
+  readonly at: number;
 }
 
-const closed = () => undispatched("cue", new Closed({ cause: "released" }));
+interface Evidence {
+  readonly feed: Feed;
+  readonly frame: Frame;
+  readonly value: Shown;
+}
+
+const unavailable = () =>
+  undispatched("cue", new InvalidRequest({ detail: "the cue's capture is no longer available" }));
 
 /** The sole writer of a cue's capture lifecycle; presentation ownership belongs to the stage. */
 const update = (
@@ -131,13 +139,13 @@ const ended = (feed: Feed): Effect.Effect<never, BrowserError> =>
         Effect.flatMap((exit) =>
           Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)
             ? Effect.failCause(exit.cause)
-            : Effect.fail(closed()),
+            : Effect.fail(unavailable()),
         ),
       );
 
 const firstOf = (feed: Feed, wait: Duration.Duration) =>
   Effect.suspend(() => {
-    if (feed.state._tag === "Stopped") return Effect.fail(closed());
+    if (feed.state._tag === "Stopped") return Effect.fail(unavailable());
     if (feed.page.playwright.isClosed()) return failWith("cue", new Closed({ cause: "page" }));
     if (frameOf(feed) !== undefined) return Effect.void;
 
@@ -225,6 +233,8 @@ const evidence = (
         throw new RangeError("shown hold must be a finite positive duration");
       const millis = Duration.toMillis(parsed.value);
       let checkedAt = now();
+      let shownAt = Number.NEGATIVE_INFINITY;
+      let seen: Pick<Paint, "feed" | "frame"> | undefined = current();
       let gone: Feed | undefined;
 
       const probe = Effect.gen(function* () {
@@ -239,37 +249,67 @@ const evidence = (
           gone === before.feed ||
           checkedAt - before.changedAt < millis
         )
-          return Option.none<Shown>();
+          return Option.none<Evidence>();
         const { feed } = before;
 
         const confirmed = yield* Effect.result(confirm(feed, frame));
 
-        if (current()?.feed !== feed || current()?.frame !== frame) return Option.none<Shown>();
+        if (current()?.feed !== feed || current()?.frame !== frame) return Option.none<Evidence>();
         const at = now();
 
         checkedAt = at;
         if (Result.isFailure(confirmed) && consequence(confirmed.failure).lost !== "nothing") {
-          gone = feed;
-
-          return Option.some<Shown>({ _tag: "Gone", page: feed.page.id, at });
+          return Option.some<Evidence>({
+            feed,
+            frame,
+            value: { _tag: "Gone", page: feed.page.id, at },
+          });
         }
 
-        return Option.some<Shown>({
-          _tag: Result.isSuccess(confirmed) && confirmed.success ? "Still" : "Stalled",
+        return Option.some<Evidence>({
+          feed,
           frame,
-          at,
+          value: {
+            _tag: Result.isSuccess(confirmed) && confirmed.success ? "Still" : "Stalled",
+            frame,
+            at,
+          },
         });
       });
 
       return Stream.merge(
         Stream.fromPubSub(output).pipe(
-          Stream.filter(({ feed }) => gone !== feed),
-          Stream.map(({ frame }): Shown => ({ _tag: "Painted", frame })),
+          Stream.map(({ feed, frame, at }): Evidence => ({
+            feed,
+            frame,
+            value: { _tag: "Painted", frame, at },
+          })),
         ),
         Stream.fromEffectRepeat(probe).pipe(
           Stream.filter(Option.isSome),
           Stream.map(({ value }) => value),
         ),
+      ).pipe(
+        // A probe can overtake queued paint while its reader is paused. It establishes nothing
+        // about that reader's output until the matching frame has reached it.
+        Stream.filter(({ feed, frame, value }) => {
+          if (value._tag === "Painted" && gone !== feed) {
+            seen = { feed, frame };
+
+            return true;
+          }
+          // The subscription may have begun after its first publication.
+          seen ??= { feed, frame };
+
+          return value._tag !== "Painted" && seen?.feed === feed && seen.frame === frame;
+        }),
+        Stream.map(({ feed, value }) => {
+          if (value._tag === "Gone") gone = feed;
+          // A frame captured before a silence probe can arrive after the probe's evidence.
+          shownAt = Math.max(shownAt, value.at);
+
+          return value.at === shownAt ? value : { ...value, at: shownAt };
+        }),
       );
     }),
   );
@@ -375,15 +415,15 @@ export const make = Effect.fn("Stage.make")(function* (
 
   yield* Effect.addFinalizer(() => PubSub.shutdown(output));
 
-  const publish = (feed: Feed, frame: Frame) =>
+  const publish = (feed: Feed, frame: Frame, at = frame.hostTime) =>
     Effect.suspend(() => {
-      painted = Math.max(painted, frame.hostTime);
+      painted = Math.max(painted, at);
       if (showing !== undefined) {
         showing.changedAt = now();
         showing.frame = frame;
       }
 
-      return PubSub.publish(output, { feed, frame });
+      return PubSub.publish(output, { feed, frame, at: painted });
     });
 
   const commit = (feed: Feed, options: { readonly at?: number | undefined } = {}) =>
@@ -407,7 +447,7 @@ export const make = Effect.fn("Stage.make")(function* (
           const switchTo = Effect.suspend(() => {
             const frame = frameOf(feed);
 
-            if (frame === undefined) return Effect.fail(closed());
+            if (frame === undefined) return Effect.fail(unavailable());
             const at = Math.max(now(), asked, frame.hostTime, painted);
 
             showing = {
@@ -417,7 +457,7 @@ export const make = Effect.fn("Stage.make")(function* (
               changedAt: at,
             };
 
-            return publish(feed, frame).pipe(Effect.as(showing.presented));
+            return publish(feed, frame, at).pipe(Effect.as(showing.presented));
           }).pipe(Effect.uninterruptible);
 
           const readyToSwitch = firstOf(feed, firstFrame).pipe(