@mercuryo-ai/agentbrowse 0.2.50

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## Unreleased
+
+- switched the library extraction API to `extract(session, schema, scopeRef?)`, where
+  `schema` is a plain schema object or a Zod schema
+- made `observe(...)` return a top-level flat `targets` array alongside grouped
+  `scopes`
+- exported named observe payload types and extraction schema types from the
+  public library surface
+- replaced `ReturnType<typeof ...>` client method signatures with named result
+  types
+- added runnable examples under `examples/`
+- added public API reference and troubleshooting guides
+- aligned package metadata with the public `nuanu-ai/agentbrowse` repository

package/README.md

@@ -0,0 +1,335 @@
+# @mercuryo-ai/agentbrowse
+
+Browser automation library for agent systems.
+
+AgentBrowse is for the part of your system that has to work with a real web
+page.
+
+If your application already knows what it is trying to do, AgentBrowse gives
+you the browser layer for that work:
+
+- launch a managed browser or attach to an existing CDP browser session;
+- inspect the current page;
+- interact with stable target references instead of raw selectors;
+- extract structured data from the page;
+- optionally use an LLM when page understanding needs help.
+
+Your app keeps control of orchestration, state, policies, and business logic.
+AgentBrowse focuses on the page itself.
+
+A good first way to think about it is:
+
+1. launch a browser or attach to one and get a `session`
+2. inspect the page with `observe(...)`
+3. use `act(...)` to interact with what you found
+4. use `extract(...)` when you need structured data instead of an action
+5. close the session when you are done
+
+This makes AgentBrowse fit naturally into a worker, backend service, CLI, or
+agent runtime that already exists.
+
+## Install
+
+```bash
+npm i @mercuryo-ai/agentbrowse
+```
+
+If you want the operator-facing CLI, install `@mercuryo-ai/agentbrowse-cli`.
+
+## The Core Mental Model
+
+There are four ideas you need to understand before using the library:
+
+- `session`
+  The handle for a running browser. `launch(...)` or `attach(...)` returns it,
+  and you pass it into the rest of the API.
+- `observe`
+  Reads the page and tells you what AgentBrowse found: targets, scopes,
+  signals, and forms.
+- `ref`
+  A stable reference returned by `observe(...)`. You use it with `act(...)`
+  instead of managing selectors yourself.
+- `assistive runtime`
+  Optional LLM-backed page understanding. You only need it for extraction and
+  for better quality in some goal-based `observe(session, goal)` calls.
+
+## Quick Start
+
+This is the normal managed-browser flow. It does not require LLM setup.
+
+```ts
+import {
+  act,
+  close,
+  launch,
+  navigate,
+  observe,
+  screenshot,
+  status,
+} from '@mercuryo-ai/agentbrowse';
+
+const launchResult = await launch('https://example.com');
+if (!launchResult.success) {
+  throw new Error(launchResult.reason ?? launchResult.message);
+}
+
+const { session } = launchResult;
+
+try {
+  const observeResult = await observe(session);
+  if (!observeResult.success) {
+    throw new Error(observeResult.reason ?? observeResult.message);
+  }
+
+  const firstActionableTarget = observeResult.targets.find((target) => typeof target.ref === 'string');
+
+  if (firstActionableTarget?.ref) {
+    const actResult = await act(session, firstActionableTarget.ref, 'click');
+    if (!actResult.success) {
+      throw new Error(actResult.reason ?? actResult.message);
+    }
+  }
+
+  const navigateResult = await navigate(session, 'https://example.com/checkout');
+  if (!navigateResult.success) {
+    throw new Error(navigateResult.reason ?? navigateResult.message);
+  }
+
+  const screenshotResult = await screenshot(session, '/tmp/checkout.png');
+  if (!screenshotResult.success) {
+    throw new Error(screenshotResult.reason ?? screenshotResult.message);
+  }
+
+  const statusResult = await status(session);
+  if (!statusResult.success) {
+    throw new Error(statusResult.reason ?? statusResult.message);
+  }
+} finally {
+  await close(session);
+}
+```
+
+Runnable examples live in [`examples/`](./examples/README.md):
+
+- `npx tsx examples/basic.ts`
+- `npx tsx examples/attach.ts`
+- `npx tsx examples/extract.ts`
+
+## Managed Launch Runtime Note
+
+When you use `launch(...)`, the package includes `puppeteer` for the managed
+browser connection layer with stealth evasions enabled by default.
+
+The goal is practical: reduce unnecessary anti-bot friction such as extra
+captcha or challenge pages on sensitive sites.
+
+After the browser is up, the normal live browser interaction flow still runs
+over Playwright CDP.
+
+The library entrypoint does not load `.env` files. Environment loading is only
+part of the CLI entrypoint.
+
+## Attach To An Existing Browser
+
+If you already have a browser that exposes a CDP websocket, use `attach(...)`
+instead of `launch(...)`.
+
+That works for:
+
+- a local Chrome or Chromium process started with remote debugging enabled;
+- a cloud browser session that gives you a CDP websocket URL;
+- any other browser runtime that Playwright can reach through CDP.
+
+```ts
+import { attach, observe } from '@mercuryo-ai/agentbrowse';
+
+const attached = await attach('ws://127.0.0.1:9222/devtools/browser/browser-id');
+if (!attached.success) {
+  throw new Error(attached.reason ?? attached.message);
+}
+
+const observeResult = await observe(attached.session);
+if (!observeResult.success) {
+  throw new Error(observeResult.reason ?? observeResult.message);
+}
+```
+
+If your provider gives you a labeled remote session, you can carry that label
+in the session handle:
+
+```ts
+const attached = await attach(remoteCdpUrl, {
+  provider: 'browserbase',
+});
+```
+
+## What Each Main API Does
+
+| API | Use it when | Typical result |
+| --- | --- | --- |
+| `launch(url?, options?)` | You need a new browser session | `session`, current `url`, current `title` |
+| `attach(cdpUrl, options?)` | You already have a running browser that exposes CDP | `session`, current `url`, current `title` |
+| `observe(session, goal?)` | You want to understand the page | targets, scopes, signals, fillable forms |
+| `act(session, targetRef, action, value?)` | You want to click, type, select, fill, or press | action result and target metadata |
+| `navigate(session, url)` | You want to move to another page | page metadata after navigation |
+| `extract(session, schema, scopeRef?)` | You want structured JSON from the page | `data` that matches your schema |
+| `screenshot(session, path?)` | You want a screenshot artifact | saved path and page metadata |
+| `status(session)` | You want to know whether the session is still healthy | liveness, page info, runtime summary |
+| `close(session)` | You are done with the browser | close result |
+
+Two common questions:
+
+- `observe(session)` gives you a general inventory of the page.
+- `observe(session, goal)` focuses that inventory around a question such as
+  `"find the checkout total"` or `"find the email field"`.
+
+All main APIs return the same broad result shape:
+
+- success path: `{ success: true, ... }`
+- failure path: `{ success: false, error, message, reason, ... }`
+
+## When You Need An Assistive Runtime
+
+You only need assistive runtime when AgentBrowse should call an LLM.
+
+In practice, that mainly means:
+
+- `extract(...)`
+- better quality goal-based `observe(session, goal)`
+
+The runtime contract is intentionally small: you provide an object that can
+create an OpenAI-compatible chat-completions client.
+
+```ts
+import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
+
+const client = createAgentbrowseClient({
+  assistiveRuntime: {
+    createLlmClient: () => ({
+      async createChatCompletion(args) {
+        const { messages, response_model, image, temperature, maxOutputTokens } = args.options;
+
+        const result = await callStructuredProvider({
+          messages,
+          responseModel: response_model,
+          image,
+          temperature,
+          maxOutputTokens,
+        });
+
+        return {
+          data: result.data,
+          usage: result.usage,
+        };
+      },
+    }),
+  },
+});
+```
+
+The same pattern works for OpenRouter and other OpenAI-compatible backends.
+
+See:
+
+- [Assistive Runtime Guide](./docs/assistive-runtime.md)
+
+## Session Persistence, Proxy, And Diagnostics
+
+Normal usage is explicit-session based:
+
+1. call `launch(...)` or `attach(...)`
+2. keep the returned `session`
+3. pass that session into later calls
+
+If you want to restore a session across process runs, use the optional store
+helpers:
+
+```ts
+import {
+  createBrowserSessionStore,
+  loadBrowserSession,
+  saveBrowserSession,
+} from '@mercuryo-ai/agentbrowse';
+
+saveBrowserSession(session);
+const restored = loadBrowserSession();
+
+const store = createBrowserSessionStore({
+  rootDir: '/tmp/my-app/browser-state',
+});
+
+store.save(session);
+const restoredFromCustomRoot = store.load();
+```
+
+If you want to use a proxy, pass it directly to `launch(...)`:
+
+```ts
+const launchResult = await launch('https://example.com', {
+  useProxy: true,
+  proxy: 'http://user:pass@proxy.example:8080',
+});
+```
+
+Diagnostics are optional. If you need tracing or custom logging, use a client:
+
+```ts
+import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
+
+const client = createAgentbrowseClient({
+  diagnostics: {
+    startStep() {
+      return {
+        finish() {},
+      };
+    },
+  },
+});
+```
+
+See:
+
+- [Configuration Guide](./docs/configuration.md)
+
+## Testing Wrappers Around AgentBrowse
+
+If your package wraps AgentBrowse and you want a stable test helper for the
+assistive runtime contract, use the dedicated testing subpath:
+
+```ts
+import {
+  installFetchBackedTestAssistiveRuntime,
+  uninstallTestAssistiveRuntime,
+} from '@mercuryo-ai/agentbrowse/testing';
+```
+
+See:
+
+- [Testing Guide](./docs/testing.md)
+
+## Protected Fill
+
+Protected fill is for cases where your application already has sensitive values
+and wants AgentBrowse to apply them to a previously observed form through a
+guarded browser execution path.
+
+Import it separately:
+
+```ts
+import { fillProtectedForm } from '@mercuryo-ai/agentbrowse/protected-fill';
+```
+
+See:
+
+- [Protected Fill Guide](./docs/protected-fill.md)
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md)
+- [API Reference](./docs/api-reference.md)
+- [Configuration Guide](./docs/configuration.md)
+- [Assistive Runtime Guide](./docs/assistive-runtime.md)
+- [Protected Fill Guide](./docs/protected-fill.md)
+- [Integration Checklist](./docs/integration-checklist.md)
+- [Testing Guide](./docs/testing.md)
+- [Troubleshooting](./docs/troubleshooting.md)

