@namzu/sdk 45.0.0 → 45.1.0

package/dist/tools/builtins/browser-url.js

@@ -0,0 +1,240 @@
+/**
+ * One spelling per address, decided before anyone judges the address.
+ *
+ * The browser tools' `url` and `origin` arguments are canonicalised by their
+ * input schema, and the registry hands the gate and the reviewer the schema's
+ * OUTPUT (`ToolRegistry.prepareExecution`). So a site rule written as
+ * `^https://github\.com(?:[/?#]|$)` is tested against the one spelling the
+ * browser will load, never against `HTTPS://GitHub.com:443/`,
+ * `https://github.com./` or `https://%67ithub.com/`, which name the same page
+ * and would each slip past a deny written for the plain form.
+ *
+ * The canonical form is the WHATWG URL serialisation (`new URL(x).href`),
+ * which already lowercases the scheme and host, converts an internationalised
+ * host to punycode, drops a default port, decodes percent-encoded host bytes
+ * and reads every IPv4 spelling (`2852039166`, `0xA9FEA9FE`,
+ * `0251.0376.0251.0376`, `169.254.43518`) as dotted-quad. On top of that:
+ *
+ * - trailing dots on the host are removed (`github.com.` is `github.com` to
+ *   DNS and to a person, and a different string to a pattern);
+ * - only `http:` and `https:` are accepted, plus the literal `about:blank`;
+ * - an address carrying a user name or password is refused — it is how
+ *   `https://github.com@evil.example/` reads as GitHub to a person;
+ * - cloud metadata endpoints are refused outright, in every spelling the
+ *   parser folds into them. This is a floor, not the site policy: a private
+ *   or loopback address is left to the operator's site rules, and a DNS name
+ *   that RESOLVES to a metadata address is the host's to catch after the
+ *   navigation lands.
+ */
+/** Longest address the tools accept. Longer is not a page anyone meant to name. */
+export const BROWSER_URL_MAX_LENGTH = 8192;
+const ABOUT_BLANK = 'about:blank';
+/** Host names of cloud metadata services. Compared after lowercasing and trailing-dot removal. */
+const METADATA_HOSTNAMES = new Set(['metadata.google.internal', 'metadata', 'metadata.goog']);
+/**
+ * IPv4 metadata endpoints: AWS, GCP, Azure, Oracle and DigitalOcean
+ * (169.254.169.254), and Alibaba Cloud (100.100.100.200).
+ */
+const METADATA_IPV4 = new Set(['169.254.169.254', '100.100.100.200']);
+/** IPv6 metadata endpoints, in the parser's compressed form. AWS Nitro. */
+const METADATA_IPV6 = new Set(['fd00:ec2::254']);
+function stripTrailingDots(hostname) {
+    return hostname.replace(/\.+$/, '');
+}
+/** Eight hextets of a compressed IPv6 literal, or undefined if it is not one. */
+function expandIpv6(address) {
+    const halves = address.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const parse = (part) => {
+        if (part === undefined || part === '')
+            return [];
+        const out = [];
+        for (const piece of part.split(':')) {
+            if (!/^[0-9a-f]{1,4}$/.test(piece))
+                return undefined;
+            out.push(Number.parseInt(piece, 16));
+        }
+        return out;
+    };
+    const head = parse(halves[0]);
+    const tail = parse(halves[1]);
+    if (!head || !tail)
+        return undefined;
+    if (halves.length === 1)
+        return head.length === 8 ? head : undefined;
+    const fill = 8 - head.length - tail.length;
+    if (fill < 1)
+        return undefined;
+    return [...head, ...new Array(fill).fill(0), ...tail];
+}
+function ipv4Of(high, low) {
+    return `${high >>> 8}.${high & 0xff}.${low >>> 8}.${low & 0xff}`;
+}
+/**
+ * IPv4 addresses an IPv6 literal carries in a well-known embedding: mapped
+ * (`::ffff:a.b.c.d`), compatible (`::a.b.c.d`), SIIT (`::ffff:0:a.b.c.d`),
+ * NAT64 (`64:ff9b::/96`, `64:ff9b:1::/48`) and 6to4 (`2002:AABB:CCDD::`).
+ * Each is a way to reach the IPv4 address from an IPv6 spelling.
+ */
+function embeddedIpv4(h) {
+    const out = [];
+    const zero = (from, to) => h.slice(from, to).every((x) => x === 0);
+    const last = ipv4Of(h[6] ?? 0, h[7] ?? 0);
+    if (zero(0, 5) && (h[5] === 0xffff || h[5] === 0))
+        out.push(last);
+    if (zero(0, 4) && h[4] === 0xffff && h[5] === 0)
+        out.push(last);
+    if (h[0] === 0x64 && h[1] === 0xff9b)
+        out.push(last);
+    if (h[0] === 0x2002)
+        out.push(ipv4Of(h[1] ?? 0, h[2] ?? 0));
+    return out;
+}
+/**
+ * Is this host a cloud metadata endpoint, in any spelling the URL parser
+ * folds into one? `hostname` is a URL's `hostname` (IPv6 in brackets) or a
+ * bare name or address.
+ */
+export function isCloudMetadataHost(hostname) {
+    let host = stripTrailingDots(hostname.trim().toLowerCase());
+    if (host === '')
+        return false;
+    // Let the WHATWG parser fold every IPv4 and IPv6 spelling into one.
+    const bracketed = host.startsWith('[') ? host : host.includes(':') ? `[${host}]` : host;
+    try {
+        host = stripTrailingDots(new URL(`http://${bracketed}/`).hostname);
+    }
+    catch {
+        return false;
+    }
+    if (METADATA_HOSTNAMES.has(host) || METADATA_IPV4.has(host))
+        return true;
+    if (!host.startsWith('['))
+        return false;
+    const v6 = host.slice(1, -1);
+    if (METADATA_IPV6.has(v6))
+        return true;
+    const hextets = expandIpv6(v6);
+    if (!hextets)
+        return false;
+    return embeddedIpv4(hextets).some((v4) => METADATA_IPV4.has(v4));
+}
+/**
+ * The one spelling of an address the browser may be sent to, or why not.
+ *
+ * Accepts absolute `http:` and `https:` URLs and `about:blank`. See the
+ * module comment for what is folded and what is refused.
+ */
+export function canonicalizeBrowserUrl(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return { ok: false, reason: 'the address is empty' };
+    if (raw.length > BROWSER_URL_MAX_LENGTH)
+        return { ok: false, reason: `the address is longer than ${BROWSER_URL_MAX_LENGTH} characters` };
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'the address is not an absolute URL; give the full https:// address',
+        };
+    }
+    if (url.protocol === 'about:') {
+        if (url.pathname.toLowerCase() === 'blank' && url.search === '' && url.hash === '')
+            return { ok: true, url: ABOUT_BLANK, origin: 'null' };
+        return { ok: false, reason: 'only about:blank is allowed among about: addresses' };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return {
+            ok: false,
+            reason: `the scheme "${url.protocol}" is not allowed; only http and https addresses (and about:blank) can be opened`,
+        };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return {
+            ok: false,
+            reason: 'the address carries a user name or password (user@host); credentials never go in an address — open the site and let the user sign in',
+        };
+    }
+    const host = stripTrailingDots(url.hostname);
+    if (host === '')
+        return { ok: false, reason: 'the address has no host' };
+    if (host !== url.hostname) {
+        url.hostname = host;
+        // The setter re-parses; a host that did not survive is not one to open.
+        if (stripTrailingDots(url.hostname) !== host)
+            return { ok: false, reason: 'the address host could not be canonicalised' };
+    }
+    if (isCloudMetadataHost(url.hostname)) {
+        return {
+            ok: false,
+            reason: `${url.hostname} is a cloud metadata endpoint, which the browser never opens`,
+        };
+    }
+    return { ok: true, url: url.href, origin: url.origin };
+}
+/**
+ * The canonical origin (`scheme://host[:port]`) a `browser_act` call names,
+ * or why it is not one. A trailing `/` is accepted; a path, query or fragment
+ * is not — the argument is an origin, copied from the snapshot header.
+ */
+export function canonicalizeBrowserOrigin(raw) {
+    const verdict = canonicalizeBrowserUrl(raw);
+    if (!verdict.ok)
+        return verdict;
+    if (verdict.url === ABOUT_BLANK)
+        return { ok: false, reason: 'about:blank has no origin to act on; open a page first' };
+    const url = new URL(verdict.url);
+    if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+        return {
+            ok: false,
+            reason: `"${raw}" is a URL, not an origin; copy the origin from the snapshot header (${url.origin})`,
+        };
+    }
+    return { ok: true, origin: verdict.origin };
+}
+/**
+ * The canonical spelling of a site key an operator or a job grants —
+ * `https://github.com`, `https://*.example.com`, `http://localhost:*` — or
+ * why it is not one.
+ *
+ * The scheme is literal (`http` or `https`). The host may begin with `*.`,
+ * meaning one or more labels in front of the rest. The port may be `*`, any
+ * port; a default port is dropped. The host is lowercased and punycoded like
+ * a URL's. A bare `*`, a path, credentials and metadata hosts are refused.
+ */
+export function canonicalizeBrowserSitePattern(raw) {
+    const trimmed = typeof raw === 'string' ? raw.trim() : '';
+    const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(\*\.)?([^/:?#@]+)(?::(\d{1,5}|\*))?\/?$/.exec(trimmed);
+    if (!match) {
+        return {
+            ok: false,
+            reason: `"${raw}" is not a site; write scheme://host, optionally *.host and :port or :*, with no path`,
+        };
+    }
+    if ((match[3] ?? '').includes('*')) {
+        return {
+            ok: false,
+            reason: `"${raw}" has a wildcard inside the host; a wildcard may only be a leading *. before a domain`,
+        };
+    }
+    const scheme = (match[1] ?? '').toLowerCase();
+    const wildcard = match[2] !== undefined;
+    const port = match[4];
+    if (scheme !== 'http' && scheme !== 'https')
+        return { ok: false, reason: `the scheme "${scheme}:" is not allowed; only http and https` };
+    const probe = canonicalizeBrowserOrigin(`${scheme}://${match[3]}${port !== undefined && port !== '*' ? `:${port}` : ''}`);
+    if (!probe.ok)
+        return { ok: false, reason: probe.reason };
+    const probeUrl = new URL(probe.origin);
+    if (wildcard &&
+        (probeUrl.hostname.startsWith('[') || /^\d+(?:\.\d+){3}$/.test(probeUrl.hostname))) {
+        return { ok: false, reason: 'a wildcard cannot precede an IP address' };
+    }
+    const host = `${wildcard ? '*.' : ''}${probeUrl.hostname}`;
+    const portPart = port === '*' ? ':*' : probeUrl.port !== '' ? `:${probeUrl.port}` : '';
+    return { ok: true, pattern: `${scheme}://${host}${portPart}` };
+}
+//# sourceMappingURL=browser-url.js.map

package/dist/tools/builtins/browser-url.js.map

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

package/dist/tools/builtins/browser.d.ts

@@ -0,0 +1,367 @@
+import { z } from 'zod';
+import type { BrowserHost, BrowserHostError, BrowserPageInfo } from '../../types/browser/index.js';
+import type { ToolDefinition } from '../../types/tool/index.js';
+export declare const BROWSER_TOOL_NAME: "browser";
+export declare const BROWSER_ACT_TOOL_NAME: "browser_act";
+declare const observeSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"action", [z.ZodObject<{
+    action: z.ZodLiteral<"navigate">;
+    url: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    action: "navigate";
+    url: string;
+}, {
+    action: "navigate";
+    url: string;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"back">;
+}, "strip", z.ZodTypeAny, {
+    action: "back";
+}, {
+    action: "back";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"forward">;
+}, "strip", z.ZodTypeAny, {
+    action: "forward";
+}, {
+    action: "forward";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"reload">;
+}, "strip", z.ZodTypeAny, {
+    action: "reload";
+}, {
+    action: "reload";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"snapshot">;
+    ref: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "snapshot";
+    cursor?: string | undefined;
+    ref?: string | undefined;
+}, {
+    action: "snapshot";
+    cursor?: string | undefined;
+    ref?: string | undefined;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"screenshot">;
+    ref: z.ZodOptional<z.ZodString>;
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    action: "screenshot";
+    ref?: string | undefined;
+    fullPage?: boolean | undefined;
+}, {
+    action: "screenshot";
+    ref?: string | undefined;
+    fullPage?: boolean | undefined;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"scroll">;
+    direction: z.ZodEnum<["up", "down", "left", "right"]>;
+    ref: z.ZodOptional<z.ZodString>;
+    amount: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "scroll";
+    direction: "left" | "right" | "up" | "down";
+    amount?: number | undefined;
+    ref?: string | undefined;
+}, {
+    action: "scroll";
+    direction: "left" | "right" | "up" | "down";
+    amount?: number | undefined;
+    ref?: string | undefined;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"wait_for">;
+    text: z.ZodOptional<z.ZodString>;
+    textGone: z.ZodOptional<z.ZodString>;
+    timeMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "wait_for";
+    text?: string | undefined;
+    textGone?: string | undefined;
+    timeMs?: number | undefined;
+}, {
+    action: "wait_for";
+    text?: string | undefined;
+    textGone?: string | undefined;
+    timeMs?: number | undefined;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"tabs">;
+    op: z.ZodEnum<["list", "select", "close", "new"]>;
+    tab: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    action: "tabs";
+    op: "close" | "list" | "select" | "new";
+    url?: string | undefined;
+    tab?: string | undefined;
+}, {
+    action: "tabs";
+    op: "close" | "list" | "select" | "new";
+    url?: string | undefined;
+    tab?: string | undefined;
+}>]>, {
+    action: "navigate";
+    url: string;
+} | {
+    action: "back";
+} | {
+    action: "forward";
+} | {
+    action: "reload";
+} | {
+    action: "snapshot";
+    cursor?: string | undefined;
+    ref?: string | undefined;
+} | {
+    action: "screenshot";
+    ref?: string | undefined;
+    fullPage?: boolean | undefined;
+} | {
+    action: "scroll";
+    direction: "left" | "right" | "up" | "down";
+    amount?: number | undefined;
+    ref?: string | undefined;
+} | {
+    action: "wait_for";
+    text?: string | undefined;
+    textGone?: string | undefined;
+    timeMs?: number | undefined;
+} | {
+    action: "tabs";
+    op: "close" | "list" | "select" | "new";
+    url?: string | undefined;
+    tab?: string | undefined;
+}, {
+    action: "navigate";
+    url: string;
+} | {
+    action: "back";
+} | {
+    action: "forward";
+} | {
+    action: "reload";
+} | {
+    action: "snapshot";
+    cursor?: string | undefined;
+    ref?: string | undefined;
+} | {
+    action: "screenshot";
+    ref?: string | undefined;
+    fullPage?: boolean | undefined;
+} | {
+    action: "scroll";
+    direction: "left" | "right" | "up" | "down";
+    amount?: number | undefined;
+    ref?: string | undefined;
+} | {
+    action: "wait_for";
+    text?: string | undefined;
+    textGone?: string | undefined;
+    timeMs?: number | undefined;
+} | {
+    action: "tabs";
+    op: "close" | "list" | "select" | "new";
+    url?: string | undefined;
+    tab?: string | undefined;
+}>;
+declare const actSchema: z.ZodDiscriminatedUnion<"action", [z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"click">;
+    ref: z.ZodString;
+    doubleClick: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    origin: string;
+    action: "click";
+    ref: string;
+    snapshot?: boolean | undefined;
+    doubleClick?: boolean | undefined;
+}, {
+    origin: string;
+    action: "click";
+    ref: string;
+    snapshot?: boolean | undefined;
+    doubleClick?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"type">;
+    ref: z.ZodString;
+    text: z.ZodString;
+    submit: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    origin: string;
+    action: "type";
+    ref: string;
+    snapshot?: boolean | undefined;
+    submit?: boolean | undefined;
+}, {
+    text: string;
+    origin: string;
+    action: "type";
+    ref: string;
+    snapshot?: boolean | undefined;
+    submit?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"fill_form">;
+    fields: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        value: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        ref: string;
+    }, {
+        value: string;
+        ref: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    origin: string;
+    action: "fill_form";
+    fields: {
+        value: string;
+        ref: string;
+    }[];
+    snapshot?: boolean | undefined;
+}, {
+    origin: string;
+    action: "fill_form";
+    fields: {
+        value: string;
+        ref: string;
+    }[];
+    snapshot?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"select">;
+    ref: z.ZodString;
+    values: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    values: string[];
+    origin: string;
+    action: "select";
+    ref: string;
+    snapshot?: boolean | undefined;
+}, {
+    values: string[];
+    origin: string;
+    action: "select";
+    ref: string;
+    snapshot?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"press">;
+    key: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    origin: string;
+    action: "press";
+    snapshot?: boolean | undefined;
+    ref?: string | undefined;
+}, {
+    key: string;
+    origin: string;
+    action: "press";
+    snapshot?: boolean | undefined;
+    ref?: string | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"hover">;
+    ref: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    origin: string;
+    action: "hover";
+    ref: string;
+    snapshot?: boolean | undefined;
+}, {
+    origin: string;
+    action: "hover";
+    ref: string;
+    snapshot?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"upload">;
+    ref: z.ZodString;
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    origin: string;
+    action: "upload";
+    ref: string;
+    snapshot?: boolean | undefined;
+}, {
+    path: string;
+    origin: string;
+    action: "upload";
+    ref: string;
+    snapshot?: boolean | undefined;
+}>, z.ZodObject<{
+    origin: z.ZodEffects<z.ZodString, string, string>;
+    snapshot: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodLiteral<"dialog">;
+    accept: z.ZodBoolean;
+    promptText: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    origin: string;
+    action: "dialog";
+    accept: boolean;
+    snapshot?: boolean | undefined;
+    promptText?: string | undefined;
+}, {
+    origin: string;
+    action: "dialog";
+    accept: boolean;
+    snapshot?: boolean | undefined;
+    promptText?: string | undefined;
+}>]>;
+/** The `browser` tool's input after canonicalisation. */
+export type BrowserToolInput = z.infer<typeof observeSchema>;
+/** The `browser_act` tool's input after canonicalisation. */
+export type BrowserActToolInput = z.infer<typeof actSchema>;
+/**
+ * Whether a `browser` call only observes. Navigation, history moves, reload
+ * and opening a tab change what the browser has loaded, and are what a site
+ * rule on `url` decides; looking, scrolling, waiting and moving between or
+ * closing tabs the browser already holds do not.
+ */
+export declare function isBrowserCallReadOnly(input: BrowserToolInput): boolean;
+/**
+ * `Page: <origin> — "<title>" (tab t1)`.
+ *
+ * The origin is the host's and canonical; the model copies it into
+ * `browser_act`. The title is the page's, so it is quoted, cut to one line
+ * and stripped of the envelope's delimiter.
+ */
+export declare function formatBrowserPageHeader(page: BrowserPageInfo): string;
+/**
+ * The structural error a browser host threw, or undefined. Recognised by
+ * shape, so a separately installed host and SDK need not share a class.
+ */
+export declare function browserHostErrorOf(value: unknown): BrowserHostError | undefined;
+/**
+ * The browser tools over a {@link BrowserHost}: `browser` (observe and
+ * navigate) and `browser_act` (change the page).
+ *
+ * The split is what makes the gate useful. `browser` calls that only look
+ * are read-only; `navigate` and `tabs new` carry a canonical `url` a site
+ * rule can match; every `browser_act` call carries the canonical `origin`
+ * it means to act on, which a site rule can match and which the host checks
+ * against the live page before acting.
+ *
+ * @example
+ * ```ts sketch
+ * import { createBrowserTools } from '@namzu/sdk'
+ *
+ * for (const tool of createBrowserTools(host)) registry.register(tool)
+ * ```
+ */
+export declare function createBrowserTools(host: BrowserHost): [ToolDefinition<BrowserToolInput>, ToolDefinition<BrowserActToolInput>];
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/tools/builtins/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAKX,WAAW,EACX,gBAAgB,EAIhB,eAAe,EAGf,MAAM,8BAA8B,CAAA;AAOrC,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,2BAA2B,CAAA;AAO3E,eAAO,MAAM,iBAAiB,EAAG,SAAkB,CAAA;AACnD,eAAO,MAAM,qBAAqB,EAAG,aAAsB,CAAA;AAmC3D,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqDhB,CAAA;AAOH,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+Cb,CAAA;AAEF,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAC5D,6DAA6D;AAC7D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAyB3D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAetE;AAqJD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAIrE;AA6FD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAwB/E;AAqND;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,WAAW,GACf,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC,CAiFzE"}