@effect-uai/core 0.9.0 → 0.10.0

package/dist/browser/Browser.d.mts

@@ -0,0 +1,190 @@
+import { BrowserError } from "./BrowserError.mjs";
+import { Brand, Context, Duration, Effect, Scope } from "effect";
+
+//#region src/browser/Browser.d.ts
+declare namespace Browser_d_exports {
+  export { AxNode, BoundingBox, Browser, BrowserService, BrowserSession, BrowserSessionId, BrowserSessionRef, CommonSessionRequest, Cookie, CookieApi, ElementInfo, PageFormat, ScreenshotOptions, ScrollDirection, ScrollOptions, attach, create, destroy, list };
+}
+/**
+ * Session identifier. Branded `string` so providers don't accidentally
+ * accept a raw user-supplied id, and so a session id can't be passed where
+ * another service's id is expected. Each provider mints these per its own
+ * scheme; core code treats them opaquely. Mint via `BrowserSessionId(...)`.
+ */
+type BrowserSessionId = Brand.Branded<string, "BrowserSessionId">;
+declare const BrowserSessionId: Brand.Constructor<BrowserSessionId>;
+/** Reference returned by `list`; enough to `attach`. */
+type BrowserSessionRef = {
+  readonly id: BrowserSessionId; /** Current top-level URL, when the provider reports it. */
+  readonly url?: string;
+};
+/**
+ * Output representation for {@link BrowserSession.content}. `markdown` is
+ * the default.
+ */
+type PageFormat = "markdown" | "html";
+/**
+ * Cross-provider session-create request. Provider-specific knobs (proxy,
+ * stealth, persistent profile, ...) live on each provider's narrowed
+ * request type which extends this.
+ */
+type CommonSessionRequest = {
+  /**
+   * Hard max lifetime of the session. Enforced locally (the handle is
+   * disposed and further calls fail with `BrowserSessionExpired`) and,
+   * where the provider supports it, passed through as a server-side cap so
+   * a crashed client still gets the session reclaimed. The provider cap
+   * must be >= the local reaper. Accepts millis, a string like
+   * `"5 minutes"`, or a `Duration`.
+   */
+  readonly timeout?: Duration.Input;
+  /**
+   * Idle teardown: dispose the session after this much inactivity, the
+   * timer resetting on each operation. Opt-in; omit for no idle limit.
+   */
+  readonly idleTimeout?: Duration.Input; /** Initial viewport size. Providers default differently. */
+  readonly viewport?: {
+    readonly width: number;
+    readonly height: number;
+  };
+};
+type BoundingBox = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+/**
+ * One element returned by {@link BrowserSession.query}. Serializable data,
+ * not a live handle (handles go stale across navigation and do not cross a
+ * provider boundary cleanly).
+ */
+type ElementInfo = {
+  /**
+   * Reference usable as a selector for a follow-up action. Valid until the
+   * next navigation; do not cache across `goto` or a page-changing click.
+   */
+  readonly ref: string;
+  readonly tag: string;
+  readonly text?: string;
+  readonly attributes: Readonly<Record<string, string>>;
+  readonly box?: BoundingBox;
+};
+/** Accessibility-tree node returned by {@link BrowserSession.snapshot}. */
+type AxNode = {
+  readonly role: string;
+  readonly name?: string;
+  readonly value?: string;
+  /**
+   * Reference usable as a selector for a follow-up action. Valid until the
+   * next navigation; do not cache across `goto` or a page-changing click.
+   */
+  readonly ref?: string;
+  readonly children: ReadonlyArray<AxNode>;
+};
+type ScrollDirection = "up" | "down" | "left" | "right";
+type ScrollOptions = {
+  readonly direction: ScrollDirection; /** Distance in CSS pixels. Provider default applies when omitted. */
+  readonly pixels?: number;
+};
+type ScreenshotOptions = {
+  /** Clip to the first element matching this selector. */readonly selector?: string; /** Capture the full scrollable page rather than the viewport. */
+  readonly fullPage?: boolean;
+};
+type Cookie = {
+  readonly name: string;
+  readonly value: string;
+  readonly domain?: string;
+  readonly path?: string;
+  readonly expires?: number;
+  readonly httpOnly?: boolean;
+  readonly secure?: boolean;
+  readonly sameSite?: "Strict" | "Lax" | "None";
+};
+/** Read / write the session's cookie jar. Needed for authenticated flows. */
+type CookieApi = {
+  readonly get: Effect.Effect<ReadonlyArray<Cookie>, BrowserError>;
+  readonly set: (cookies: ReadonlyArray<Cookie>) => Effect.Effect<void, BrowserError>;
+};
+/**
+ * Live session handle. Actions take a CSS selector string (so `#id` is
+ * just `#id`). Methods are plain `Effect` values; disposal is the scope
+ * finalizer, not a method here (see {@link BrowserService}). Anything not
+ * covered by a verb is reachable via `evaluate`. Per-operation time budgets
+ * are the provider's default; wrap any call in `Effect.timeout` for a
+ * tighter bound.
+ */
+type BrowserSession = {
+  readonly id: BrowserSessionId;
+  readonly goto: (url: string) => Effect.Effect<void, BrowserError>;
+  readonly waitFor: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly click: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly dblclick: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly fill: (selector: string, text: string) => Effect.Effect<void, BrowserError>;
+  readonly type: (selector: string, text: string) => Effect.Effect<void, BrowserError>;
+  readonly press: (key: string) => Effect.Effect<void, BrowserError>;
+  readonly hover: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly focus: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly select: (selector: string, value: string) => Effect.Effect<void, BrowserError>;
+  readonly check: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly uncheck: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly scroll: (options: ScrollOptions) => Effect.Effect<void, BrowserError>;
+  readonly scrollIntoView: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly content: (format?: PageFormat) => Effect.Effect<string, BrowserError>;
+  readonly screenshot: (options?: ScreenshotOptions) => Effect.Effect<Uint8Array, BrowserError>;
+  readonly snapshot: Effect.Effect<AxNode, BrowserError>;
+  readonly query: (selector: string) => Effect.Effect<ReadonlyArray<ElementInfo>, BrowserError>;
+  readonly cookies: CookieApi;
+  readonly evaluate: (script: string) => Effect.Effect<unknown, BrowserError>;
+};
+/**
+ * Cross-provider browser service.
+ *
+ * Lifetime: `create` and `attach` return a handle in `Scope.Scope`. The
+ * scope finalizer disposes the session (close the transport, destroy or
+ * detach the remote session, kill the local engine). Bind with
+ * `Effect.scoped` for a single call, or hold a wider scope to keep a
+ * session warm across many calls. This is why there is no `dispose()` on
+ * {@link BrowserSession}; the scope is the lifecycle handle.
+ */
+type BrowserService = {
+  /**
+   * Provision a new session, bound to the caller's scope. Disposed on
+   * scope close.
+   */
+  readonly create: (request: CommonSessionRequest) => Effect.Effect<BrowserSession, BrowserError, Scope.Scope>;
+  /**
+   * Re-acquire an existing session by id. Scope-bound, but the finalizer
+   * detaches rather than destroying, for sessions kept warm beyond a
+   * single run.
+   */
+  readonly attach: (id: BrowserSessionId) => Effect.Effect<BrowserSession, BrowserError, Scope.Scope>; /** Enumerate sessions visible to the configured account / project. */
+  readonly list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, BrowserError>;
+  /**
+   * Destroy a session from outside its owning scope. Most callers should
+   * let the scope finalizer handle this.
+   */
+  readonly destroy: (id: BrowserSessionId) => Effect.Effect<void, BrowserError>;
+};
+declare const Browser_base: Context.ServiceClass<Browser, "@betalyra/effect-uai/Browser", BrowserService>;
+declare class Browser extends Browser_base {}
+/**
+ * Provision a session bound to the caller's scope. Drop the `Scope.Scope`
+ * requirement with `Effect.scoped`.
+ */
+declare const create: (request: CommonSessionRequest) => Effect.Effect<BrowserSession, BrowserError, Browser | Scope.Scope>;
+/**
+ * Re-acquire an existing session by id. Same scope semantics as `create`,
+ * but the finalizer detaches rather than destroying.
+ */
+declare const attach: (id: BrowserSessionId) => Effect.Effect<BrowserSession, BrowserError, Browser | Scope.Scope>;
+/** Enumerate sessions for the configured account / project. */
+declare const list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, BrowserError, Browser>;
+/**
+ * Destroy a session from outside its owning scope. Most callers should let
+ * the scope finalizer handle this automatically.
+ */
+declare const destroy: (id: BrowserSessionId) => Effect.Effect<void, BrowserError, Browser>;
+//#endregion
+export { AxNode, BoundingBox, Browser, BrowserService, BrowserSession, BrowserSessionId, BrowserSessionRef, CommonSessionRequest, Cookie, CookieApi, ElementInfo, PageFormat, ScreenshotOptions, ScrollDirection, ScrollOptions, attach, create, destroy, list, Browser_d_exports as t };
+//# sourceMappingURL=Browser.d.mts.map

