@te-river/opencode-team-mode 1.5.11 → 1.5.13

package/dist/tm/bash-timeout.js

@@ -0,0 +1,100 @@
+/**
+ * Built-in bash TIMEOUT discipline (issue #6 of 2026-09-18).
+ *
+ * Where the 120 s comes from: the host's shell tool resolves
+ * `flags.bashDefaultTimeoutMs ?? 2 * 60 * 1e3` (verified in the shipped
+ * desktop bundle) — so when a model omits `timeout`, 120 s is the HOST
+ * default, and models that do pass one routinely pass 120000+ for a
+ * `Get-ChildItem`.  Three serialised probes then cost the user six minutes
+ * of dead air, and every one of them was allowed to run for a reason no
+ * model ever had.
+ *
+ * The plugin owns no shell timer, so the ONE non-invasive lever is the
+ * official `tool.execute.before` hook, whose `output.args` is explicitly
+ * mutable.  Two ceilings, both opt-out:
+ *   - `TM_BASH_TIMEOUT_PROBE_MS` (default 60 000) — only for a command the
+ *     P3 read-only allowlist already accepts (ls / grep / rg / cat /
+ *     Get-ChildItem …).  A pure probe has no legitimate reason to outlive
+ *     a minute, and this is where the wasted 120 s actually sits.
+ *   - `TM_BASH_TIMEOUT_MAX_MS` (default 0 = OFF) — a global cap for
+ *     everything else.  Off by default on purpose: a build/test run may
+ *     legitimately need minutes, and silently killing one is worse than a
+ *     slow one.  A user who wants the ceiling sets it.
+ *
+ * This clamps a number the model already volunteered; it never ADDS a
+ * timeout where the model supplied none (that would turn the host's default
+ * into OUR default, which is not this plugin's call to make).
+ */
+import { classifyReadonlyCommand } from "./guard.js";
+/** Parse the model-supplied timeout defensively: the host schema says a
+ *  positive integer of MILLISECONDS, but an LLM hands us `"120000"`,
+ *  `120000.0`, or omits it entirely.  Anything unreadable means "no
+ *  timeout was supplied" and is left alone. */
+export function parseTimeoutArg(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        return Math.trunc(raw);
+    if (typeof raw === "string") {
+        const n = Number(raw.trim());
+        if (Number.isFinite(n) && n > 0)
+            return Math.trunc(n);
+    }
+    return null;
+}
+/**
+ * Decide the clamped timeout for one bash call.
+ * `probeMs`/`maxMs` of 0 disable that ceiling.
+ */
+export function resolveBashTimeout(opts) {
+    const t = opts.timeoutMs;
+    if (t === null)
+        return { changed: false, via: "none" };
+    const probe = opts.probeMs > 0 && classifyReadonlyCommand(opts.command, opts.readonlyAllowed).ok;
+    if (probe && t > opts.probeMs)
+        return { changed: true, via: "probe", from: t, to: opts.probeMs };
+    if (opts.maxMs > 0 && t > opts.maxMs)
+        return { changed: true, via: "max", from: t, to: opts.maxMs };
+    if (!probe && opts.maxMs === 0)
+        return { changed: false, via: "none" };
+    return { changed: false, via: "already-short" };
+}
+/**
+ * The hook fragment.  Returns true when it mutated `args.timeout` — the
+ * caller may log that, and the trajectory keeps a count so a user asking
+ * "why did my probe get killed at 60 s?" has an answer.
+ *
+ * Everything here is defensive by contract: `output.args` is `any` on the
+ * host side, a non-bash tool must be untouched, and a malformed payload
+ * must never turn into a thrown error inside a permission-adjacent hook.
+ */
+export function createBashTimeoutHook(deps) {
+    return (input, output) => {
+        try {
+            const tool = String(input?.tool ?? "").trim().toLowerCase();
+            if (tool !== "bash")
+                return false;
+            const args = output?.args;
+            if (!args || typeof args !== "object")
+                return false;
+            const command = typeof args.command === "string" ? args.command : "";
+            if (!command)
+                return false;
+            const verdict = resolveBashTimeout({
+                command,
+                timeoutMs: parseTimeoutArg(args.timeout),
+                probeMs: deps.probeMs,
+                maxMs: deps.maxMs,
+                readonlyAllowed: deps.readonlyAllowed,
+            });
+            if (!verdict.changed)
+                return false;
+            args.timeout = verdict.to;
+            deps.onClamp?.({ via: verdict.via, from: verdict.from, to: verdict.to });
+            return true;
+        }
+        catch {
+            /* a timeout clamp must never break the call it is trying to speed up */
+            return false;
+        }
+    };
+}
+//# sourceMappingURL=bash-timeout.js.map

