effect-browser 0.3.0-beta.7 → 0.3.0-beta.8

package/README.md

@@ -702,25 +702,93 @@ its first glide starts mid-viewport, and each later one where the one before end
 input on another tab does meanwhile. Every sent move updates the position, including a partially
 cancelled glide. A later viewport clamps the starting point to its bounds if necessary.
 
-`Supervisor.make` keeps a browser open across losses and session ends, as generations, each a new
-browser from the provider's `open`. Opens run in the supervisor's own scope, so a caller that stops
-waiting never interrupts a half-open browser. `browser` gives the current generation, waiting up to
-`waitTimeout` while one opens. A lost browser is published at once, `Lost` with its browser's
-`disconnected` cause, and the next one opens on the `reopen` schedule, which also retries a failed
-open until it gives up, unless the provider deems the failure `definite`, such as a refused key:
-then the generation is `Down` at once, with its cause, which `Unavailable` also gives anyone
-waiting, because a schedule would only hide a configuration error. `rotate`, or the time
-`rotateBefore` ahead of a generation's browser's `expiresAt`, opens the next generation before it
-releases the current one, unless generations are `exclusive`: then the current one is released
-first.
-`retire` stops reopening at once and releases what is open, asking the provider's `release` before
-it closes a generation's scope; closing the scope retires too, unless the supervisor `keep`s: then
-the generation serving is left running, `Kept`, its scope closed but its provider never asked to
-release it, for a provider whose scope only disconnects. `states` streams each generation's
-`Opening`, `Reopening`, `Open`, `Lost`, `Down`, `Closed`, the last with the provider's release
-outcome, `Settled` or `Unconfirmed`, and `Kept`, so time open is a subtraction of their stamps.
-Pages don't carry over from one generation to the next. `effect-browserbase`'s
-`Browserbase.supervise` supervises hosted sessions, and with `keep` adopts the one it kept.
+## Supervising browser generations
+
+`Supervisor.make` keeps a browser open across losses and session ends. Its `open` builds each
+generation in a scope of its own and can return `{ browser, value }`: the application's pages,
+tools or other resources belong to that generation. A caller that stops waiting never interrupts
+the shared acquisition. Browser-only providers can continue returning `{ browser }`, with a
+`void` value. Pages and values do not carry over when a new generation opens.
+
+```ts
+import { Effect } from "effect";
+import * as Chromium from "effect-browser/Chromium";
+import * as Supervisor from "effect-browser/Supervisor";
+
+const program = Effect.gen(function* () {
+  const browsers = yield* Supervisor.make({
+    open: Effect.gen(function* () {
+      const browser = yield* Chromium.open();
+      const page = yield* browser.firstPage;
+
+      return { browser, value: page };
+    }),
+  });
+  return yield* browsers.use(({ value: page }) => page.snapshot());
+});
+```
+
+`use(work, { wait })` atomically borrows the serving generation and runs `work` in a scope of its
+own. The lease gives its `generation`, `browser`, `value`, an `ending` notice and `retain`.
+`wait` defaults to `waitTimeout` (two minutes); zero either borrows immediately or fails
+`Unavailable`. Cancelling the caller closes its work scope and lets its hold go. Ordinary work
+errors stay ordinary work errors. `browser` still returns an unheld browser: use it only when the
+caller can tolerate that generation being released underneath it.
+
+A retained scope transfers a hold beyond the `use` call. Acquire anything that must travel with
+that hold in its scope, and close it when the receiver is finished. Within a scoped program with
+`browsers` as above and `Exit` and `Scope` imported from `effect`:
+
+```ts
+const prepared =
+  yield *
+  browsers.use((lease) =>
+    Effect.gen(function* () {
+      const hold = yield* lease.retain;
+      const page = yield* Effect.acquireRelease(lease.browser.newPage(), (page) =>
+        page.close.pipe(Effect.ignore),
+      ).pipe(Scope.provide(hold));
+
+      return { page, hold, ending: lease.ending };
+    }),
+  );
+// Hand `prepared` to its next owner; that owner eventually lets it go.
+yield * Scope.close(prepared.hold, Exit.void);
+```
+
+Rotation publishes `Draining` for the outgoing generation. It stays alive until its last hold
+closes or `handover` expires, 30 seconds by default. `ending` is the first notice that it stopped
+serving, with a `Superseded` reason and monotonic `revokeAt`; loss or retirement can revoke sooner.
+At revocation, `use` interrupts work still running, waits for its finalizers and fails
+`Superseded`. New `retain` calls refuse a revoked or releasing generation, and a retained scope
+cannot extend the deadline. Retained scopes and work scopes close before the provider's
+`release`; the generation's own scope closes last. Cleanup can therefore extend the time taken to
+finish revocation. `Superseded` does not say whether an input reached the site: use the action's
+receipt and plan stopping point to resolve that uncertainty.
+
+Nonexclusive `rotate`, including `rotateBefore` timed rotation, opens the next generation while
+old holds drain. Handover does not delay later rotations; multiple old generations can remain
+owned, so the consumer chooses its rotation and overlap budget. Calls share one acquisition in
+progress. Under `exclusive`, the current generation drains and finishes its provider release
+before acquisition starts. Call `rotate` outside `use` for a clean cut: an exclusive rotation
+inside `use` waits for its own hold to end or be revoked.
+
+A loss publishes `Lost` with the browser's `disconnected` cause and revokes its holds immediately.
+It reopens on `reopen`, which also retries an open failure until the schedule ends. A provider's
+`definite` failure goes `Down` at once, with the cause also available through `Unavailable`.
+`retire` revokes immediately, stops acquisition and waits for every generation to release.
+Closing the supervisor's scope does the same unless `keep` is set: then only the serving
+generation skips provider release, `Kept`; its application scopes still close. Other generations
+are released normally.
+
+`states` streams `Opening`, `Reopening`, `Open`, `Draining`, `Lost`, `Down`, `Closed` and `Kept`.
+`Closed.released` preserves `Settled` or `Unconfirmed`; the latter does not establish that a
+provider stopped the browser or its billing. `Generation.at` is wall-clock epoch milliseconds;
+`hostTime` and `revokeAt` are host monotonic milliseconds from the supervisor's Effect `Clock`.
+They can be compared with browser event and frame times when those use that same clock and host,
+not across processes or against a provider's wall-clock timestamps. A generation event is
+lifetime evidence, not proof that a frame was shown. `Browserbase.supervise` supplies hosted
+generations and, with `keep`, can adopt one it previously kept.
 
 Every module is also an entry point, such as `effect-browser/Page`. The
 [repository README](https://github.com/mannyc2/effect-agent-browserbase#readme) has examples.

package/dist/{Supervisor-CLJaT7rG.d.mts → Supervisor-CYWFK3vM.d.mts}

@@ -2,7 +2,7 @@ import { c as DisconnectCause } from "./BrowserEvent-BRu2juEz.mjs";
 import { Service, t as Browser_d_exports } from "./Browser.mjs";
 import { Cause, Duration, Effect, Schedule, Schema, Scope, Stream } from "effect";
 declare namespace lifecycle_d_exports {
-  export { Closed, Command, Down, GenerationState, Input, Kept, Live, Lost, Open, Opening, Released, Reopening, Resolution, Settled, State, Step, Unconfirmed, resolve, start, transition };
+  export { Closed, Command, Down, Drain, Draining, GenerationState, Held, Input, Kept, Live, Lost, Open, Opening, Released, Reopening, Resolution, Settled, State, Step, Unconfirmed, lookup, resolve, start, transition };
 }
 declare const Settled_base: Schema.Class<Settled, Schema.TaggedStruct<"Settled", {}>, {}>;
 /** The provider confirmed that the generation's browser ended. */
@@ -23,6 +23,12 @@ declare class Reopening extends Reopening_base {}
 declare const Open_base: Schema.Class<Open, Schema.TaggedStruct<"Open", {}>, {}>;
 /** Open: `browser` gives this generation until the next one opens. */
 declare class Open extends Open_base {}
+declare const Draining_base: Schema.Class<Draining, Schema.TaggedStruct<"Draining", {
+  readonly reason: Schema.Literals<readonly ["rotated", "lost", "retired"]>;
+  readonly revokeAt: Schema.Finite;
+}>, {}>;
+/** No longer serving; holds end at this host-monotonic deadline or when their owners let go. */
+declare class Draining extends Draining_base {}
 declare const Lost_base: Schema.Class<Lost, Schema.TaggedStruct<"Lost", {
   readonly cause: Schema.Literals<readonly ["connection", "session", "released"]>;
 }>, {}>;
@@ -48,99 +54,115 @@ declare const Kept_base: Schema.Class<Kept, Schema.TaggedStruct<"Kept", {}>, {}>
  * closed, and its provider runs it on, and bills, until something adopts and releases it.
  */
 declare class Kept extends Kept_base {}
-declare const GenerationState: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
+declare const GenerationState: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Draining, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
 type GenerationState = typeof GenerationState.Type;
 /** A generation that opened: its number, and what the runtime keeps to serve and end it. */
 interface Live<A> {
   readonly number: number;
   readonly value: A;
 }
-/**
- * At most one generation opens and at most one serves. Both do while a rotation makes the next
- * before it breaks the current, and `Down` keeps serving one that a rotation failed to replace.
- */
-type State<A> = {
+interface Held<A, H> extends Live<A> {
+  readonly holds: ReadonlySet<H>;
+}
+/** Release ownership remains here until the provider and generation scope have finished. */
+interface Drain<A, H> {
+  readonly _tag: "Draining" | "Releasing" | "Leaving";
+  readonly live: Held<A, H>;
+  readonly ending: Draining;
+}
+/** One serving generation, one shared acquisition, and prior generations still owned. */
+type State<A, H = unknown> = ({
   readonly _tag: "Opening";
   readonly number: number;
-  readonly serving: Live<A> | undefined;
+  readonly serving: Held<A, H> | undefined;
 } | {
   readonly _tag: "Open";
-  readonly serving: Live<A>;
+  readonly serving: Held<A, H>;
 } | {
   readonly _tag: "Down";
   readonly number: number;
   readonly detail: string;
   readonly cause: unknown;
-  readonly serving: Live<A> | undefined;
+  readonly serving: Held<A, H> | undefined;
 } | {
   readonly _tag: "Retired";
+}) & {
+  readonly draining: ReadonlyMap<number, Drain<A, H>>;
 };
-type Input<A> = {
+type Input<A, H = unknown> = {
   readonly _tag: "Opened";
   readonly live: Live<A>;
-} |
-/** The open of `number` failed for good. */
-{
+} | {
   readonly _tag: "Failed";
   readonly number: number;
   readonly detail: string;
   readonly cause: unknown;
-} |
-/** The open of `number` was stopped, as on retiring, before it opened. */
-{
+} | {
   readonly _tag: "Abandoned";
   readonly number: number;
 } | {
   readonly _tag: "Lost";
   readonly number: number;
   readonly cause: DisconnectCause;
-} |
-/** A caller asks for the next generation, or the rotation time of `due` came. */
-{
+} | {
   readonly _tag: "Rotate";
   readonly due?: number | undefined;
 } | {
   readonly _tag: "Retire";
-} |
-/** Stop as `Retire` does, but leave the serving generation running. */
-{
+} | {
   readonly _tag: "Keep";
+} | {
+  readonly _tag: "Hold";
+  readonly number?: number | undefined;
+  readonly hold: H;
+} | {
+  readonly _tag: "Let";
+  readonly number: number;
+  readonly hold: H;
+} | {
+  readonly _tag: "Revoke";
+  readonly number: number;
 } | {
   readonly _tag: "Released";
   readonly number: number;
-  readonly released: Released;
+  readonly released?: Released | undefined;
 };
-type Command<A> =
-/** Open `number`, after the release of `after` has finished. */
-{
+type Command<A> = {
   readonly _tag: "Open";
   readonly number: number;
   readonly after: number | undefined;
-} |
-/** Watch a generation that opened for its loss and its rotation time. */
-{
+} | {
   readonly _tag: "Watch";
   readonly live: Live<A>;
-} | {
-  readonly _tag: "Release";
+} |
+/** Signal ending and arrange revocation. Repeated only when loss/retirement accelerates it. */
+{
+  readonly _tag: "Drain";
   readonly live: Live<A>;
+  readonly ending: Draining;
 } |
-/** Close its scope without asking its provider to release it. */
+/** Revoke/close holds, await their Let inputs, release the provider, then close its scope. */
 {
+  readonly _tag: "Release";
+  readonly live: Live<A>;
+  readonly ending: Draining;
+} | {
   readonly _tag: "Leave";
   readonly live: Live<A>;
+  readonly ending: Draining;
 };
-interface Step<A> {
-  readonly state: State<A>;
-  /** Generation numbers and their new states, to publish in this order. */
+interface Step<A, H = unknown> {
+  readonly state: State<A, H>;
   readonly events: ReadonlyArray<readonly [number, GenerationState]>;
   readonly commands: ReadonlyArray<Command<A>>;
-  /** For `Rotate`, the generation to wait for, unless retired. */
   readonly reply?: number | undefined;
+  readonly borrowed?: Live<A> | undefined;
 }
-declare const start: <A>() => Step<A>;
-/** The state after `input`, with the events to publish and the commands to run. */
-declare const transition: <A>(state: State<A>, input: Input<A>, exclusive: boolean) => Step<A>;
+declare const start: <A, H = unknown>() => Step<A, H>;
+/** The holds still owned for a generation, including one whose release has begun. */
+declare const lookup: <A, H>(state: State<A, H>, number: number) => Held<A, H> | undefined;
+/** Pure admission and lifecycle changes. A rejected hold preserves state identity. */
+declare const transition: <A, H = unknown>(state: State<A, H>, input: Input<A, H>, exclusive: boolean, now?: number, handover?: number) => Step<A, H>;
 type Resolution<A> = {
   readonly _tag: "Serve";
   readonly live: Live<A>;
@@ -150,18 +172,16 @@ type Resolution<A> = {
   readonly detail: string;
   readonly cause?: unknown;
 };
-/**
- * What a caller waiting for generation `target`, or for any when it is undefined, gets in
- * `state`; undefined while it should go on waiting.
- */
-declare const resolve: <A>(state: State<A>, target: number | undefined) => Resolution<A> | undefined;
+/** An unheld browser resolution; use obtains its hold atomically through Hold instead. */
+declare const resolve: <A, H>(state: State<A, H>, target: number | undefined) => Resolution<A> | undefined;
 declare namespace Supervisor_d_exports {
-  export { Closed, Down, Generation, GenerationState, Kept, Lost, Open, Opened, Opening, Options, Released, Reopening, Settled, Supervisor, Unavailable, Unconfirmed, make };
+  export { Closed, Down, Draining, Generation, GenerationState, Kept, Lease, Lost, Open, Opened, Opening, Options, Released, Reopening, Settled, Superseded, Supervisor, Unavailable, Unconfirmed, UseOptions, make };
 }
 declare const Generation_base: Schema.Class<Generation, Schema.Struct<{
   readonly number: Schema.Int;
   readonly at: Schema.Finite;
-  readonly state: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
+  readonly hostTime: Schema.Finite;
+  readonly state: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Draining, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
 }>, {}>;
 /** One change in a generation's life. `at` is wall-clock epoch milliseconds from the Effect `Clock`. */
 declare class Generation extends Generation_base {}
@@ -178,7 +198,8 @@ declare class Unavailable extends Unavailable_base {
   get message(): string;
 }
 /** One generation, as a provider opened it in the scope the supervisor gave it. */
-interface Opened {
+interface Opened<A = void> {
+  readonly value: A;
   readonly browser: Service;
   /**
    * End the generation, and say whether the provider confirmed its end. The supervisor asks it
@@ -187,9 +208,9 @@ interface Opened {
    */
   readonly release?: Effect.Effect<Released> | undefined;
 }
-interface Options<E, R> {
+interface Options<E, R, A = void> {
   /** Opens one generation in the scope it is given. */
-  readonly open: Effect.Effect<Opened, E, R>;
+  readonly open: Effect.Effect<Opened<A>, E, R>;
   /** When to try a failed open again. Defaults to exponential from 1 second, for 5 minutes. */
   readonly reopen?: Schedule.Schedule<unknown, E> | undefined;
   /**
@@ -204,6 +225,8 @@ interface Options<E, R> {
   readonly rotateBefore?: Duration.Input | undefined;
   /** Generations must not overlap: a rotation releases the current one before it opens the next. */
   readonly exclusive?: boolean | undefined;
+  /** Finite, nonnegative time outgoing holds may finish; defaults to 30 seconds. */
+  readonly handover?: Duration.Input | undefined;
   /**
    * Closing the scope leaves the serving generation running, `Kept`: it closes the generation's
    * scope but never asks `release`. For providers whose scope only disconnects, such as
@@ -213,7 +236,29 @@ interface Options<E, R> {
   /** How long `browser` and `rotate` wait for a generation to open. Defaults to 2 minutes. */
   readonly waitTimeout?: Duration.Input | undefined;
 }
-interface Supervisor {
+declare const Superseded_base: Schema.Class<Superseded, Schema.TaggedStruct<"Superseded", {
+  readonly generation: Schema.Int;
+  readonly reason: Schema.Literals<readonly ["rotated", "lost", "retired"]>;
+  readonly revokeAt: Schema.Finite;
+}>, Cause.YieldableError>;
+/** Work whose generation was revoked; input receipts still determine whether input reached a site. */
+declare class Superseded extends Superseded_base {}
+interface Lease<A> {
+  readonly generation: number;
+  readonly browser: Service;
+  readonly value: A;
+  /** 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. */
+  readonly retain: Effect.Effect<Scope.Closeable, Superseded>;
+}
+interface UseOptions {
+  /** Finite, nonnegative wait for a serving generation. Zero makes an immediate attempt. */
+  readonly wait?: Duration.Input | undefined;
+}
+interface Supervisor<A = void> {
+  /** Scoped work on the current generation. Revocation interrupts it and waits for its cleanup. */
+  readonly use: <B, E, R>(work: (lease: Lease<A>) => Effect.Effect<B, E, R>, options?: UseOptions) => Effect.Effect<B, E | Unavailable | Superseded, Exclude<R, Scope.Scope>>;
   /** The current generation's browser, waiting up to `waitTimeout` while none is open. */
   readonly browser: Effect.Effect<Service, Unavailable>;
   /** Each generation's changes, in order. A new reader first gets the latest 64; ends on retiring. */
@@ -223,8 +268,13 @@ interface Supervisor {
   /** Stop opening at once, release every generation, and wait until each release has finished. */
   readonly retire: Effect.Effect<void>;
 }
-/** Supervise generations of a provider's browser for as long as the scope is open. */
-declare const make: <E, R>(options: Options<E, R>) => Effect.Effect<Supervisor, never, Scope.Scope | Exclude<R, Scope.Scope>>;
+type Provider = Omit<Opened, "value">;
+type MakeOptions<E, R, A> = Omit<Options<E, R, A>, "open"> & {
+  readonly open: Effect.Effect<Opened<A> | Provider, E, R>;
+};
+/** Supervise scoped generation values. Browser-only providers retain their existing void value. */
+declare function make<E, R, A = void>(options: Options<E, R, A>): Effect.Effect<Supervisor<A>, never, Scope.Scope | Exclude<R, Scope.Scope>>;
+declare function make<E, R>(options: MakeOptions<E, R, never>): Effect.Effect<Supervisor<void>, never, Scope.Scope | Exclude<R, Scope.Scope>>;
 //#endregion
-export { Settled as _, Supervisor_d_exports as a, Closed as c, Kept as d, Lost as f, Reopening as g, Released as h, Supervisor as i, Down as l, Opening as m, Opened as n, Unavailable as o, Open as p, Options as r, make as s, Generation as t, GenerationState as u, Unconfirmed as v };
-//# sourceMappingURL=Supervisor-CLJaT7rG.d.mts.map
+export { Unconfirmed as S, Open as _, Superseded as a, Reopening as b, Unavailable as c, Closed as d, Down as f, Lost as g, Kept as h, Options as i, UseOptions as l, GenerationState as m, Lease as n, Supervisor as o, Draining as p, Opened as r, Supervisor_d_exports as s, Generation as t, make as u, Opening as v, Settled as x, Released as y };
+//# sourceMappingURL=Supervisor-CYWFK3vM.d.mts.map