package/dist/browser/Browser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Browser.d.mts","names":[],"sources":["../../src/browser/Browser.ts"],"mappings":"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"}

package/dist/browser/Browser.mjs

@@ -0,0 +1,34 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Brand, Context, Effect } from "effect";
+//#region src/browser/Browser.ts
+var Browser_exports = /* @__PURE__ */ __exportAll({
+	Browser: () => Browser,
+	BrowserSessionId: () => BrowserSessionId,
+	attach: () => attach,
+	create: () => create,
+	destroy: () => destroy,
+	list: () => list
+});
+const BrowserSessionId = Brand.nominal();
+var Browser = class extends Context.Service()("@betalyra/effect-uai/Browser") {};
+/**
+* Provision a session bound to the caller's scope. Drop the `Scope.Scope`
+* requirement with `Effect.scoped`.
+*/
+const create = (request) => Effect.flatMap(Browser.asEffect(), (s) => s.create(request));
+/**
+* Re-acquire an existing session by id. Same scope semantics as `create`,
+* but the finalizer detaches rather than destroying.
+*/
+const attach = (id) => Effect.flatMap(Browser.asEffect(), (s) => s.attach(id));
+/** Enumerate sessions for the configured account / project. */
+const list = Effect.flatMap(Browser.asEffect(), (s) => s.list);
+/**
+* Destroy a session from outside its owning scope. Most callers should let
+* the scope finalizer handle this automatically.
+*/
+const destroy = (id) => Effect.flatMap(Browser.asEffect(), (s) => s.destroy(id));
+//#endregion
+export { Browser, BrowserSessionId, attach, create, destroy, list, Browser_exports as t };
+
+//# sourceMappingURL=Browser.mjs.map

