@intentic/browser 1.176.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur Kurowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @intentic/browser
+
+Drive a Chromium-family browser from Node over CDP: open pages, read them as **structured text**, and click and
+type by element reference. No dependencies.
+
+```ts
+import { browser } from "@intentic/browser";
+
+const web = browser();
+const page = await web.open("https://example.com/login");
+// page.elements → [{ ref: "e0", role: "textbox", name: "Email" }, …]
+
+await web.fill("e0", "someone@example.com");
+await web.fill("e1", "…", true);          // true = submit
+const after = await web.snapshot();
+```
+
+## Why references instead of coordinates
+
+A browser can be operated by clicking pixels, and it is miserable: the coordinates move when the window moves, a
+scroll invalidates every one of them, and "the Submit button" is a guess about which grey rectangle is which.
+
+A browser will simply tell you what it is showing. So this asks it — one snapshot returns every visible element
+with its role (`link`, `button`, `textbox`), its accessible name, and what it currently holds — and every action
+names an element rather than a position. The same instruction then works at any window size, on any machine,
+after any re-render.
+
+**Refs are deliberately short-lived.** They index an array parked on the page, and the next snapshot replaces it,
+so a ref taken before a click that navigated cannot silently address whatever now occupies that slot. A stale ref
+fails loudly, which is the behaviour worth having.
+
+## Which browser it drives
+
+**Not the user's own.** A browser only speaks CDP if it was started with `--remote-debugging-port`, and nobody's
+everyday browser was; restarting theirs to add the flag would close every tab they had open. So: if a debugging
+endpoint is already there, it is used; otherwise a separate instance starts with its own profile directory under
+`~/.intentic/host/browser`.
+
+That separate profile is a feature rather than a compromise. It is empty the first time, so the user signs into
+whatever is needed once, in a window they can watch, and it persists afterwards. Their own session is never
+automated and never at risk from a misfired click.
+
+## Why hand-rolled CDP rather than Puppeteer or Playwright
+
+This ships inside a `bun build --compile` binary, and that constraint has already been tested rather than
+assumed: the last native-dependency-shaped library that looked reasonable (nut.js, for input injection) turned
+out to be unloadable from a compiled binary at all — its addon is found through `bindings`, which walks up from
+`__dirname` looking for a `package.json`, and inside a standalone binary there isn't one.
+
+CDP needs no dependency. The protocol is JSON, `fetch` and `WebSocket` are globals, and the ~200 lines here are
+the subset that driving a page actually uses. Nothing in it can fail to load on somebody's laptop.
+
+## What is testable without a browser
+
+`snapshot.ts`'s renderer and ref parsing, and the per-platform browser search — all pure. The CDP calls end in a
+real Chrome painting a real page; those need a machine, not a test.

package/dist/cdp.d.ts

@@ -0,0 +1,17 @@
+export interface CdpTarget {
+    readonly id: string;
+    readonly title: string;
+    readonly url: string;
+    readonly type: string;
+    readonly webSocketDebuggerUrl?: string;
+}
+export interface CdpSession {
+    readonly send: <T = Record<string, unknown>>(method: string, params?: Record<string, unknown>) => Promise<T>;
+    readonly close: () => void;
+}
+export declare const probe: (port: number) => Promise<boolean>;
+export declare const waitForPort: (port: number, timeoutMs: number) => Promise<void>;
+export declare const listTargets: (port: number) => Promise<CdpTarget[]>;
+export declare const newTab: (port: number, url: string) => Promise<CdpTarget>;
+export declare const attach: (wsUrl: string) => Promise<CdpSession>;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../src/cdp.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7G,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC9B;AAMD,eAAO,MAAM,KAAK,SAAgB,MAAM,KAAG,OAAO,CAAC,OAAO,CAOzD,CAAC;AAEF,eAAO,MAAM,WAAW,SAAgB,MAAM,aAAa,MAAM,KAAG,OAAO,CAAC,IAAI,CAS/E,CAAC;AAEF,eAAO,MAAM,WAAW,SAAgB,MAAM,KAAG,OAAO,CAAC,SAAS,EAAE,CAQnE,CAAC;AAEF,eAAO,MAAM,MAAM,SAAgB,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,SAAS,CAMzE,CAAC;AAEF,eAAO,MAAM,MAAM,UAAiB,MAAM,KAAG,OAAO,CAAC,UAAU,CAkD9D,CAAC"}

package/dist/cdp.js

