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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-browser",
-  "version": "0.3.0-beta.13",
+  "version": "0.3.0-beta.14",
   "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(

package/src/Supervisor.ts

@@ -92,9 +92,21 @@ export interface Opened<A = void> {
   readonly release?: Effect.Effect<Lifecycle.Released> | undefined;
 }
 
+/** Facts available before an acquisition attempt; awaiting `after` never changes release order. */
+export interface Admission {
+  readonly number: number;
+  /**
+   * The preceding generation's release once it stops serving. Undefined on the first open and
+   * while a nonexclusive rotation keeps it serving; checked again before each retry.
+   */
+  readonly after: Effect.Effect<Lifecycle.Released> | undefined;
+}
+
 export interface Options<E, R, A = void> {
   /** Opens one generation in the scope it is given. */
   readonly open: Effect.Effect<Opened<A>, E, R>;
+  /** Runs before every open attempt, including the first; failures follow `reopen` and `definite`. */
+  readonly admit?: ((opening: Admission) => Effect.Effect<void, E, R>) | undefined;
   /** When to try a failed open again. Defaults to exponential from 1 second, for 5 minutes. */
   readonly reopen?: Schedule.Schedule<unknown, E> | undefined;
   /**
@@ -132,6 +144,8 @@ export interface Lease<A> {
   readonly generation: number;
   readonly browser: Browser.Service;
   readonly value: A;
+  /** Declare this serving generation unusable and revoke it now; stale declarations do nothing. */
+  readonly lose: (detail: string) => Effect.Effect<void>;
   /** First notice that serving ended; loss or retirement may revoke before its deadline. */
   readonly ending: Effect.Effect<Superseded>;
   /** An independent scope; its resources close before provider release. Fails once revoked. */
@@ -167,6 +181,7 @@ interface Held<A> {
   readonly opened: Opened<A>;
   readonly ending: Deferred.Deferred<Superseded>;
   readonly revoked: Deferred.Deferred<Superseded>;
+  readonly released: Deferred.Deferred<Lifecycle.Released>;
   readonly scope: Scope.Closeable;
 }
 
@@ -175,6 +190,9 @@ type Apply<A> = (
   input: Lifecycle.Input<Held<A>, Hold>,
 ) => Effect.Effect<Lifecycle.Step<Held<A>, Hold>>;
 
+const superseded = (generation: number, { reason, revokeAt }: Lifecycle.Draining) =>
+  new Superseded({ generation, reason, revokeAt });
+
 const retired = () => new Unavailable({ reason: "retired", detail: "the supervisor was retired" });
 
 const describe = (cause: Cause.Cause<unknown>) => {
@@ -278,6 +296,8 @@ const leasing = <A>(
     generation: live.number,
     browser: live.value.opened.browser,
     value: live.value.opened.value,
+    lose: (detail) =>
+      apply({ _tag: "Lost", number: live.number, cause: "declared", detail }).pipe(Effect.asVoid),
     ending: Deferred.await(live.value.ending),
     retain: Effect.uninterruptible(
       Effect.gen(function* () {
@@ -310,9 +330,18 @@ const leasing = <A>(
           apply({ _tag: "Let", number: live.number, hold }).pipe(Effect.asVoid),
         );
 
+        const revoked = Deferred.await(live.value.revoked).pipe(Effect.flatMap(Effect.fail));
+
         return yield* Effect.raceFirst(
-          work(leaseOf(live)),
-          Deferred.await(live.value.revoked).pipe(Effect.flatMap(Effect.fail)),
+          work(leaseOf(live)).pipe(
+            // Declaring loss and returning can finish before the race's other fiber runs.
+            Effect.tap(() =>
+              Deferred.isDone(live.value.revoked).pipe(
+                Effect.flatMap((done) => (done ? revoked : Effect.void)),
+              ),
+            ),
+          ),
+          revoked,
         );
       }),
     );
@@ -338,6 +367,7 @@ const acquireGeneration = <A, E, R>(
           scope,
           ending: Deferred.makeUnsafe<Superseded>(),
           revoked: Deferred.makeUnsafe<Superseded>(),
+          released: Deferred.makeUnsafe<Lifecycle.Released>(),
         })),
       ),
     ),
@@ -369,23 +399,14 @@ const watchGeneration = <A>(
   return Effect.all([loss, rotation], { concurrency: 2, discard: true });
 };
 