package/dist/browser/Browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Browser.mjs","names":[],"sources":["../../src/browser/Browser.ts"],"sourcesContent":["import { Brand, Context, type Duration, Effect, Scope } from \"effect\"\nimport type * as BrowserError from \"./BrowserError.js\"\n\n// ---------------------------------------------------------------------------\n// Identity\n// ---------------------------------------------------------------------------\n\n/**\n * Session identifier. Branded `string` so providers don't accidentally\n * accept a raw user-supplied id, and so a session id can't be passed where\n * another service's id is expected. Each provider mints these per its own\n * scheme; core code treats them opaquely. Mint via `BrowserSessionId(...)`.\n */\nexport type BrowserSessionId = Brand.Branded<string, \"BrowserSessionId\">\nexport const BrowserSessionId = Brand.nominal<BrowserSessionId>()\n\n/** Reference returned by `list`; enough to `attach`. */\nexport type BrowserSessionRef = {\n  readonly id: BrowserSessionId\n  /** Current top-level URL, when the provider reports it. */\n  readonly url?: string\n}\n\n/**\n * Output representation for {@link BrowserSession.content}. `markdown` is\n * the default.\n */\nexport type PageFormat = \"markdown\" | \"html\"\n\n// ---------------------------------------------------------------------------\n// Create request\n// ---------------------------------------------------------------------------\n\n/**\n * Cross-provider session-create request. Provider-specific knobs (proxy,\n * stealth, persistent profile, ...) live on each provider's narrowed\n * request type which extends this.\n */\nexport type CommonSessionRequest = {\n  /**\n   * Hard max lifetime of the session. Enforced locally (the handle is\n   * disposed and further calls fail with `BrowserSessionExpired`) and,\n   * where the provider supports it, passed through as a server-side cap so\n   * a crashed client still gets the session reclaimed. The provider cap\n   * must be >= the local reaper. Accepts millis, a string like\n   * `\"5 minutes\"`, or a `Duration`.\n   */\n  readonly timeout?: Duration.Input\n  /**\n   * Idle teardown: dispose the session after this much inactivity, the\n   * timer resetting on each operation. Opt-in; omit for no idle limit.\n   */\n  readonly idleTimeout?: Duration.Input\n  /** Initial viewport size. Providers default differently. */\n  readonly viewport?: { readonly width: number; readonly height: number }\n}\n\n// ---------------------------------------------------------------------------\n// Observation shapes\n// ---------------------------------------------------------------------------\n\nexport type BoundingBox = {\n  readonly x: number\n  readonly y: number\n  readonly width: number\n  readonly height: number\n}\n\n/**\n * One element returned by {@link BrowserSession.query}. Serializable data,\n * not a live handle (handles go stale across navigation and do not cross a\n * provider boundary cleanly).\n */\nexport type ElementInfo = {\n  /**\n   * Reference usable as a selector for a follow-up action. Valid until the\n   * next navigation; do not cache across `goto` or a page-changing click.\n   */\n  readonly ref: string\n  readonly tag: string\n  readonly text?: string\n  readonly attributes: Readonly<Record<string, string>>\n  readonly box?: BoundingBox\n}\n\n/** Accessibility-tree node returned by {@link BrowserSession.snapshot}. */\nexport type AxNode = {\n  readonly role: string\n  readonly name?: string\n  readonly value?: string\n  /**\n   * Reference usable as a selector for a follow-up action. Valid until the\n   * next navigation; do not cache across `goto` or a page-changing click.\n   */\n  readonly ref?: string\n  readonly children: ReadonlyArray<AxNode>\n}\n\n// ---------------------------------------------------------------------------\n// Interaction shapes\n// ---------------------------------------------------------------------------\n\nexport type ScrollDirection = \"up\" | \"down\" | \"left\" | \"right\"\n\nexport type ScrollOptions = {\n  readonly direction: ScrollDirection\n  /** Distance in CSS pixels. Provider default applies when omitted. */\n  readonly pixels?: number\n}\n\nexport type ScreenshotOptions = {\n  /** Clip to the first element matching this selector. */\n  readonly selector?: string\n  /** Capture the full scrollable page rather than the viewport. */\n  readonly fullPage?: boolean\n}\n\nexport type Cookie = {\n  readonly name: string\n  readonly value: string\n  readonly domain?: string\n  readonly path?: string\n  readonly expires?: number\n  readonly httpOnly?: boolean\n  readonly secure?: boolean\n  readonly sameSite?: \"Strict\" | \"Lax\" | \"None\"\n}\n\n/** Read / write the session's cookie jar. Needed for authenticated flows. */\nexport type CookieApi = {\n  readonly get: Effect.Effect<ReadonlyArray<Cookie>, BrowserError.BrowserError>\n  readonly set: (cookies: ReadonlyArray<Cookie>) => Effect.Effect<void, BrowserError.BrowserError>\n}\n\n// ---------------------------------------------------------------------------\n// Live session handle\n// ---------------------------------------------------------------------------\n\n/**\n * Live session handle. Actions take a CSS selector string (so `#id` is\n * just `#id`). Methods are plain `Effect` values; disposal is the scope\n * finalizer, not a method here (see {@link BrowserService}). Anything not\n * covered by a verb is reachable via `evaluate`. Per-operation time budgets\n * are the provider's default; wrap any call in `Effect.timeout` for a\n * tighter bound.\n */\nexport type BrowserSession = {\n  readonly id: BrowserSessionId\n\n  // Navigation and waiting\n  readonly goto: (url: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly waitFor: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n\n  // Interaction\n  readonly click: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly dblclick: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly fill: (selector: string, text: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly type: (selector: string, text: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly press: (key: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly hover: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly focus: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly select: (\n    selector: string,\n    value: string,\n  ) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly check: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly uncheck: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly scroll: (options: ScrollOptions) => Effect.Effect<void, BrowserError.BrowserError>\n  readonly scrollIntoView: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>\n\n  // Observation\n  readonly content: (format?: PageFormat) => Effect.Effect<string, BrowserError.BrowserError>\n  readonly screenshot: (\n    options?: ScreenshotOptions,\n  ) => Effect.Effect<Uint8Array, BrowserError.BrowserError>\n  readonly snapshot: Effect.Effect<AxNode, BrowserError.BrowserError>\n  readonly query: (\n    selector: string,\n  ) => Effect.Effect<ReadonlyArray<ElementInfo>, BrowserError.BrowserError>\n\n  // State and escape hatch\n  readonly cookies: CookieApi\n  readonly evaluate: (script: string) => Effect.Effect<unknown, BrowserError.BrowserError>\n}\n\n// ---------------------------------------------------------------------------\n// Service definition\n// ---------------------------------------------------------------------------\n\n/**\n * Cross-provider browser service.\n *\n * Lifetime: `create` and `attach` return a handle in `Scope.Scope`. The\n * scope finalizer disposes the session (close the transport, destroy or\n * detach the remote session, kill the local engine). Bind with\n * `Effect.scoped` for a single call, or hold a wider scope to keep a\n * session warm across many calls. This is why there is no `dispose()` on\n * {@link BrowserSession}; the scope is the lifecycle handle.\n */\nexport type BrowserService = {\n  /**\n   * Provision a new session, bound to the caller's scope. Disposed on\n   * scope close.\n   */\n  readonly create: (\n    request: CommonSessionRequest,\n  ) => Effect.Effect<BrowserSession, BrowserError.BrowserError, Scope.Scope>\n\n  /**\n   * Re-acquire an existing session by id. Scope-bound, but the finalizer\n   * detaches rather than destroying, for sessions kept warm beyond a\n   * single run.\n   */\n  readonly attach: (\n    id: BrowserSessionId,\n  ) => Effect.Effect<BrowserSession, BrowserError.BrowserError, Scope.Scope>\n\n  /** Enumerate sessions visible to the configured account / project. */\n  readonly list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, BrowserError.BrowserError>\n\n  /**\n   * Destroy a session from outside its owning scope. Most callers should\n   * let the scope finalizer handle this.\n   */\n  readonly destroy: (id: BrowserSessionId) => Effect.Effect<void, BrowserError.BrowserError>\n}\n\nexport class Browser extends Context.Service<Browser, BrowserService>()(\n  \"@betalyra/effect-uai/Browser\",\n) {}\n\n// ---------------------------------------------------------------------------\n// Free helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Provision a session bound to the caller's scope. Drop the `Scope.Scope`\n * requirement with `Effect.scoped`.\n */\nexport const create = (\n  request: CommonSessionRequest,\n): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>\n  Effect.flatMap(Browser.asEffect(), (s) => s.create(request))\n\n/**\n * Re-acquire an existing session by id. Same scope semantics as `create`,\n * but the finalizer detaches rather than destroying.\n */\nexport const attach = (\n  id: BrowserSessionId,\n): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>\n  Effect.flatMap(Browser.asEffect(), (s) => s.attach(id))\n\n/** Enumerate sessions for the configured account / project. */\nexport const list: Effect.Effect<\n  ReadonlyArray<BrowserSessionRef>,\n  BrowserError.BrowserError,\n  Browser\n> = Effect.flatMap(Browser.asEffect(), (s) => s.list)\n\n/**\n * Destroy a session from outside its owning scope. Most callers should let\n * the scope finalizer handle this automatically.\n */\nexport const destroy = (\n  id: BrowserSessionId,\n): Effect.Effect<void, BrowserError.BrowserError, Browser> =>\n  Effect.flatMap(Browser.asEffect(), (s) => s.destroy(id))\n"],"mappings":";;;;;;;;;;;AAcA,MAAa,mBAAmB,MAAM,SAA2B;AAqNjE,IAAa,UAAb,cAA6B,QAAQ,SAAkC,CACrE,+BACD,CAAC;;;;;AAUF,MAAa,UACX,YAEA,OAAO,QAAQ,QAAQ,UAAU,GAAG,MAAM,EAAE,OAAO,QAAQ,CAAC;;;;;AAM9D,MAAa,UACX,OAEA,OAAO,QAAQ,QAAQ,UAAU,GAAG,MAAM,EAAE,OAAO,GAAG,CAAC;;AAGzD,MAAa,OAIT,OAAO,QAAQ,QAAQ,UAAU,GAAG,MAAM,EAAE,KAAK;;;;;AAMrD,MAAa,WACX,OAEA,OAAO,QAAQ,QAAQ,UAAU,GAAG,MAAM,EAAE,QAAQ,GAAG,CAAC"}