@@ -0,0 +1,82 @@
+import { BrowserError } from "./types.js";
+const CALL_TIMEOUT_MS = 30_000;
+const endpoint = (port, path) => `http://127.0.0.1:${port}${path}`;
+export const probe = async (port) => {
+    try {
+        const response = await fetch(endpoint(port, "/json/version"), { signal: AbortSignal.timeout(1000) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+export const waitForPort = async (port, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await probe(port)) {
+            return;
+        }
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 150));
+    }
+    throw new BrowserError(`The browser did not open its debugging port (${port}) in time.`);
+};
+export const listTargets = async (port) => {
+    const response = await fetch(endpoint(port, "/json/list"), { signal: AbortSignal.timeout(5000) }).catch(() => undefined);
+    if (response === undefined || !response.ok) {
+        throw new BrowserError(`No browser is answering on the debugging port (${port}).`);
+    }
+    return (await response.json()).filter((target) => target.type === "page" && !target.url.startsWith("devtools://"));
+};
+export const newTab = async (port, url) => {
+    const response = await fetch(endpoint(port, `/json/new?${encodeURIComponent(url)}`), { method: "PUT" }).catch(() => undefined);
+    if (response === undefined || !response.ok) {
+        throw new BrowserError("The browser refused to open a new tab.");
+    }
+    return (await response.json());
+};
+export const attach = async (wsUrl) => {
+    const socket = new WebSocket(wsUrl);
+    const pending = new Map();
+    let nextId = 1;
+    await new Promise((resolvePromise, reject) => {
+        socket.addEventListener("open", () => resolvePromise(), { once: true });
+        socket.addEventListener("error", () => reject(new BrowserError("Could not connect to the browser's debugging socket.")), { once: true });
+    });
+    socket.addEventListener("message", (event) => {
+        const message = JSON.parse(String(event.data));
+        if (message.id === undefined) {
+            return;
+        }
+        const waiter = pending.get(message.id);
+        if (waiter === undefined) {
+            return;
+        }
+        pending.delete(message.id);
+        clearTimeout(waiter.timer);
+        if (message.error !== undefined) {
+            waiter.reject(new BrowserError(message.error.message ?? "The browser refused that."));
+            return;
+        }
+        waiter.resolve(message.result);
+    });
+    socket.addEventListener("close", () => {
+        for (const [, waiter] of pending) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new BrowserError("The browser closed the connection — the tab was probably closed."));
+        }
+        pending.clear();
+    });
+    return {
+        send: (method, params = {}) => new Promise((resolvePromise, reject) => {
+            const id = nextId++;
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new BrowserError(`The page did not answer "${method}" within ${CALL_TIMEOUT_MS / 1000}s.`));
+            }, CALL_TIMEOUT_MS);
+            pending.set(id, { resolve: resolvePromise, reject, timer });
+            socket.send(JSON.stringify({ id, method, params }));
+        }),
+        close: () => socket.close(),
+    };
+};
+//# sourceMappingURL=cdp.js.map

package/dist/cdp.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type Browser } from "./types.js";
+export { DEFAULT_PORT, browserCandidates, ensureBrowser, profileDir } from "./launch.js";
+export { renderPage, refIndex, toPageState, SNAPSHOT_SCRIPT, type RawSnapshot } from "./snapshot.js";
+export { BrowserError, type Browser, type PageElement, type PageState } from "./types.js";
+export declare const browser: (port?: number) => Browser;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAgC,MAAM,YAAY,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAqC1F,eAAO,MAAM,OAAO,UAAU,MAAM,KAAkB,OA6GrD,CAAC"}

package/dist/index.js