package/dist/tm/bash-timeout.js.map

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

package/dist/tm/browser.d.ts

@@ -1,30 +1,65 @@
 /**
  * tm_browser — governed interactive browser (Plan C: the user's own
- * Chromium-family browser driven headful over the CDP pipe protocol).
+ * Chromium-family browser, headful by default on desktops).
  *
- * Feasibility proven by smoke (Edge + --remote-debugging-pipe + JSON/NUL
- * framing over fds 3/4 — zero deps, no WebSocket implementation).  Qoder's
- * hardening ideas are ported where the plugin can reach them:
- *   - isolated temp user-data-dir (never the user's real profile);
- *   - per-navigation allowlist enforced at the NETWORK layer via CDP
- *     Fetch.requestPaused (non-allowlisted hosts get BlockedByClient —
- *     the per-hop re-check analog);
- *   - hardened webPreferences are the spawn's own flags (no-first-run,
- *     no-extensions, mute);
- *   - hard per-command timeout + explicit close; dispose kills the child.
+ * T5 engine split (design board ② "TM_BROWSER_ENGINE" + R2 verdict):
+ *   - PRIMARY engine: playwright-core — dynamic import ONLY (the package is
+ *     declared in dependencies but NOT installed at build time; a static
+ *     import would break tsc).  A failed import or node < 20 degrades the
+ *     session to the cdp-legacy engine automatically, per plugin instance.
+ *   - cdp-legacy engine: the original hand-rolled CDP pipe transport
+ *     (JSON + NUL framing over fds 3/4, zero deps — smoke-proven) kept
+ *     verbatim as the fallback.  On cdp-legacy only the core subset works
+ *     (open/navigate/read/screenshot/close + navigate_page/take_screenshot/
+ *     list_pages/evaluate_script aliases); the snapshot-first actions
+ *     (take_snapshot + uid addressing, 16-verb chrome-devtools-mcp surface)
+ *     require the playwright engine.
+ *
+ * Action surface aligns with chrome-devtools-mcp's 16 verbs (R2 mapping):
+ *   navigate_page · take_snapshot · click · fill · hover · drag ·
+ *   press_key · select_page · upload_file · wait_for · evaluate_script ·
+ *   list_console_messages · list_network_requests · list_pages ·
+ *   take_screenshot · handle_dialog
+ * plus the legacy compatibility verbs open / navigate / read /
+ * screenshot / close.  Snapshot-first discipline: take_snapshot returns
+ * the ariaSnapshot YAML with an INJECTED [uid=eN] per node (playwright has
+ * no uid concept — SnapshotIndex below is our own snapshot→locator
+ * registry); follow-up actions address nodes by that uid (or an explicit
+ * selector escape hatch) instead of guessed locators.
+ *
+ * Hardening (unchanged from the CDP era, ported to both engines):
+ *   - isolated temp profile (never the user's real browser profile);
+ *     persistent login is ONLY via an explicit TM_BROWSER_USER_DATA_DIR;
+ *   - domain allowlist enforced at the NETWORK layer on the NAVIGATION
+ *     (playwright context.route / CDP Fetch interception), re-checked on
+ *     every redirect hop; SUBRESOURCES then follow TM_BROWSER_SUBRESOURCE
+ *     (default same-site: passive types load, an executable resource loads
+ *     when it belongs to a site this session opened).  Gating every request
+ *     by the content allowlist is what made pages render picture-less — the
+ *     21 seeded hosts contain no CDN, so img/css/js died silently;
+ *   - out-of-allowlist open/navigate routes through the OFFICIAL dialog
+ *     BEFORE any spawn; approved hosts also pass the network layer;
+ *   - hardened context: real-Chrome UA + zh-CN Accept-Language,
+ *     no-first-run / no-extensions / mute launch flags, 3 s default action
+ *     timeout (the prompt's "3000 ms budget" is the tool's default, not an
+ *     aspiration), no networkidle waits anywhere;
+ *   - dispose AWAITS the close, and an idle session reaps itself
+ *     (TM_BROWSER_IDLE_MS) — an orphaned visible window is a user-facing bug.
  *
  * Environment adaptivity (different OpenCode hosts):
  *   - headful by default (Plan C); display-less Linux (no DISPLAY/
  *     WAYLAND_DISPLAY) automatically falls back to headless; TM_BROWSER_
  *     HEADLESS=1|0 forces either way;
- *   - browser discovery: TM_BROWSER_PATH override, then the USER'S DEFAULT
- *     browser (Windows registry / Linux xdg-settings) when it is
- *     Chromium-family — CDP's pipe protocol is Chromium-only, so Firefox as
- *     default falls through — then per-OS candidate paths (Edge first on
- *     Windows; Chrome/Chromium elsewhere).  No browser → structured error,
- *     the agent falls back to tm_webfetch / user MCP tools.
+ *   - browser discovery (SHARED by both engines): TM_BROWSER_PATH
+ *     override, then the USER'S DEFAULT browser (Windows registry / Linux
+ *     xdg-settings) when it is Chromium-family — CDP is Chromium-proprietary
+ *     and playwright channels only speak Chromium too, so a Firefox default
+ *     falls through — then per-OS candidate paths (Edge first on Windows;
+ *     Chrome/Chromium elsewhere).  No browser → structured error, the agent
+ *     falls back to tm_webfetch / user MCP tools.
  *
- * Role access mirrors tm_webfetch: network roles (team + researcher) only.
+ * Role access mirrors tm_webfetch: network roles (team + researcher) only,
+ * tester browser-only (UI verification).
  */
 import type { ToolResult } from "../types.js";
 import type { TmConfig } from "./config.js";