package/dist/browser/BrowserError.d.mts

@@ -0,0 +1,141 @@
+import { Duration } from "effect";
+import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Types0 from "effect/Types";
+
+//#region src/browser/BrowserError.d.ts
+declare namespace BrowserError_d_exports {
+  export { BrowserActionFailed, BrowserAuthFailed, BrowserAuthSubtype, BrowserCreateFailed, BrowserError, BrowserInvalidRequest, BrowserQuotaExceeded, BrowserSessionExpired, BrowserSessionNotFound, BrowserTimeout, BrowserUnsupported, describe };
+}
+declare const BrowserCreateFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserCreateFailed";
+} & Readonly<A>;
+/**
+ * Failed to provision a browser session: the transport could not connect,
+ * a launched engine did not come up, or the provider refused to mint a
+ * session. Provider's structured reason on `reason`; the raw transport /
+ * SDK error on `raw`.
+ */
+declare class BrowserCreateFailed extends BrowserCreateFailed_base<{
+  provider: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserSessionNotFound_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserSessionNotFound";
+} & Readonly<A>;
+/**
+ * The requested session id does not exist. Raised by `attach` / `destroy`
+ * against a stale or never-known id. Distinct from
+ * {@link BrowserSessionExpired}, which is a session that existed and has
+ * since ended.
+ */
+declare class BrowserSessionNotFound extends BrowserSessionNotFound_base<{
+  provider: string;
+  id: string;
+}> {}
+declare const BrowserSessionExpired_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserSessionExpired";
+} & Readonly<A>;
+/**
+ * An operation was issued against a session that has ended: it reached its
+ * max lifetime (the create-time `timeout`), was destroyed, or the provider
+ * reaped it. The handle is dead; `create` or `attach` a live session.
+ * Distinct from {@link BrowserTimeout} (a single live operation was too
+ * slow).
+ */
+declare class BrowserSessionExpired extends BrowserSessionExpired_base<{
+  provider: string;
+  id: string;
+}> {}
+declare const BrowserTimeout_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserTimeout";
+} & Readonly<A>;
+/**
+ * A single operation exceeded its own time budget while the session was
+ * still alive (a navigation that never settled, a `waitFor` selector that
+ * never appeared). Carries the breached budget for observability.
+ */
+declare class BrowserTimeout extends BrowserTimeout_base<{
+  provider: string;
+  operation: "create" | "attach" | "navigate" | "action" | "query";
+  budget?: Duration.Duration;
+  raw?: unknown;
+}> {}
+declare const BrowserActionFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserActionFailed";
+} & Readonly<A>;
+/**
+ * An interaction or observation failed at the transport / protocol layer:
+ * a selector resolved to nothing, an element was not actionable, an
+ * `evaluate` script threw, a navigation errored. `selector` and `reason`
+ * carry what is known.
+ */
+declare class BrowserActionFailed extends BrowserActionFailed_base<{
+  provider: string;
+  operation: "navigate" | "interact" | "observe" | "evaluate" | "cookies";
+  selector?: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserQuotaExceeded_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserQuotaExceeded";
+} & Readonly<A>;
+/**
+ * Provider rejected the request because an account / project quota or
+ * concurrency limit was exceeded. Separate from {@link BrowserCreateFailed}
+ * so callers can back off and retry.
+ */
+declare class BrowserQuotaExceeded extends BrowserQuotaExceeded_base<{
+  provider: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserInvalidRequest_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserInvalidRequest";
+} & Readonly<A>;
+/**
+ * Caller's request shape is malformed for the wired provider. Adapters
+ * should reject at the request-schema layer where possible; this is the
+ * runtime fallback.
+ */
+declare class BrowserInvalidRequest extends BrowserInvalidRequest_base<{
+  provider: string;
+  param?: string;
+  reason?: string;
+  raw?: unknown;
+}> {}
+/**
+ * Transport could not authenticate against the provider. Subtype mirrors
+ * the model-side `AiError.AuthFailed` shape for consistency.
+ */
+type BrowserAuthSubtype = "auth" | "permission" | "billing" | "quota";
+declare const BrowserAuthFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserAuthFailed";
+} & Readonly<A>;
+declare class BrowserAuthFailed extends BrowserAuthFailed_base<{
+  provider: string;
+  subtype: BrowserAuthSubtype;
+  raw: unknown;
+}> {}
+declare const BrowserUnsupported_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserUnsupported";
+} & Readonly<A>;
+/**
+ * The wired provider does not implement the requested operation for these
+ * inputs. Distinct from {@link BrowserInvalidRequest} (malformed request)
+ * and from compile-time capability markers gating blanket provider gaps.
+ */
+declare class BrowserUnsupported extends BrowserUnsupported_base<{
+  provider: string;
+  capability: string;
+  reason?: string;
+}> {}
+type BrowserError = BrowserCreateFailed | BrowserSessionNotFound | BrowserSessionExpired | BrowserTimeout | BrowserActionFailed | BrowserQuotaExceeded | BrowserInvalidRequest | BrowserAuthFailed | BrowserUnsupported;
+/**
+ * Short human-readable description of an error, for logs and model-facing
+ * failure messages. Prose, not a contract; branch on `_tag` instead.
+ */
+declare const describe: (e: BrowserError) => string;
+//#endregion
+export { BrowserActionFailed, BrowserAuthFailed, BrowserAuthSubtype, BrowserCreateFailed, BrowserError, BrowserInvalidRequest, BrowserQuotaExceeded, BrowserSessionExpired, BrowserSessionNotFound, BrowserTimeout, BrowserUnsupported, describe, BrowserError_d_exports as t };
+//# sourceMappingURL=BrowserError.d.mts.map