@@ -0,0 +1,112 @@
+import { attach, listTargets, newTab } from "./cdp.js";
+import { DEFAULT_PORT, ensureBrowser } from "./launch.js";
+import { refIndex, SNAPSHOT_SCRIPT, toPageState } from "./snapshot.js";
+import { BrowserError } from "./types.js";
+export { DEFAULT_PORT, browserCandidates, ensureBrowser, profileDir } from "./launch.js";
+export { renderPage, refIndex, toPageState, SNAPSHOT_SCRIPT } from "./snapshot.js";
+export { BrowserError } from "./types.js";
+const evaluate = async (session, expression) => {
+    const result = await session.send("Runtime.evaluate", {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+    });
+    if (result.exceptionDetails !== undefined) {
+        throw new BrowserError(`The page rejected that: ${result.exceptionDetails.text ?? "script error"}`);
+    }
+    return result.result?.value;
+};
+const withElement = (ref, body) => {
+    const index = refIndex(ref);
+    return `(function () {
+  var refs = window.__intenticRefs || [];
+  var el = refs[${index}];
+  if (!el) throw new Error('${ref} is not on this page any more — take a new snapshot; the page has changed since the last one.');
+  ${body}
+})()`;
+};
+export const browser = (port = DEFAULT_PORT) => {
+    let session;
+    let targetId;
+    const connect = async (preferred) => {
+        if (session !== undefined && (preferred === undefined || preferred === targetId)) {
+            return session;
+        }
+        const targets = await listTargets(port);
+        const target = preferred === undefined ? targets[0] : targets.find((candidate) => candidate.id === preferred);
+        if (target?.webSocketDebuggerUrl === undefined) {
+            throw new BrowserError(preferred === undefined ? "The browser has no open page." : `There is no tab "${preferred}" any more.`);
+        }
+        session?.close();
+        session = await attach(target.webSocketDebuggerUrl);
+        targetId = target.id;
+        return session;
+    };
+    const snapshot = async () => {
+        const raw = await evaluate(await connect(targetId), SNAPSHOT_SCRIPT);
+        return toPageState(raw ?? {});
+    };
+    return {
+        open: async (url) => {
+            await ensureBrowser(port, url);
+            if (url !== undefined) {
+                const target = await newTab(port, url);
+                targetId = target.id;
+                session?.close();
+                session = undefined;
+                await new Promise((resolvePromise) => setTimeout(resolvePromise, 600));
+            }
+            return await snapshot();
+        },
+        snapshot,
+        click: async (ref) => {
+            await evaluate(await connect(targetId), withElement(ref, "el.scrollIntoView({block: 'center'}); el.click();"));
+        },
+        fill: async (ref, text, submit) => {
+            const literal = JSON.stringify(text);
+            await evaluate(await connect(targetId), withElement(ref, `el.focus();
+  if (el.isContentEditable) { el.textContent = ${literal}; }
+  else { el.value = ${literal}; }
+  // The events a page's own JavaScript listens for. Setting .value alone updates the DOM and leaves every
+  // framework's state untouched, which is how a filled form submits empty.
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+  el.dispatchEvent(new Event('change', { bubbles: true }));
+  ${submit === true ? "if (el.form) { el.form.requestSubmit ? el.form.requestSubmit() : el.form.submit(); }" : ""}`));
+        },
+        press: async (combo) => {
+            const live = await connect(targetId);
+            const key = combo.split("+").pop() ?? combo;
+            const named = {
+                Return: { key: "Enter", code: "Enter", keyCode: 13 },
+                Enter: { key: "Enter", code: "Enter", keyCode: 13 },
+                Escape: { key: "Escape", code: "Escape", keyCode: 27 },
+                Tab: { key: "Tab", code: "Tab", keyCode: 9 },
+            };
+            const descriptor = named[key] ?? { key, code: `Key${key.toUpperCase()}`, keyCode: key.toUpperCase().charCodeAt(0) };
+            const modifiers = (combo.includes("ctrl") ? 2 : 0) | (combo.includes("shift") ? 8 : 0) | (combo.includes("alt") ? 1 : 0);
+            for (const type of ["keyDown", "keyUp"]) {
+                await live.send("Input.dispatchKeyEvent", { type, ...descriptor, windowsVirtualKeyCode: descriptor.keyCode, modifiers });
+            }
+        },
+        text: async () => {
+            const body = await evaluate(await connect(targetId), "document.body ? document.body.innerText : ''");
+            return (body ?? "").replace(/\n{3,}/g, "\n\n").slice(0, 20_000);
+        },
+        screenshot: async () => {
+            const shot = await (await connect(targetId)).send("Page.captureScreenshot", { format: "png" });
+            return Buffer.from(shot.data, "base64");
+        },
+        tabs: async () => (await listTargets(port)).map((target) => ({ id: target.id, title: target.title, url: target.url, active: target.id === targetId })),
+        selectTab: async (id) => {
+            await connect(id);
+            await session?.send("Page.bringToFront").catch(() => undefined);
+            return await snapshot();
+        },
+        disconnect: async () => {
+            session?.close();
+            session = undefined;
+            targetId = undefined;
+        },
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/launch.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_PORT = 9222;
+export declare const profileDir: () => string;
+export declare const browserCandidates: (platform: NodeJS.Platform) => string[];
+export declare const ensureBrowser: (port?: number, url?: string) => Promise<{
+    started: boolean;
+}>;
+//# sourceMappingURL=launch.d.ts.map

package/dist/launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,eAAO,MAAM,UAAU,QAAO,MAAyD,CAAC;AAKxF,eAAO,MAAM,iBAAiB,aAAc,MAAM,CAAC,QAAQ,KAAG,MAAM,EAqBnE,CAAC;AAsBF,eAAO,MAAM,aAAa,UAAgB,MAAM,QAAuB,MAAM,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAiB3G,CAAC"}

package/dist/launch.js

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { probe, waitForPort } from "./cdp.js";
+import { BrowserError } from "./types.js";
+export const DEFAULT_PORT = 9222;
+export const profileDir = () => join(homedir(), ".intentic", "host", "browser");
+export const browserCandidates = (platform) => {
+    if (platform === "win32") {
+        const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
+        const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+        const local = process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+        return [
+            join(programFiles, "Google\\Chrome\\Application\\chrome.exe"),
+            join(programFilesX86, "Google\\Chrome\\Application\\chrome.exe"),
+            join(local, "Google\\Chrome\\Application\\chrome.exe"),
+            join(programFiles, "Microsoft\\Edge\\Application\\msedge.exe"),
+            join(programFilesX86, "Microsoft\\Edge\\Application\\msedge.exe"),
+        ];
+    }
+    return [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/usr/bin/microsoft-edge",
+        "/snap/bin/chromium",
+    ];
+};
+const findBrowser = () => browserCandidates(process.platform).find((path) => existsSync(path));
+const flags = (port, url) => [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${profileDir()}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-session-crashed-bubble",
+    "--restore-last-session=false",
+    ...(url === undefined ? [] : [url]),
+];
+const START_TIMEOUT_MS = 20_000;
+export const ensureBrowser = async (port = DEFAULT_PORT, url) => {
+    if (await probe(port)) {
+        return { started: false };
+    }
+    const binary = findBrowser();
+    if (binary === undefined) {
+        throw new BrowserError("This computer has no Chrome, Chromium or Edge, and browser control needs one of them.", "Install Google Chrome (or Chromium) and try again.");
+    }
+    const child = spawn(binary, flags(port, url), { detached: true, stdio: "ignore" });
+    child.unref();
+    await waitForPort(port, START_TIMEOUT_MS);
+    return { started: true };
+};
+//# sourceMappingURL=launch.js.map

package/dist/launch.js.map

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

package/dist/snapshot.d.ts

@@ -0,0 +1,12 @@
+import type { PageElement, PageState } from "./types.js";
+export declare const SNAPSHOT_SCRIPT = "(function () {\n  var MAX = 150;\n  var refs = [];\n  window.__intenticRefs = refs;\n\n  function visible(el) {\n    var rect = el.getBoundingClientRect();\n    if (rect.width <= 0 || rect.height <= 0) return false;\n    var style = window.getComputedStyle(el);\n    return style.visibility !== 'hidden' && style.display !== 'none' && style.opacity !== '0';\n  }\n\n  function roleOf(el) {\n    var explicit = el.getAttribute('role');\n    if (explicit) return explicit;\n    var tag = el.tagName.toLowerCase();\n    if (tag === 'a') return 'link';\n    if (tag === 'button') return 'button';\n    if (tag === 'select') return 'combobox';\n    if (tag === 'textarea') return 'textbox';\n    if (/^h[1-6]$/.test(tag)) return 'heading';\n    if (tag === 'input') {\n      var type = (el.getAttribute('type') || 'text').toLowerCase();\n      if (type === 'submit' || type === 'button' || type === 'reset') return 'button';\n      if (type === 'checkbox') return 'checkbox';\n      if (type === 'radio') return 'radio';\n      if (type === 'file') return 'file';\n      return 'textbox';\n    }\n    if (el.isContentEditable) return 'textbox';\n    return 'element';\n  }\n\n  function nameOf(el) {\n    var candidates = [\n      el.getAttribute('aria-label'),\n      el.getAttribute('alt'),\n      el.getAttribute('placeholder'),\n      el.getAttribute('title'),\n      el.getAttribute('name'),\n      (el.innerText || '').trim(),\n      el.value\n    ];\n    for (var i = 0; i < candidates.length; i++) {\n      var candidate = candidates[i];\n      if (typeof candidate === 'string' && candidate.trim() !== '') {\n        return candidate.trim().replace(/\\s+/g, ' ').slice(0, 120);\n      }\n    }\n    return '';\n  }\n\n  var selector = 'a[href], button, input, textarea, select, summary, [role], [onclick], [contenteditable=\"\"], [contenteditable=\"true\"], h1, h2, h3';\n  var found = document.querySelectorAll(selector);\n  var elements = [];\n  for (var i = 0; i < found.length && elements.length < MAX; i++) {\n    var el = found[i];\n    if (!visible(el)) continue;\n    var role = roleOf(el);\n    var name = nameOf(el);\n    // A nameless non-input is something a caller could never ask for by name, so it is noise.\n    if (name === '' && role !== 'textbox' && role !== 'checkbox' && role !== 'file') continue;\n    var ref = 'e' + refs.length;\n    refs.push(el);\n    var entry = { ref: ref, role: role, name: name };\n    if (typeof el.value === 'string' && el.value !== '' && role !== 'button') entry.value = el.value.slice(0, 120);\n    if (role === 'checkbox' || role === 'radio') entry.value = el.checked ? 'checked' : 'unchecked';\n    elements.push(entry);\n  }\n  return {\n    url: location.href,\n    title: document.title,\n    truncated: found.length > 0 && elements.length >= MAX,\n    elements: elements\n  };\n})()";
+export declare const renderPage: (page: PageState, truncated?: boolean) => string;
+export interface RawSnapshot {
+    readonly url?: string;
+    readonly title?: string;
+    readonly truncated?: boolean;
+    readonly elements?: readonly PageElement[];
+}
+export declare const toPageState: (raw: RawSnapshot) => PageState;
+export declare const refIndex: (ref: string) => number;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqBzD,eAAO,MAAM,eAAe,gyFA2EvB,CAAC;AAMN,eAAO,MAAM,UAAU,SAAU,SAAS,0BAAsB,MAY/D,CAAC;AAGF,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC9C;AAED,eAAO,MAAM,WAAW,QAAS,WAAW,KAAG,SAI7C,CAAC;AAIH,eAAO,MAAM,QAAQ,QAAS,MAAM,KAAG,MAGtC,CAAC"}

package/dist/snapshot.js

@@ -0,0 +1,100 @@
+const MAX_ELEMENTS = 150;
+export const SNAPSHOT_SCRIPT = `(function () {
+  var MAX = ${MAX_ELEMENTS};
+  var refs = [];
+  window.__intenticRefs = refs;
+
+  function visible(el) {
+    var rect = el.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return false;
+    var style = window.getComputedStyle(el);
+    return style.visibility !== 'hidden' && style.display !== 'none' && style.opacity !== '0';
+  }
+
+  function roleOf(el) {
+    var explicit = el.getAttribute('role');
+    if (explicit) return explicit;
+    var tag = el.tagName.toLowerCase();
+    if (tag === 'a') return 'link';
+    if (tag === 'button') return 'button';
+    if (tag === 'select') return 'combobox';
+    if (tag === 'textarea') return 'textbox';
+    if (/^h[1-6]$/.test(tag)) return 'heading';
+    if (tag === 'input') {
+      var type = (el.getAttribute('type') || 'text').toLowerCase();
+      if (type === 'submit' || type === 'button' || type === 'reset') return 'button';
+      if (type === 'checkbox') return 'checkbox';
+      if (type === 'radio') return 'radio';
+      if (type === 'file') return 'file';
+      return 'textbox';
+    }
+    if (el.isContentEditable) return 'textbox';
+    return 'element';
+  }
+
+  function nameOf(el) {
+    var candidates = [
+      el.getAttribute('aria-label'),
+      el.getAttribute('alt'),
+      el.getAttribute('placeholder'),
+      el.getAttribute('title'),
+      el.getAttribute('name'),
+      (el.innerText || '').trim(),
+      el.value
+    ];
+    for (var i = 0; i < candidates.length; i++) {
+      var candidate = candidates[i];
+      if (typeof candidate === 'string' && candidate.trim() !== '') {
+        return candidate.trim().replace(/\\s+/g, ' ').slice(0, 120);
+      }
+    }
+    return '';
+  }
+
+  var selector = 'a[href], button, input, textarea, select, summary, [role], [onclick], [contenteditable=""], [contenteditable="true"], h1, h2, h3';
+  var found = document.querySelectorAll(selector);
+  var elements = [];
+  for (var i = 0; i < found.length && elements.length < MAX; i++) {
+    var el = found[i];
+    if (!visible(el)) continue;
+    var role = roleOf(el);
+    var name = nameOf(el);
+    // A nameless non-input is something a caller could never ask for by name, so it is noise.
+    if (name === '' && role !== 'textbox' && role !== 'checkbox' && role !== 'file') continue;
+    var ref = 'e' + refs.length;
+    refs.push(el);
+    var entry = { ref: ref, role: role, name: name };
+    if (typeof el.value === 'string' && el.value !== '' && role !== 'button') entry.value = el.value.slice(0, 120);
+    if (role === 'checkbox' || role === 'radio') entry.value = el.checked ? 'checked' : 'unchecked';
+    elements.push(entry);
+  }
+  return {
+    url: location.href,
+    title: document.title,
+    truncated: found.length > 0 && elements.length >= MAX,
+    elements: elements
+  };
+})()`;
+export const renderPage = (page, truncated = false) => {
+    const header = [`Page: ${page.title === "" ? "(untitled)" : page.title}`, page.url];
+    if (page.elements.length === 0) {
+        return [...header, "", "Nothing on this page can be clicked or typed into — try reading its text instead."].join("\n");
+    }
+    const rows = page.elements.map((element) => {
+        const said = element.name === "" ? "" : ` "${element.name}"`;
+        const holds = element.value === undefined || element.value === "" ? "" : ` = "${element.value}"`;
+        return `[${element.ref}] ${element.role}${said}${holds}`;
+    });
+    const note = truncated ? [`(only the first ${MAX_ELEMENTS} are listed — scroll or narrow the page to see more)`] : [];
+    return [...header, "", ...rows, ...note].join("\n");
+};
+export const toPageState = (raw) => ({
+    url: raw.url ?? "",
+    title: raw.title ?? "",
+    elements: raw.elements ?? [],
+});
+export const refIndex = (ref) => {
+    const match = /^e(\d+)$/.exec(ref.trim());
+    return match?.[1] === undefined ? -1 : Number(match[1]);
+};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAmBA,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,MAAM,CAAC,MAAM,eAAe,GAAG;cACjB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0ErB,CAAC;AAMN,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAe,EAAE,SAAS,GAAG,KAAK,EAAU,EAAE;IACrE,MAAM,MAAM,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACpF,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,MAAM,EAAE,EAAE,EAAE,mFAAmF,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3H,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,KAAK,GAAG,CAAC;QACjG,OAAO,IAAI,OAAO,CAAC,GAAG,KAAK,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC;IAC7D,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,mBAAmB,YAAY,sDAAsD,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtH,OAAO,CAAC,GAAG,MAAM,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC,CAAC;AAUF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAgB,EAAa,EAAE,CAAC,CAAC;IACzD,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE;IAClB,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE;IACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,EAAE;CAC/B,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+export interface PageElement {
+    readonly ref: string;
+    readonly role: string;
+    readonly name: string;
+    readonly value?: string | undefined;
+}
+export interface PageState {
+    readonly url: string;
+    readonly title: string;
+    readonly elements: readonly PageElement[];
+}
+export interface Browser {
+    readonly open: (url?: string) => Promise<PageState>;
+    readonly snapshot: () => Promise<PageState>;
+    readonly click: (ref: string) => Promise<void>;
+    readonly fill: (ref: string, text: string, submit?: boolean) => Promise<void>;
+    readonly press: (combo: string) => Promise<void>;
+    readonly text: () => Promise<string>;
+    readonly screenshot: () => Promise<Buffer>;
+    readonly tabs: () => Promise<{
+        readonly id: string;
+        readonly title: string;
+        readonly url: string;
+        readonly active: boolean;
+    }[]>;
+    readonly selectTab: (id: string) => Promise<PageState>;
+    readonly disconnect: () => Promise<void>;
+}
+export declare class BrowserError extends Error {
+    readonly hint: string | undefined;
+    constructor(message: string, hint?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,OAAO;IAGpB,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IAChI,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAGvD,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAKD,qBAAa,YAAa,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAIzC;CACJ"}

package/dist/types.js

@@ -0,0 +1,9 @@
+export class BrowserError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "BrowserError";
+        this.hint = hint;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAoDA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC1B,IAAI,CAAqB;IAClC,YAAY,OAAe,EAAE,IAAa;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@intentic/browser",
+  "version": "1.176.0",
+  "description": "Drive a Chromium browser from Node over CDP — open pages, read them as structured text, click and type by element reference. No dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/radarsu/intentic.git",
+    "directory": "_libs/browser"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "tslib": "2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.2",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "vitest": "4.1.10",
+    "@intentic/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "typecheck": "tsgo --noEmit -p tsconfig.test.json",
+    "watch": "tsgo --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}