@@ -34,7 +69,9 @@ export type CommandRunner = (cmd: string, args: string[]) => string;
 export declare function isChromiumFamily(exePath: string): boolean;
 /** Parse `reg query "...UrlAssociations\http\UserChoice" /v ProgId` output. */
 export declare function parseProgId(stdout: string): string | null;
-/** Parse `reg query "...\shell\open\command" /ve` output → exe path. */
+/** Parse `reg query "...\shell\open\command" /ve` output → exe path.
+ *  The quoted capture stops at the closing quote, so the `" -- %1"` style
+ *  URL-template tail never leaks into the returned path. */
 export declare function parseRegCommand(stdout: string): string | null;
 /** Parse the Exec= line of an xdg .desktop file. */
 export declare function parseDesktopExec(text: string): string | null;
@@ -42,6 +79,18 @@ export declare function parseDesktopExec(text: string): string | null;
  *  null → the caller falls back to the per-OS probe list (detection is
  *  best-effort and must never throw into tool discovery). */
 export declare function defaultBrowserExecutable(env?: Record<string, string | undefined>, run?: CommandRunner): string | null;
+/** Playwright's `channel` launch IGNORES the executable we discovered —
+ *  `channel:"msedge"` resolves whatever playwright thinks the stable Edge is,
+ *  so a correct Edge-Beta discovery still opened stable (the decisive half of
+ *  the 2026-09-18 report).  The channel spelling is therefore only correct
+ *  for the exact stable-channel install dir; everything else (Beta/Dev/
+ *  Canary, portable, an explicit TM_BROWSER_PATH) rides on executablePath. */
+export declare function playwrightLaunchTarget(executable: string, opts?: {
+    explicitOverride?: boolean;
+}): {
+    executablePath: string;
+    channel?: string;
+};
 /** Resolve the browser executable: TM_BROWSER_PATH override → the user's
  *  DEFAULT browser (Chromium-family only) → per-OS candidate paths.
  *  %LOCALAPPDATA% style vars are expanded on win32. */