package/dist/browser/BrowserError.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserError.d.mts","names":[],"sources":["../../src/browser/BrowserError.ts"],"mappings":";;;;;;;;cAA8C,wBAAA;;;;;;;;;cAQjC,mBAAA,SAA4B,wBAAA;EACvC,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,2BAAA;;;;AAZyC;;;;;cAoBjC,sBAAA,SAA+B,2BAAA;EAC1C,QAAA;EACA,EAAA;AAAA;AAAA,cACG,0BAAA;;;;;;;;;;cASQ,qBAAA,SAA8B,0BAAA;EACzC,QAAA;EACA,EAAA;AAAA;AAAA,cACG,mBAAA;;;;;;AA3BL;;cAkCa,cAAA,SAAuB,mBAAA;EAClC,QAAA;EACA,SAAA;EACA,MAAA,GAAS,QAAA,CAAS,QAAA;EAClB,GAAA;AAAA;AAAA,cACG,wBAAA;;;;;;;;;cAQQ,mBAAA,SAA4B,wBAAA;EACvC,QAAA;EACA,SAAA;EACA,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,yBAAA;;;;;;;;cAOQ,oBAAA,SAA6B,yBAAA;EACxC,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,0BAAA;;;;;;;;cAOQ,qBAAA,SAA8B,0BAAA;EACzC,QAAA;EACA,KAAA;EACA,MAAA;EACA,GAAA;AAAA;;;;;KAOU,kBAAA;AAAA,cAAgE,sBAAA;;;cAE/D,iBAAA,SAA0B,sBAAA;EACrC,QAAA;EACA,OAAA,EAAS,kBAAA;EACT,GAAA;AAAA;AAAA,cACG,uBAAA;;;;;;;;cAOQ,kBAAA,SAA2B,uBAAA;EACtC,QAAA;EACA,UAAA;EACA,MAAA;AAAA;AAAA,KAGU,YAAA,GACR,mBAAA,GACA,sBAAA,GACA,qBAAA,GACA,cAAA,GACA,mBAAA,GACA,oBAAA,GACA,qBAAA,GACA,iBAAA,GACA,kBAAA;;;;;cASS,QAAA,GAAW,CAAA,EAAG,YAAA"}