package/dist/assistive-runtime.d.ts

@@ -0,0 +1,110 @@
+import type { Stagehand } from '@browserbasehq/stagehand';
+import type { z } from 'zod';
+import type { BrowserSessionState } from './browser-session-state.js';
+/** Token usage reported by an assistive LLM provider. */
+export interface AgentbrowseAssistiveLlmUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    cached_input_tokens?: number;
+    reasoning_tokens?: number;
+}
+/** Single text-or-image content entry in an assistive user message. */
+export type AgentbrowseAssistiveMessageContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail: 'auto';
+    };
+};
+/** Single assistive chat message sent to the configured LLM client. */
+export interface AgentbrowseAssistiveChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string | AgentbrowseAssistiveMessageContentPart[];
+}
+/** Optional screenshot-style image payload passed to the assistive runtime. */
+export interface AgentbrowseAssistiveImageInput {
+    buffer: Buffer;
+    description?: string;
+}
+/** Structured output contract requested from the assistive runtime. */
+export interface AgentbrowseAssistiveResponseModel {
+    name: string;
+    schema: z.ZodTypeAny;
+}
+/** Request options passed to `createChatCompletion(...)`. */
+export interface AgentbrowseAssistiveChatCompletionOptions {
+    messages: AgentbrowseAssistiveChatMessage[];
+    response_model?: AgentbrowseAssistiveResponseModel;
+    temperature?: number;
+    maxOutputTokens?: number;
+    image?: AgentbrowseAssistiveImageInput;
+}
+/** Single structured assistive LLM request. */
+export interface AgentbrowseAssistiveChatCompletionRequest {
+    logger?: (...args: unknown[]) => void;
+    options: AgentbrowseAssistiveChatCompletionOptions;
+}
+/** Structured assistive LLM response returned to AgentBrowse. */
+export interface AgentbrowseAssistiveChatCompletionResult<T = unknown> {
+    data: T;
+    usage?: AgentbrowseAssistiveLlmUsage;
+}
+/** Minimal LLM client contract required by assistive AgentBrowse features. */
+export interface AgentbrowseAssistiveLlmClient {
+    createChatCompletion<T = unknown>(args: AgentbrowseAssistiveChatCompletionRequest): Promise<AgentbrowseAssistiveChatCompletionResult<T>>;
+}
+/** Assistive runtime configuration for goal-based observe and extract flows. */
+export interface AgentbrowseAssistiveRuntime {
+    createLlmClient: () => AgentbrowseAssistiveLlmClient;
+    connectStagehand?: (input: {
+        cdpUrl: string;
+        llmClient: AgentbrowseAssistiveLlmClient;
+    }) => Promise<Stagehand>;
+}
+export declare class AgentbrowseAssistiveRuntimeMissingError extends Error {
+    readonly feature: string;
+    constructor(feature: string);
+}
+export declare class AssistiveStructuredOutputTruncatedError extends Error {
+    readonly status: number;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly finishReason?: string;
+    readonly maxOutputTokens?: number;
+    readonly completionTokens?: number;
+    constructor(message: string, params: {
+        status: number;
+        provider?: string;
+        model?: string;
+        finishReason?: string;
+        maxOutputTokens?: number;
+        completionTokens?: number;
+    });
+}
+export declare function configureAgentbrowseAssistiveRuntime(runtime: AgentbrowseAssistiveRuntime | null): void;
+export declare function resetAgentbrowseAssistiveRuntime(): void;
+/** Returns a best-effort assistive LLM client for the provided session or runtime. */
+export declare function tryCreateAgentbrowseAssistiveLlmClient(options?: {
+    session?: BrowserSessionState | null;
+    runtime?: AgentbrowseAssistiveRuntime | null;
+}): AgentbrowseAssistiveLlmClient | null;
+/** Returns `true` when assistive LLM-backed features can run for the session. */
+export declare function canUseAgentbrowseAssistiveLlmClient(options?: {
+    session?: BrowserSessionState | null;
+    runtime?: AgentbrowseAssistiveRuntime | null;
+}): boolean;
+/** Returns the configured assistive LLM client or throws when none is available. */
+export declare function requireAgentbrowseAssistiveLlmClient(feature: string, options?: {
+    session?: BrowserSessionState | null;
+    runtime?: AgentbrowseAssistiveRuntime | null;
+}): AgentbrowseAssistiveLlmClient;
+/** Connects Stagehand through the configured assistive runtime for the session. */
+export declare function connectConfiguredAssistiveStagehand(cdpUrl: string, options?: {
+    session?: BrowserSessionState | null;
+    runtime?: AgentbrowseAssistiveRuntime | null;
+}): Promise<Stagehand>;
+//# sourceMappingURL=assistive-runtime.d.ts.map