@@ -54,15 +103,196 @@ export declare function findBrowserExecutable(env?: Record<string, string | unde
  *   display possible (Linux without DISPLAY/WAYLAND_DISPLAY).
  */
 export declare function resolveHeadless(env?: Record<string, string | undefined>): boolean;
+/** Approximate registrable site (eTLD+1) of a hostname. */
+export declare function siteOf(host: string): string;
+/** playwright and CDP spell resource types differently (`Image` vs `image`,
+ *  `Stylesheet` vs `stylesheet`) — one normalizer keeps both engines on the
+ *  same verdict table. */
+export declare function normalizeResourceType(raw: unknown): string;
+export declare function isPassiveResource(raw: unknown): boolean;
+/**
+ * One subresource verdict, shared VERBATIM by both engines so playwright and
+ * cdp-legacy can never drift.  `allowedSites` holds the registrable sites of
+ * every host this session actually navigated to (allowlist hit or dialog
+ * approval), which is what makes a page's own JS/CSS work without opening
+ * the whole internet: the governance boundary moves from "21 content domains"
+ * to "the site you approved", and an off-site SCRIPT still needs a dialog.
+ */
+export declare function subresourcePass(opts: {
+    url: string;
+    resourceType: unknown;
+    policy: "same-site" | "passive" | "off";
+    allowlistHit: boolean;
+    approvedHost: boolean;
+    allowedSites: ReadonlySet<string>;
+}): {
+    pass: boolean;
+    via: string;
+};
+/** A navigation (or a host the dialog approved) widens the subresource
+ *  footprint to its own site.  Called for EVERY top-level/document request
+ *  that passed the allowlist side. */
+export declare function rememberSite(allowedSites: Set<string>, url: string): void;
+export type BrowserEngineKind = "playwright" | "cdp-legacy";
+/** playwright-core 1.63 targets node >= 20; on anything older we refuse the
+ *  engine up-front and stay on the zero-dependency CDP pipe (the node>=18
+ *  package floor keeps the plugin itself loadable — only the playwright
+ *  PRIMARY is gated here, cdp-legacy carries node 18/19 hosts). */
+export declare const PLAYWRIGHT_MIN_NODE_MAJOR = 20;
+/** "v22.3.1" / "20" -> major number; unparseable -> 0 (fail toward the
+ *  always-available cdp-legacy engine). */
+export declare function nodeMajorOf(version: string): number;
+export interface EngineSelection {
+    kind: BrowserEngineKind;
+    /** The imported playwright-core namespace (present iff kind=playwright). */
+    pw?: PwModule;
+    /** Why this kind was chosen (preference / node gate / import failure). */
+    reason?: string;
+}
+/** The REAL loader — a VARIABLE specifier so tsc never tries to resolve
+ *  "playwright-core" at build time (types ship inside the package, which may
+ *  be absent from node_modules).  Under ESM, import(variable) yields the
+ *  module namespace typed as any. */
+export declare function defaultImportPlaywright(): Promise<unknown>;
+/** Pure engine-selection seam (exported for test-browser.mjs):
+ *  cdp-legacy preference → legacy WITHOUT ever importing; node < 20 →
+ *  legacy without importing; playwright preference → import, verify the
+ *  chromium.launch shape, degrade to legacy on ANY failure. */
+export declare function selectBrowserEngine(opts: {
+    preference: string | undefined;
+    nodeMajor: number;
+    importPlaywright: () => Promise<unknown>;
+}): Promise<EngineSelection>;
+export interface PwModule {
+    chromium: {
+        launch(opts: Record<string, unknown>): Promise<PwBrowser>;
+        launchPersistentContext(userDataDir: string, opts: Record<string, unknown>): Promise<PwBrowserContext>;
+    };
+}
+export interface PwBrowser {
+    newContext(opts?: Record<string, unknown>): Promise<PwBrowserContext>;
+    close(): Promise<void>;
+}
+export interface PwBrowserContext {
+    route(pattern: string, handler: (route: PwRoute, request: PwRequestInfo) => Promise<void> | void): Promise<void> | void;
+    pages(): PwPage[];
+    newPage(): Promise<PwPage>;
+    close(): Promise<void>;
+}
+export interface PwPage {
+    goto(url: string, opts?: Record<string, unknown>): Promise<unknown>;
+    locator(selector: string): PwLocator;
+    getByRole(role: string, opts?: Record<string, unknown>): PwLocator;
+    getByText(text: string): PwLocator;
+    keyboard: {
+        press(key: string): Promise<unknown>;
+    };
+    evaluate(pageFunction: string): Promise<unknown>;
+    screenshot(opts?: Record<string, unknown>): Promise<Uint8Array>;
+    on(event: string, handler: (...args: any[]) => void): void;
+    url(): string;
+    title?(): Promise<string>;
+    bringToFront?(): Promise<void>;
+}
+export interface PwLocator {
+    ariaSnapshot(): Promise<string>;
+    click(): Promise<unknown>;
+    fill(value: string): Promise<unknown>;
+    hover(): Promise<unknown>;
+    pressKey(key: string): Promise<unknown>;
+    setInputFiles(files: string | string[]): Promise<unknown>;
+    waitFor(opts?: Record<string, unknown>): Promise<unknown>;
+    nth(index: number): PwLocator;
+    dragTo(target: PwLocator): Promise<unknown>;
+}
+export interface PwRoute {
+    continue(): Promise<unknown>;
+    abort(): Promise<unknown>;
+}
+export interface PwRequestInfo {
+    url(): string;
+    method?(): string;
+    /** playwright resource type ("document"|"script"|"image"|…).  Optional on
+     *  the seam so a stale mock cannot break the gate — an absent type is
+     *  treated as EXECUTABLE (the strict side of the subresource policy). */
+    resourceType?(): string;
+}
+export interface PwConsoleMessage {
+    type(): string;
+    text(): string;
+}
+export interface PwResponseInfo {
+    url(): string;
+    status(): number;
+    request(): PwRequestInfo;
+}
+export interface PwDialog {
+    type(): string;
+    message(): string;
+    accept(promptText?: string): Promise<unknown>;
+    dismiss(): Promise<unknown>;
+}
+export interface SnapshotEntry {
+    role: string;
+    name?: string;
+    nth: number;
+}
+/** ariaSnapshot yields plain YAML with NO addressable id, while the
+ *  chrome-devtools-mcp muscle memory this tool aligns to is uid-addressed.
+ *  The missing layer is built here: each take_snapshot re-indexes every YAML
+ *  node (`- <role> "<name>" …`), injects `[uid=eN]` inline, and remembers
+ *  (role, name, nth-of-kind); later actions resolve uid →
+ *  `page.getByRole(role, { name, exact: true }).nth(nth)`.  Uids are
+ *  renumbered on every snapshot (one action, one observation); an
+ *  unknown/stale uid errors back to take_snapshot instead of falling back
+ *  to guessed locators. */
+export declare class SnapshotIndex {
+    private entries;
+    private next;
+    get size(): number;
+    /** Reset + parse + annotate the ariaSnapshot YAML in one pass. */
+    annotate(yaml: string): string;
+    get(uid: string): SnapshotEntry | undefined;
+    /** uid → playwright locator; null = unknown uid / role the engine cannot
+     *  address (the caller renders the take_snapshot-first guidance). */
+    locatorFor(page: PwPage, uid: string): PwLocator | null;
+}
+/** ariaSnapshot escapes whitespace/quotes inside names (\s \n \t \" \\). */
+export declare function unescapeAriaName(raw: string): string;
+/** The 16 canonical verbs, named byte-identical to chrome-devtools-mcp. */
+export declare const BROWSER_PLAYWRIGHT_ACTIONS: readonly ["navigate_page", "take_snapshot", "click", "fill", "hover", "drag", "press_key", "select_page", "upload_file", "wait_for", "evaluate_script", "list_console_messages", "list_network_requests", "list_pages", "take_screenshot", "handle_dialog"];
+/** Legacy compat verbs that ride on top of the 16 (both engines). */
+export declare const BROWSER_COMPAT_ACTIONS: readonly ["open", "navigate", "read", "screenshot", "close"];
+/** What the cdp-legacy fallback can still do (R2: degradation must keep the
+ *  §6o behavior; everything snapshot-shaped is playwright-only). */
+export declare const BROWSER_LEGACY_ACTIONS: readonly ["open", "navigate", "navigate_page", "read", "screenshot", "take_screenshot", "list_pages", "evaluate_script", "close"];
 export declare function buildTmBrowserTool(deps: {
     pipelines: TmPipelines;
     cfg: TmConfig;
     env?: Record<string, string | undefined>;
     args?: Record<string, unknown>;
+    /** Test seam: replace the dynamic playwright-core import. */
+    importPlaywright?: () => Promise<unknown>;
+    /** Test seam: pretend node major version for the engine gate. */
+    nodeMajor?: number;
+    /** Best-effort user notification (host toast) — used by the idle reaper,
+     *  which closes a window the agent forgot and must say so out loud. */
+    notify?: (message: string) => void;
+    /** Test seam for the DISCOVERY result (not the TM_BROWSER_PATH override —
+     *  the override is read from env so the channel-substitution rule stays
+     *  honest in tests too). */
+    findExecutable?: (env: Record<string, string | undefined>) => string | null;
 }): {
     description: string;
     args: Record<string, unknown>;
     execute: (rawArgs: Record<string, unknown>, ctx: unknown) => Promise<ToolResult>;
-    dispose: () => void;
+    /** Async on purpose: the host's `dispose` hook is `() => Promise<void>`,
+     *  and a fire-and-forget close could exit before the browser child was
+     *  killed (leaving a visible orphan window). */
+    dispose: () => Promise<void>;
+    engineInfo: () => {
+        kind: BrowserEngineKind | null;
+        reason: string | null;
+    };
 };
 //# sourceMappingURL=browser.d.ts.map

package/dist/tm/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/tm/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AA0BjD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;AAWnE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;6DAE6D;AAC7D,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,GAAG,GAAE,aAA6B,GACjC,MAAM,GAAG,IAAI,CAmCf;AAED;;uDAEuD;AACvD,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,GAAG,IAAI,CAkB1G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAM9F;AA0FD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,SAAS,EAAE,WAAW,CAAA;IACtB,GAAG,EAAE,QAAQ,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B,GAAG;IACF,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAChF,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAiPA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/tm/browser.ts"],"names":[],"mappings":"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"}