package/dist/browser/BrowserError.mjs

@@ -0,0 +1,89 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Data, Match } from "effect";
+//#region src/browser/BrowserError.ts
+var BrowserError_exports = /* @__PURE__ */ __exportAll({
+	BrowserActionFailed: () => BrowserActionFailed,
+	BrowserAuthFailed: () => BrowserAuthFailed,
+	BrowserCreateFailed: () => BrowserCreateFailed,
+	BrowserInvalidRequest: () => BrowserInvalidRequest,
+	BrowserQuotaExceeded: () => BrowserQuotaExceeded,
+	BrowserSessionExpired: () => BrowserSessionExpired,
+	BrowserSessionNotFound: () => BrowserSessionNotFound,
+	BrowserTimeout: () => BrowserTimeout,
+	BrowserUnsupported: () => BrowserUnsupported,
+	describe: () => describe
+});
+/**
+* Failed to provision a browser session: the transport could not connect,
+* a launched engine did not come up, or the provider refused to mint a
+* session. Provider's structured reason on `reason`; the raw transport /
+* SDK error on `raw`.
+*/
+var BrowserCreateFailed = class extends Data.TaggedError("BrowserCreateFailed") {};
+/**
+* The requested session id does not exist. Raised by `attach` / `destroy`
+* against a stale or never-known id. Distinct from
+* {@link BrowserSessionExpired}, which is a session that existed and has
+* since ended.
+*/
+var BrowserSessionNotFound = class extends Data.TaggedError("BrowserSessionNotFound") {};
+/**
+* An operation was issued against a session that has ended: it reached its
+* max lifetime (the create-time `timeout`), was destroyed, or the provider
+* reaped it. The handle is dead; `create` or `attach` a live session.
+* Distinct from {@link BrowserTimeout} (a single live operation was too
+* slow).
+*/
+var BrowserSessionExpired = class extends Data.TaggedError("BrowserSessionExpired") {};
+/**
+* A single operation exceeded its own time budget while the session was
+* still alive (a navigation that never settled, a `waitFor` selector that
+* never appeared). Carries the breached budget for observability.
+*/
+var BrowserTimeout = class extends Data.TaggedError("BrowserTimeout") {};
+/**
+* An interaction or observation failed at the transport / protocol layer:
+* a selector resolved to nothing, an element was not actionable, an
+* `evaluate` script threw, a navigation errored. `selector` and `reason`
+* carry what is known.
+*/
+var BrowserActionFailed = class extends Data.TaggedError("BrowserActionFailed") {};
+/**
+* Provider rejected the request because an account / project quota or
+* concurrency limit was exceeded. Separate from {@link BrowserCreateFailed}
+* so callers can back off and retry.
+*/
+var BrowserQuotaExceeded = class extends Data.TaggedError("BrowserQuotaExceeded") {};
+/**
+* Caller's request shape is malformed for the wired provider. Adapters
+* should reject at the request-schema layer where possible; this is the
+* runtime fallback.
+*/
+var BrowserInvalidRequest = class extends Data.TaggedError("BrowserInvalidRequest") {};
+var BrowserAuthFailed = class extends Data.TaggedError("BrowserAuthFailed") {};
+/**
+* The wired provider does not implement the requested operation for these
+* inputs. Distinct from {@link BrowserInvalidRequest} (malformed request)
+* and from compile-time capability markers gating blanket provider gaps.
+*/
+var BrowserUnsupported = class extends Data.TaggedError("BrowserUnsupported") {};
+const withReason = (base, reason) => reason === void 0 ? base : `${base}: ${reason}`;
+/**
+* Short human-readable description of an error, for logs and model-facing
+* failure messages. Prose, not a contract; branch on `_tag` instead.
+*/
+const describe = Match.type().pipe(Match.discriminatorsExhaustive("_tag")({
+	BrowserCreateFailed: (e) => withReason("the browser session could not be created", e.reason),
+	BrowserSessionNotFound: () => "the browser session does not exist",
+	BrowserSessionExpired: () => "the browser session has expired",
+	BrowserTimeout: (e) => `the ${e.operation} operation timed out`,
+	BrowserActionFailed: (e) => withReason(`the ${e.operation} failed${e.selector === void 0 ? "" : ` on ${e.selector}`}`, e.reason),
+	BrowserQuotaExceeded: (e) => withReason("the browser quota is exceeded", e.reason),
+	BrowserInvalidRequest: (e) => withReason("the request was invalid", e.reason),
+	BrowserAuthFailed: (e) => `browser authentication failed (${e.subtype})`,
+	BrowserUnsupported: (e) => withReason(`this browser does not support ${e.capability}`, e.reason)
+}));
+//#endregion
+export { BrowserActionFailed, BrowserAuthFailed, BrowserCreateFailed, BrowserInvalidRequest, BrowserQuotaExceeded, BrowserSessionExpired, BrowserSessionNotFound, BrowserTimeout, BrowserUnsupported, describe, BrowserError_exports as t };
+
+//# sourceMappingURL=BrowserError.mjs.map