-// Revocation stops use work; retained resources and use finalizers let go before the provider.
+// After revocation, retained resources and use finalizers let go before the provider.
 const releaseGeneration = <A>(
   command: Extract<Lifecycle.Command<Held<A>>, { readonly _tag: "Release" | "Leave" }>,
   state: SubscriptionRef.SubscriptionRef<State<A>>,
   apply: Apply<A>,
 ) =>
   Effect.gen(function* () {
-    const { live, ending } = command;
-
-    yield* Deferred.succeed(
-      live.value.revoked,
-      new Superseded({
-        generation: live.number,
-        reason: ending.reason,
-        revokeAt: ending.revokeAt,
-      }),
-    );
+    const { live } = command;
     const holds = Lifecycle.lookup(state.value, live.number)?.holds ?? [];
 
     const cleaned = yield* Effect.forEach(
@@ -414,9 +435,25 @@ const releaseGeneration = <A>(
     const closed = yield* Effect.exit(Scope.close(live.value.scope, Exit.void));
 
     yield* apply({ _tag: "Released", number: live.number, released });
+    if (released !== undefined) yield* Deferred.succeed(live.value.released, released);
     yield* Exit.asVoidAll([...cleaned, closed]);
   });
 
+const openedInput = <A, E>(
+  number: number,
+  exit: Exit.Exit<Held<A>, E>,
+): Lifecycle.Input<Held<A>, Hold> =>
+  Exit.isSuccess(exit)
+    ? { _tag: "Opened", live: { number, value: exit.value } }
+    : Cause.hasInterruptsOnly(exit.cause)
+      ? { _tag: "Abandoned", number }
+      : { _tag: "Failed", number, detail: describe(exit.cause), cause: Cause.squash(exit.cause) };
+
+const admissionAfter = <A>(previous: Lifecycle.Live<Held<A>> | undefined, state: State<A>) =>
+  previous === undefined || (state._tag !== "Retired" && state.serving?.number === previous.number)
+    ? undefined
+    : Deferred.await(previous.value.released);
+
 const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
   options: MakeOptions<E, R, A>,
 ): Effect.fn.Return<Supervisor<A | void>, never, Scope.Scope | Exclude<R, Scope.Scope>> {
@@ -489,11 +526,7 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
             );
             break;
           case "Drain": {
-            const ending = new Superseded({
-              generation: command.live.number,
-              reason: command.ending.reason,
-              revokeAt: command.ending.revokeAt,
-            });
+            const ending = superseded(command.live.number, command.ending);
 
             yield* Deferred.succeed(command.live.value.ending, ending);
             yield* Effect.forkIn(
@@ -508,40 +541,39 @@ const makeScoped = Effect.fn("Supervisor.make")(function* <E, R, A>(
           }
           case "Release":
           case "Leave":
+            yield* Deferred.succeed(
+              command.live.value.revoked,
+              superseded(command.live.number, command.ending),
+            );
             runRelease(command.live.number, releaseGeneration(command, state, apply));
             break;
         }
     });
 
-  const openOnce = acquireGeneration(options.open, own).pipe(Effect.provideContext(context));
+  const openGeneration = (number: number, previous: Lifecycle.Live<Held<A | void>> | undefined) => {
+    const after = previous === undefined ? undefined : Deferred.await(previous.value.released);
+
+    const openOnce = acquireGeneration(
+      Effect.suspend(
+        () =>
+          options.admit?.({ number, after: admissionAfter(previous, state.value) }) ?? Effect.void,
+      ).pipe(Effect.andThen(options.open)),
+      own,
+    ).pipe(Effect.provideContext(context));
 
-  const openGeneration = (number: number, after: number | undefined) =>
-    Effect.uninterruptibleMask((restore) =>
+    return Effect.uninterruptibleMask((restore) =>
       restore(
-        (after === undefined
-          ? Effect.void
-          : changedUntil(state, (current) => !current.draining.has(after))
-        ).pipe(
+        (exclusive && after !== undefined ? after : Effect.void).pipe(
           Effect.andThen(
             Effect.retry(openOnce, { schedule: reopen, while: (error) => !definite(error) }),
           ),
         ),
       ).pipe(
         Effect.exit,
-        Effect.flatMap((exit) =>
-          Exit.isSuccess(exit)
-            ? apply({ _tag: "Opened", live: { number, value: exit.value } })
-            : Cause.hasInterruptsOnly(exit.cause)
-              ? apply({ _tag: "Abandoned", number })
-              : apply({
-                  _tag: "Failed",
-                  number,
-                  detail: describe(exit.cause),
-                  cause: Cause.squash(exit.cause),
-                }),
-        ),
+        Effect.flatMap((exit) => apply(openedInput(number, exit))),
       ),
     );
+  };
 
   const use = leasing(state, apply, waitTimeout, now, clock);