package/dist/assistive-runtime.d.ts.map

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

package/dist/assistive-runtime.js

@@ -0,0 +1,79 @@
+import { getAgentbrowseSessionBindings } from './client-bindings.js';
+import { connectStagehand } from './stagehand.js';
+export class AgentbrowseAssistiveRuntimeMissingError extends Error {
+    feature;
+    constructor(feature) {
+        super(`AgentBrowse assistive runtime is not configured for ${feature}. Configure it in the orchestration layer before using assistive browser features.`);
+        this.name = 'AgentbrowseAssistiveRuntimeMissingError';
+        this.feature = feature;
+    }
+}
+export class AssistiveStructuredOutputTruncatedError extends Error {
+    status;
+    provider;
+    model;
+    finishReason;
+    maxOutputTokens;
+    completionTokens;
+    constructor(message, params) {
+        super(message);
+        this.name = 'AssistiveStructuredOutputTruncatedError';
+        this.status = params.status;
+        this.provider = params.provider;
+        this.model = params.model;
+        this.finishReason = params.finishReason;
+        this.maxOutputTokens = params.maxOutputTokens;
+        this.completionTokens = params.completionTokens;
+    }
+}
+let configuredAssistiveRuntime = null;
+function resolveAssistiveRuntime(options = {}) {
+    if (options.runtime) {
+        return options.runtime;
+    }
+    const boundRuntime = options.session
+        ? (getAgentbrowseSessionBindings(options.session)?.assistiveRuntime ?? null)
+        : null;
+    return boundRuntime ?? configuredAssistiveRuntime;
+}
+export function configureAgentbrowseAssistiveRuntime(runtime) {
+    configuredAssistiveRuntime = runtime;
+}
+export function resetAgentbrowseAssistiveRuntime() {
+    configuredAssistiveRuntime = null;
+}
+/** Returns a best-effort assistive LLM client for the provided session or runtime. */
+export function tryCreateAgentbrowseAssistiveLlmClient(options = {}) {
+    return resolveAssistiveRuntime(options)?.createLlmClient() ?? null;
+}
+/** Returns `true` when assistive LLM-backed features can run for the session. */
+export function canUseAgentbrowseAssistiveLlmClient(options = {}) {
+    try {
+        return tryCreateAgentbrowseAssistiveLlmClient(options) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/** Returns the configured assistive LLM client or throws when none is available. */
+export function requireAgentbrowseAssistiveLlmClient(feature, options = {}) {
+    const client = tryCreateAgentbrowseAssistiveLlmClient(options);
+    if (!client) {
+        throw new AgentbrowseAssistiveRuntimeMissingError(feature);
+    }
+    return client;
+}
+/** Connects Stagehand through the configured assistive runtime for the session. */
+export async function connectConfiguredAssistiveStagehand(cdpUrl, options = {}) {
+    const runtime = resolveAssistiveRuntime(options);
+    const llmClient = requireAgentbrowseAssistiveLlmClient('assistive stagehand execution', options);
+    if (runtime?.connectStagehand) {
+        return runtime.connectStagehand({
+            cdpUrl,
+            llmClient,
+        });
+    }
+    return connectStagehand(cdpUrl, {
+        llmClient,
+    });
+}

package/dist/assistive-runtime.test-support.d.ts

@@ -0,0 +1,7 @@
+export declare function installFetchBackedTestAssistiveRuntime(options?: {
+    apiKey?: string;
+    apiUrl?: string;
+    model?: string;
+}): void;
+export declare function uninstallTestAssistiveRuntime(): void;
+//# sourceMappingURL=assistive-runtime.test-support.d.ts.map

package/dist/assistive-runtime.test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistive-runtime.test-support.d.ts","sourceRoot":"","sources":["../src/assistive-runtime.test-support.ts"],"names":[],"mappings":"AA4FA,wBAAgB,sCAAsC,CACpD,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,IAAI,CA2EN;AAED,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/assistive-runtime.test-support.js

@@ -0,0 +1,106 @@
+import { toJsonSchema } from '@browserbasehq/stagehand';
+import { AssistiveStructuredOutputTruncatedError, configureAgentbrowseAssistiveRuntime, resetAgentbrowseAssistiveRuntime, } from './assistive-runtime.js';
+function readString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function readNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function normalizeApiUrl(value) {
+    return value.replace(/\/$/, '');
+}
+function normalizeUsage(usage) {
+    if (!usage ||
+        typeof usage.prompt_tokens !== 'number' ||
+        typeof usage.completion_tokens !== 'number' ||
+        typeof usage.total_tokens !== 'number') {
+        return undefined;
+    }
+    return usage;
+}
+function buildMessages(options) {
+    const messages = [...options.messages];
+    if (!options.image) {
+        return messages;
+    }
+    const content = [];
+    if (options.image.description?.trim()) {
+        content.push({ type: 'text', text: options.image.description.trim() });
+    }
+    content.push({
+        type: 'image_url',
+        image_url: {
+            url: `data:image/jpeg;base64,${options.image.buffer.toString('base64')}`,
+            detail: 'auto',
+        },
+    });
+    messages.push({
+        role: 'user',
+        content,
+    });
+    return messages;
+}
+export function installFetchBackedTestAssistiveRuntime(options = {}) {
+    const apiKey = options.apiKey ?? 'ap_test';
+    const apiUrl = normalizeApiUrl(options.apiUrl ?? 'https://example.com/api');
+    const model = options.model ?? 'magicpay';
+    configureAgentbrowseAssistiveRuntime({
+        createLlmClient: () => ({
+            async createChatCompletion({ options, }) {
+                if (!options.response_model) {
+                    throw new Error('Test assistive runtime requires response_model');
+                }
+                const response = await fetch(`${apiUrl}/v1/chat/completions`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: `Bearer ${apiKey}`,
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        model,
+                        messages: buildMessages(options),
+                        response_format: {
+                            type: 'json_schema',
+                            json_schema: {
+                                name: options.response_model.name,
+                                strict: true,
+                                schema: toJsonSchema(options.response_model.schema),
+                            },
+                        },
+                        temperature: options.temperature,
+                        max_completion_tokens: options.maxOutputTokens,
+                    }),
+                });
+                const json = (await response.json());
+                if (!response.ok) {
+                    if (json.error_code === 'structured_output_truncated') {
+                        throw new AssistiveStructuredOutputTruncatedError(`Test assistive runtime error (${response.status})`, {
+                            status: response.status,
+                            provider: readString(json.provider),
+                            model: readString(json.model),
+                            finishReason: readString(json.finish_reason),
+                            maxOutputTokens: readNumber(json.max_output_tokens),
+                            completionTokens: readNumber(json.completion_tokens),
+                        });
+                    }
+                    const message = typeof json.error === 'string'
+                        ? json.error
+                        : `Test assistive runtime HTTP ${response.status}`;
+                    throw new Error(message);
+                }
+                const content = json.choices?.[0]?.message?.content;
+                if (typeof content !== 'string' || content.trim().length === 0) {
+                    throw new Error('Test assistive runtime response missing assistant content');
+                }
+                return {
+                    data: JSON.parse(content),
+                    usage: normalizeUsage(json.usage),
+                };
+            },
+        }),
+    });
+}
+export function uninstallTestAssistiveRuntime() {
+    resetAgentbrowseAssistiveRuntime();
+}

package/dist/assistive-stagehand.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserSessionState } from './browser-session-state.js';
+import type { Stagehand } from '@browserbasehq/stagehand';
+/**
+ * Connect Stagehand with the currently configured assistive runtime.
+ *
+ * This stays separate from the generic Stagehand connector so the browser-core
+ * layer does not own orchestration/backend setup directly.
+ */
+export declare function connectAssistiveStagehand(cdpUrl: string, options?: {
+    session?: BrowserSessionState | null;
+}): Promise<Stagehand>;
+//# sourceMappingURL=assistive-stagehand.d.ts.map

package/dist/assistive-stagehand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistive-stagehand.d.ts","sourceRoot":"","sources":["../src/assistive-stagehand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAG1D;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACjC,GACL,OAAO,CAAC,SAAS,CAAC,CAEpB"}