package/dist/browser/BrowserError.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserError.mjs","names":[],"sources":["../../src/browser/BrowserError.ts"],"sourcesContent":["import { Data, Duration, Match } from \"effect\"\n\n/**\n * Failed to provision a browser session: the transport could not connect,\n * a launched engine did not come up, or the provider refused to mint a\n * session. Provider's structured reason on `reason`; the raw transport /\n * SDK error on `raw`.\n */\nexport class BrowserCreateFailed extends Data.TaggedError(\"BrowserCreateFailed\")<{\n  provider: string\n  reason?: string\n  raw: unknown\n}> {}\n\n/**\n * The requested session id does not exist. Raised by `attach` / `destroy`\n * against a stale or never-known id. Distinct from\n * {@link BrowserSessionExpired}, which is a session that existed and has\n * since ended.\n */\nexport class BrowserSessionNotFound extends Data.TaggedError(\"BrowserSessionNotFound\")<{\n  provider: string\n  id: string\n}> {}\n\n/**\n * An operation was issued against a session that has ended: it reached its\n * max lifetime (the create-time `timeout`), was destroyed, or the provider\n * reaped it. The handle is dead; `create` or `attach` a live session.\n * Distinct from {@link BrowserTimeout} (a single live operation was too\n * slow).\n */\nexport class BrowserSessionExpired extends Data.TaggedError(\"BrowserSessionExpired\")<{\n  provider: string\n  id: string\n}> {}\n\n/**\n * A single operation exceeded its own time budget while the session was\n * still alive (a navigation that never settled, a `waitFor` selector that\n * never appeared). Carries the breached budget for observability.\n */\nexport class BrowserTimeout extends Data.TaggedError(\"BrowserTimeout\")<{\n  provider: string\n  operation: \"create\" | \"attach\" | \"navigate\" | \"action\" | \"query\"\n  budget?: Duration.Duration\n  raw?: unknown\n}> {}\n\n/**\n * An interaction or observation failed at the transport / protocol layer:\n * a selector resolved to nothing, an element was not actionable, an\n * `evaluate` script threw, a navigation errored. `selector` and `reason`\n * carry what is known.\n */\nexport class BrowserActionFailed extends Data.TaggedError(\"BrowserActionFailed\")<{\n  provider: string\n  operation: \"navigate\" | \"interact\" | \"observe\" | \"evaluate\" | \"cookies\"\n  selector?: string\n  reason?: string\n  raw: unknown\n}> {}\n\n/**\n * Provider rejected the request because an account / project quota or\n * concurrency limit was exceeded. Separate from {@link BrowserCreateFailed}\n * so callers can back off and retry.\n */\nexport class BrowserQuotaExceeded extends Data.TaggedError(\"BrowserQuotaExceeded\")<{\n  provider: string\n  reason?: string\n  raw: unknown\n}> {}\n\n/**\n * Caller's request shape is malformed for the wired provider. Adapters\n * should reject at the request-schema layer where possible; this is the\n * runtime fallback.\n */\nexport class BrowserInvalidRequest extends Data.TaggedError(\"BrowserInvalidRequest\")<{\n  provider: string\n  param?: string\n  reason?: string\n  raw?: unknown\n}> {}\n\n/**\n * Transport could not authenticate against the provider. Subtype mirrors\n * the model-side `AiError.AuthFailed` shape for consistency.\n */\nexport type BrowserAuthSubtype = \"auth\" | \"permission\" | \"billing\" | \"quota\"\n\nexport class BrowserAuthFailed extends Data.TaggedError(\"BrowserAuthFailed\")<{\n  provider: string\n  subtype: BrowserAuthSubtype\n  raw: unknown\n}> {}\n\n/**\n * The wired provider does not implement the requested operation for these\n * inputs. Distinct from {@link BrowserInvalidRequest} (malformed request)\n * and from compile-time capability markers gating blanket provider gaps.\n */\nexport class BrowserUnsupported extends Data.TaggedError(\"BrowserUnsupported\")<{\n  provider: string\n  capability: string\n  reason?: string\n}> {}\n\nexport type BrowserError =\n  | BrowserCreateFailed\n  | BrowserSessionNotFound\n  | BrowserSessionExpired\n  | BrowserTimeout\n  | BrowserActionFailed\n  | BrowserQuotaExceeded\n  | BrowserInvalidRequest\n  | BrowserAuthFailed\n  | BrowserUnsupported\n\nconst withReason = (base: string, reason: string | undefined): string =>\n  reason === undefined ? base : `${base}: ${reason}`\n\n/**\n * Short human-readable description of an error, for logs and model-facing\n * failure messages. Prose, not a contract; branch on `_tag` instead.\n */\nexport const describe: (e: BrowserError) => string = Match.type<BrowserError>().pipe(\n  Match.discriminatorsExhaustive(\"_tag\")({\n    BrowserCreateFailed: (e) => withReason(\"the browser session could not be created\", e.reason),\n    BrowserSessionNotFound: () => \"the browser session does not exist\",\n    BrowserSessionExpired: () => \"the browser session has expired\",\n    BrowserTimeout: (e) => `the ${e.operation} operation timed out`,\n    BrowserActionFailed: (e) =>\n      withReason(\n        `the ${e.operation} failed${e.selector === undefined ? \"\" : ` on ${e.selector}`}`,\n        e.reason,\n      ),\n    BrowserQuotaExceeded: (e) => withReason(\"the browser quota is exceeded\", e.reason),\n    BrowserInvalidRequest: (e) => withReason(\"the request was invalid\", e.reason),\n    BrowserAuthFailed: (e) => `browser authentication failed (${e.subtype})`,\n    BrowserUnsupported: (e) =>\n      withReason(`this browser does not support ${e.capability}`, e.reason),\n  }),\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAQA,IAAa,sBAAb,cAAyC,KAAK,YAAY,sBAAsB,CAI7E;;;;;;;AAQH,IAAa,yBAAb,cAA4C,KAAK,YAAY,yBAAyB,CAGnF;;;;;;;;AASH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAGjF;;;;;;AAOH,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAKnE;;;;;;;AAQH,IAAa,sBAAb,cAAyC,KAAK,YAAY,sBAAsB,CAM7E;;;;;;AAOH,IAAa,uBAAb,cAA0C,KAAK,YAAY,uBAAuB,CAI/E;;;;;;AAOH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAKjF;AAQH,IAAa,oBAAb,cAAuC,KAAK,YAAY,oBAAoB,CAIzE;;;;;;AAOH,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAI3E;AAaH,MAAM,cAAc,MAAc,WAChC,WAAW,KAAA,IAAY,OAAO,GAAG,KAAK,IAAI;;;;;AAM5C,MAAa,WAAwC,MAAM,MAAoB,CAAC,KAC9E,MAAM,yBAAyB,OAAO,CAAC;CACrC,sBAAsB,MAAM,WAAW,4CAA4C,EAAE,OAAO;CAC5F,8BAA8B;CAC9B,6BAA6B;CAC7B,iBAAiB,MAAM,OAAO,EAAE,UAAU;CAC1C,sBAAsB,MACpB,WACE,OAAO,EAAE,UAAU,SAAS,EAAE,aAAa,KAAA,IAAY,KAAK,OAAO,EAAE,cACrE,EAAE,OACH;CACH,uBAAuB,MAAM,WAAW,iCAAiC,EAAE,OAAO;CAClF,wBAAwB,MAAM,WAAW,2BAA2B,EAAE,OAAO;CAC7E,oBAAoB,MAAM,kCAAkC,EAAE,QAAQ;CACtE,qBAAqB,MACnB,WAAW,iCAAiC,EAAE,cAAc,EAAE,OAAO;CACxE,CAAC,CACH"}

package/dist/browser/BrowserTool.d.mts

@@ -0,0 +1,58 @@
+import { BrowserError } from "./BrowserError.mjs";
+import { BrowserSession } from "./Browser.mjs";
+import { l as Tool } from "../Tool-2lC_XMth.mjs";
+
+//#region src/browser/BrowserTool.d.ts
+declare namespace BrowserTool_d_exports {
+  export { browserToolkit, clickTool, fillTool, gotoTool, pressTool, scrollTool };
+}
+declare const gotoTool: (session: BrowserSession) => Tool<"browser_goto", {
+  readonly url: string;
+}, unknown, string, BrowserError, never>;
+declare const clickTool: (session: BrowserSession) => Tool<"browser_click", {
+  readonly ref: string;
+}, unknown, string, BrowserError, never>;
+declare const fillTool: (session: BrowserSession) => Tool<"browser_fill", {
+  readonly ref: string;
+  readonly text: string;
+}, unknown, string, BrowserError, never>;
+declare const pressTool: (session: BrowserSession) => Tool<"browser_press", {
+  readonly key: string;
+}, unknown, string, BrowserError, never>;
+declare const scrollTool: (session: BrowserSession) => Tool<"browser_scroll", {
+  readonly direction: "up" | "down";
+}, unknown, string, BrowserError, never>;
+/**
+ * The canonical browser action verbs bundled as a `Toolkit`, closed over a
+ * live `BrowserSession`. Compose it with a recipe-local page-reading tool and
+ * whatever finish/signal tools the agent needs:
+ *
+ *   const toolkit = yield* Toolkit.compose(
+ *     browserToolkit(session),
+ *     Toolkit.make(readPageTool(session), finishTool),
+ *   )
+ *
+ * For an à-la-carte subset, use the individual `gotoTool` / `clickTool` / …
+ * constructors directly. Run a turn's calls with `{ concurrency: 1 }`.
+ */
+declare const browserToolkit: (session: BrowserSession) => {
+  browser_goto: Tool<"browser_goto", {
+    readonly url: string;
+  }, unknown, string, BrowserError, never>;
+  browser_click: Tool<"browser_click", {
+    readonly ref: string;
+  }, unknown, string, BrowserError, never>;
+  browser_fill: Tool<"browser_fill", {
+    readonly ref: string;
+    readonly text: string;
+  }, unknown, string, BrowserError, never>;
+  browser_press: Tool<"browser_press", {
+    readonly key: string;
+  }, unknown, string, BrowserError, never>;
+  browser_scroll: Tool<"browser_scroll", {
+    readonly direction: "up" | "down";
+  }, unknown, string, BrowserError, never>;
+};
+//#endregion
+export { browserToolkit, clickTool, fillTool, gotoTool, pressTool, scrollTool, BrowserTool_d_exports as t };
+//# sourceMappingURL=BrowserTool.d.mts.map

package/dist/browser/BrowserTool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserTool.d.mts","names":[],"sources":["../../src/browser/BrowserTool.ts"],"mappings":";;;;;;;;cAoEa,QAAA,GAAY,OAAA,EAAS,cAAA,KAAc,IAAA;EAAA;oBAAA,YAAA;AAAA,cAcnC,SAAA,GAAa,OAAA,EAAS,cAAA,KAAc,IAAA;EAAA;oBAAA,YAAA;AAAA,cAcpC,QAAA,GAAY,OAAA,EAAS,cAAA,KAAc,IAAA;EAAA;;oBAAA,YAAA;AAAA,cAenC,SAAA,GAAa,OAAA,EAAS,cAAA,KAAc,IAAA;EAAA;oBAAA,YAAA;AAAA,cAcpC,UAAA,GAAc,OAAA,EAAS,cAAA,KAAc,IAAA;EAAA;oBAAA,YAAA;;;;;;;;;;;;;AA3ClD;cAuEa,cAAA,GAAkB,OAAA,EAAS,cAAA;;;sBAAc,YAAA"}