floorp-mcp 1.5.0

package/dist/floorp-client.js

@@ -0,0 +1,273 @@
+/**
+ * Thin HTTP client for Floorp's built-in automation API.
+ *
+ * Floorp exposes this API on http://127.0.0.1:58261 once `floorp.mcp.enabled`
+ * is set to `true` in about:config. The model is instance-based: to operate on
+ * a tab you first obtain an `instanceId` (by attaching to an existing tab or by
+ * creating a new one), then issue per-instance commands.
+ *
+ * Lifecycle (verified against a live Floorp):
+ *   - attach(browserId)            -> ephemeral handle to an EXISTING tab
+ *   - createTab(url)               -> opens a NEW tab, returns a handle
+ *   - detach(instanceId)  [DELETE] -> releases the handle, tab stays open
+ *   - closeTab(instanceId) [close] -> actually closes the tab
+ */
+const DATA_URL_PREFIX = /^data:image\/[a-z]+;base64,/;
+export class FloorpClient {
+    baseUrl;
+    token;
+    constructor(port = Number(process.env.FLOORP_MCP_PORT) || 58261, token = process.env.FLOORP_MCP_TOKEN ?? "") {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`Invalid Floorp API port "${port}" — must be an integer 1–65535 (check FLOORP_MCP_PORT).`);
+        }
+        this.baseUrl = `http://127.0.0.1:${port}`;
+        this.token = token;
+    }
+    // -- low level --------------------------------------------------------------
+    async request(method, path, body) {
+        const headers = {};
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new Error(`Cannot reach Floorp at ${this.baseUrl}. Is Floorp running with ` +
+                `'floorp.mcp.enabled' set to true in about:config? (${err.message})`);
+        }
+        if (!res.ok) {
+            const raw = await res.text().catch(() => "");
+            // Truncate so a large/unexpected error body can't dump page data into the model.
+            const text = raw.length > 500 ? raw.slice(0, 500) + "…[truncated]" : raw;
+            throw new Error(`Floorp API ${res.status} on ${path}: ${text}`);
+        }
+        return (await res.json());
+    }
+    static stripImagePrefix(data) {
+        return data.replace(DATA_URL_PREFIX, "");
+    }
+    // -- browser-level ----------------------------------------------------------
+    async health() {
+        try {
+            const r = await this.request("GET", "/health");
+            return r.status === "ok";
+        }
+        catch {
+            return false;
+        }
+    }
+    async listTabs() {
+        return this.request("GET", "/tabs/list");
+    }
+    /** The currently selected tab. Throws if none is reported. */
+    async activeTab() {
+        const tabs = await this.listTabs();
+        const active = tabs.find((t) => t.selected);
+        if (!active)
+            throw new Error("No active tab reported by Floorp.");
+        return active;
+    }
+    // -- instance lifecycle -----------------------------------------------------
+    /** Open a NEW tab and return its instance handle. */
+    async createTab(url, opts = {}) {
+        const r = await this.request("POST", "/tabs/instances", {
+            url,
+            inBackground: opts.background ?? false,
+            waitForLoad: opts.waitForLoad ?? true,
+        });
+        return r.instanceId;
+    }
+    /** Resolve the live browserId behind an instance handle. */
+    async getInstanceBrowserId(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}`);
+        return r.browserId ?? null;
+    }
+    /** Attach an ephemeral handle to an EXISTING tab. */
+    async attach(browserId) {
+        const r = await this.request("POST", "/tabs/attach", { browserId: String(browserId) });
+        return r.instanceId;
+    }
+    /** Release a handle WITHOUT closing the tab. */
+    async detach(instanceId) {
+        await this.request("DELETE", `/tabs/instances/${encodeURIComponent(instanceId)}`);
+    }
+    /** Actually close the tab behind a handle. */
+    async closeTab(instanceId) {
+        await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/close`);
+    }
+    // -- per-instance reads / actions ------------------------------------------
+    async navigate(instanceId, url) {
+        await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/navigate`, { url });
+    }
+    async getUri(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/uri`);
+        return r.uri;
+    }
+    async getTitle(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/title`);
+        return r.title ?? null;
+    }
+    /** Page content as clean Markdown. */
+    async getText(instanceId, mode = "full") {
+        const r = await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/text`, { mode, enableFingerprints: false, includeSelectorMap: false });
+        return r.text ?? "";
+    }
+    async getHtml(instanceId, selector) {
+        const qs = selector ? `?selector=${encodeURIComponent(selector)}` : "";
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/html${qs}`);
+        return r.html ?? "";
+    }
+    async getAccessibilityTree(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/ax-tree?interestingOnly=true`);
+        return r.tree ?? null;
+    }
+    /** Viewport screenshot as base64 PNG (no data-URL prefix). */
+    async screenshot(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/screenshot`);
+        return r.image ? FloorpClient.stripImagePrefix(r.image) : null;
+    }
+    /** Full-page screenshot as base64 PNG (no data-URL prefix). */
+    async fullPageScreenshot(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/fullPageScreenshot`);
+        return r.image ? FloorpClient.stripImagePrefix(r.image) : null;
+    }
+    // -- interactions -----------------------------------------------------------
+    /** POST a per-instance action; treat an explicit `{ ok: false }` as failure. */
+    async action(instanceId, suffix, body, what) {
+        const r = await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}${suffix}`, body);
+        if (r.ok === false) {
+            throw new Error(`${what} failed — element not found or not actionable.`);
+        }
+    }
+    /** Scroll an element (by selector or fingerprint) into view. */
+    async scrollTo(instanceId, selector, fingerprint) {
+        await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/scrollTo`, { selector, fingerprint });
+    }
+    async click(instanceId, selector, opts = {}) {
+        // Auto scroll-into-view first so off-screen elements are actionable.
+        await this.scrollTo(instanceId, selector, opts.fingerprint).catch(() => { });
+        await this.action(instanceId, "/click", {
+            selector,
+            fingerprint: opts.fingerprint,
+            button: opts.button,
+            clickCount: opts.clickCount,
+            force: opts.force,
+        }, `Click "${selector ?? opts.fingerprint ?? "?"}"`);
+    }
+    /**
+     * Structured page snapshot: clean Markdown text with inline fingerprint refs
+     * (`<!--fp:...-->`) plus an "Element Selector Map" (fp | tag | text). Lets an
+     * agent locate elements without grepping raw HTML, then act via a `ref`.
+     */
+    async snapshot(instanceId, mode = "full") {
+        const r = await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/text`, { mode, enableFingerprints: true, includeSelectorMap: true });
+        return r.text ?? "";
+    }
+    /** Set the value of an input/textarea. */
+    async input(instanceId, selector, value, opts = {}) {
+        await this.action(instanceId, "/input", { selector, value, typingMode: opts.typingMode, typingDelayMs: opts.typingDelayMs }, `Type into "${selector}"`);
+    }
+    async clearInput(instanceId, selector) {
+        await this.action(instanceId, "/clearInput", { selector }, `Clear "${selector}"`);
+    }
+    /** Fill several fields at once: keys are CSS selectors, values are strings. */
+    async fillForm(instanceId, formData) {
+        await this.action(instanceId, "/fillForm", { formData }, "Fill form");
+    }
+    async pressKey(instanceId, key) {
+        await this.action(instanceId, "/pressKey", { key }, `Press "${key}"`);
+    }
+    /**
+     * Insert text into a rich / contenteditable editor (Slate, ProseMirror, Lexical…)
+     * by dispatching a real text-input event. Use this when `input` fails because the
+     * element has no `.value` (i.e. it is not a plain <input>/<textarea>).
+     */
+    async dispatchTextInput(instanceId, selector, text) {
+        await this.action(instanceId, "/dispatchTextInput", { selector, text }, `Type into "${selector}"`);
+    }
+    /** Read the current value of an input/textarea/select. */
+    async getValue(instanceId, selector) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/value?selector=${encodeURIComponent(selector)}`);
+        return r.value ?? null;
+    }
+    async waitForElement(instanceId, selector, state = "visible", timeout = 5000) {
+        const r = await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/waitForElement`, { selector, state, timeout });
+        return r.found ?? r.ok ?? false;
+    }
+    /**
+     * Evaluate JavaScript in the page context (supports async/await).
+     * NOTE: not exposed in all Floorp builds — older ones return HTTP 404.
+     */
+    async evaluate(instanceId, script) {
+        return this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/evaluate`, { script });
+    }
+    // -- more interactions (v0.6.0) ---------------------------------------------
+    async hover(instanceId, selector, fingerprint) {
+        await this.scrollTo(instanceId, selector, fingerprint).catch(() => { });
+        await this.action(instanceId, "/hover", { selector, fingerprint }, `Hover "${selector ?? fingerprint}"`);
+    }
+    async doubleClick(instanceId, selector, fingerprint) {
+        await this.scrollTo(instanceId, selector, fingerprint).catch(() => { });
+        await this.action(instanceId, "/doubleClick", { selector, fingerprint }, `Double-click "${selector ?? fingerprint}"`);
+    }
+    async rightClick(instanceId, selector, fingerprint) {
+        await this.scrollTo(instanceId, selector, fingerprint).catch(() => { });
+        await this.action(instanceId, "/rightClick", { selector, fingerprint }, `Right-click "${selector ?? fingerprint}"`);
+    }
+    /** Choose an option in a <select> by value. */
+    async selectOption(instanceId, selector, value) {
+        await this.action(instanceId, "/selectOption", { selector, value }, `Select "${value}" in "${selector}"`);
+    }
+    /** Check/uncheck a checkbox or radio. */
+    async setChecked(instanceId, selector, checked) {
+        await this.action(instanceId, "/setChecked", { selector, checked }, `Set checked=${checked} on "${selector}"`);
+    }
+    /** Submit a form (by a selector inside/of the form). */
+    async submitForm(instanceId, selector) {
+        await this.action(instanceId, "/submit", { selector }, `Submit "${selector ?? "form"}"`);
+    }
+    /** Set a file input's file by absolute path. */
+    async uploadFile(instanceId, selector, filePath) {
+        await this.action(instanceId, "/uploadFile", { selector, filePath }, `Upload to "${selector}"`);
+    }
+    // -- more reads (v0.6.0) ----------------------------------------------------
+    async getAttribute(instanceId, name, selector, fingerprint) {
+        const p = new URLSearchParams({ name });
+        if (selector)
+            p.set("selector", selector);
+        if (fingerprint)
+            p.set("fingerprint", fingerprint);
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/attribute?${p.toString()}`);
+        return r.value ?? null;
+    }
+    /** Readability-extracted main article (title, byline, markdown). */
+    async getArticle(instanceId) {
+        return this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/article`);
+    }
+    async getCookies(instanceId) {
+        const r = await this.request("GET", `/tabs/instances/${encodeURIComponent(instanceId)}/cookies`);
+        return r.cookies ?? [];
+    }
+    /** Wait until network activity settles (good after navigation/SPA loads). */
+    async waitForNetworkIdle(instanceId, timeout = 8000) {
+        const r = await this.request("POST", `/tabs/instances/${encodeURIComponent(instanceId)}/waitForNetworkIdle`, { timeout });
+        return r.ok ?? false;
+    }
+    // -- workspaces (Floorp-specific, browser-level) (v0.6.0) -------------------
+    async listWorkspaces() {
+        const r = await this.request("GET", "/workspaces/");
+        return r.workspaces ?? [];
+    }
+    async switchWorkspace(id) {
+        const r = await this.request("POST", `/workspaces/${encodeURIComponent(id)}/switch`);
+        return r.ok ?? false;
+    }
+}
+//# sourceMappingURL=floorp-client.js.map

package/dist/floorp-client.js.map

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

package/dist/guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure security guards for URL navigation and file uploads. Kept in their own
+ * module (no side effects, no server) so they can be unit-tested without a live
+ * Floorp or starting the MCP server.
+ */
+/** Browser-internal pages (about:, chrome:, …) cannot be screenshotted. */
+export declare const PRIVILEGED_SCHEME: RegExp;
+/** True for loopback / link-local / RFC-1918 private hosts. Best-effort literal
+ *  check (does not resolve DNS — that rebinding case is documented in README). */
+export declare function isInternalHost(host: string): boolean;
+/** Gate URLs before open/navigate. By default: only http(s) (and about:blank),
+ *  and NOT loopback/private hosts — so a prompt-injected agent can't pivot the
+ *  browser onto Floorp's own automation API (127.0.0.1:58261) or your LAN, then
+ *  read the response back. Optional FLOORP_MCP_ALLOW_DOMAINS restricts to a
+ *  domain allowlist. FLOORP_MCP_ALLOW_PRIVILEGED_URLS=1 lifts scheme+host gates. */
+export declare function assertNavigableUrl(url: string): void;
+/** If FLOORP_MCP_ALLOW_UPLOAD_DIRS is set (';'-separated on Windows), uploads are
+ *  restricted to files inside those directories. Paths are canonicalised with
+ *  realpath (resolving symlinks) and checked with path.relative so neither a
+ *  symlink, a "..", nor a same-prefix sibling dir (C:\\a vs C:\\ab) can escape.
+ *  UNC paths are rejected when an allowlist is set. Unset = any path (default). */
+export declare function assertUploadAllowed(filePath: string): string;

package/dist/guards.js

@@ -0,0 +1,111 @@
+/**
+ * Pure security guards for URL navigation and file uploads. Kept in their own
+ * module (no side effects, no server) so they can be unit-tested without a live
+ * Floorp or starting the MCP server.
+ */
+import { resolve, relative, isAbsolute, delimiter } from "node:path";
+import { realpathSync } from "node:fs";
+/** Browser-internal pages (about:, chrome:, …) cannot be screenshotted. */
+export const PRIVILEGED_SCHEME = /^(about|chrome|resource|view-source|moz-extension):/i;
+/** True for loopback / link-local / RFC-1918 private hosts. Best-effort literal
+ *  check (does not resolve DNS — that rebinding case is documented in README). */
+export function isInternalHost(host) {
+    const h = host.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    if (h === "localhost" || h.endsWith(".localhost") || h === "" || h === "::" || h === "::1")
+        return true;
+    const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (m) {
+        const a = Number(m[1]), b = Number(m[2]);
+        if (a === 0 || a === 127 || a === 10)
+            return true; // this-host, loopback, private
+        if (a === 169 && b === 254)
+            return true; // link-local
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // private
+        if (a === 192 && b === 168)
+            return true; // private
+    }
+    // IPv6 loopback / unique-local (fc00::/7) / link-local (fe80::/10)
+    if (h.startsWith("fc") || h.startsWith("fd") || h.startsWith("fe8") || h.startsWith("fe9") ||
+        h.startsWith("fea") || h.startsWith("feb"))
+        return true;
+    return false;
+}
+/** Gate URLs before open/navigate. By default: only http(s) (and about:blank),
+ *  and NOT loopback/private hosts — so a prompt-injected agent can't pivot the
+ *  browser onto Floorp's own automation API (127.0.0.1:58261) or your LAN, then
+ *  read the response back. Optional FLOORP_MCP_ALLOW_DOMAINS restricts to a
+ *  domain allowlist. FLOORP_MCP_ALLOW_PRIVILEGED_URLS=1 lifts scheme+host gates. */
+export function assertNavigableUrl(url) {
+    const bypass = process.env.FLOORP_MCP_ALLOW_PRIVILEGED_URLS === "1";
+    if (url.trim().toLowerCase() === "about:blank")
+        return;
+    const scheme = url.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/)?.[1]?.toLowerCase();
+    if (scheme !== "http" && scheme !== "https") {
+        if (bypass)
+            return;
+        throw new Error(`Refusing to open "${url}" — only http(s) URLs are allowed by default ` +
+            `(blocks file:// and browser-internal pages). ` +
+            `Set FLOORP_MCP_ALLOW_PRIVILEGED_URLS=1 to allow other schemes.`);
+    }
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        throw new Error(`Refusing to open "${url}" — not a valid URL.`);
+    }
+    if (!bypass && isInternalHost(host)) {
+        throw new Error(`Refusing to navigate to internal/loopback host "${host}" — this could reach ` +
+            `Floorp's own automation API or your private network. ` +
+            `Set FLOORP_MCP_ALLOW_PRIVILEGED_URLS=1 to override.`);
+    }
+    const allow = process.env.FLOORP_MCP_ALLOW_DOMAINS;
+    if (allow) {
+        const h = host.toLowerCase();
+        const ok = allow
+            .split(",")
+            .map((d) => d.trim().toLowerCase())
+            .filter(Boolean)
+            .some((d) => h === d || h.endsWith("." + d));
+        if (!ok) {
+            throw new Error(`Refusing to navigate to "${host}" — not in FLOORP_MCP_ALLOW_DOMAINS allowlist.`);
+        }
+    }
+}
+/** If FLOORP_MCP_ALLOW_UPLOAD_DIRS is set (';'-separated on Windows), uploads are
+ *  restricted to files inside those directories. Paths are canonicalised with
+ *  realpath (resolving symlinks) and checked with path.relative so neither a
+ *  symlink, a "..", nor a same-prefix sibling dir (C:\\a vs C:\\ab) can escape.
+ *  UNC paths are rejected when an allowlist is set. Unset = any path (default). */
+export function assertUploadAllowed(filePath) {
+    const canon = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const resolved = canon(filePath);
+    const allow = process.env.FLOORP_MCP_ALLOW_UPLOAD_DIRS;
+    if (!allow)
+        return resolved;
+    if (process.platform === "win32" && /^\\\\/.test(resolved)) {
+        throw new Error(`Upload of "${resolved}" blocked — UNC paths are not allowed. Use a local absolute path.`);
+    }
+    const ok = allow
+        .split(delimiter)
+        .map((d) => d.trim())
+        .filter(Boolean)
+        .some((d) => {
+        const rel = relative(canon(d), resolved);
+        return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    });
+    if (!ok) {
+        throw new Error(`Upload of "${resolved}" blocked — outside FLOORP_MCP_ALLOW_UPLOAD_DIRS. ` +
+            `Add its directory to that variable (';'-separated) to allow it.`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

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

package/dist/html-find.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Server-side element locator. Searches a page's raw HTML by visible text and/or
+ * tag and returns compact, clickable CSS selectors — so the full page never has
+ * to reach the model. Pure (no I/O) so it can be unit-tested directly.
+ */
+/** Escape a raw attribute value for use inside a double-quoted CSS string. */
+export declare function cssString(v: string): string;
+/** Build a clickable CSS selector from an element's opening tag, preferring the
+ *  most stable identifier available. */
+export declare function suggestSelector(openTag: string, tag: string): string;
+export interface FoundEl {
+    tag: string;
+    selector: string;
+    text: string;
+}
+/** Locate elements in raw HTML by visible text and/or tag — runs server-side so
+ *  the full page never reaches the model. Returns compact, clickable matches. */
+export declare function findInHtml(html: string, opts: {
+    text?: string;
+    tag?: string;
+    limit: number;
+}): FoundEl[];

package/dist/html-find.js

@@ -0,0 +1,95 @@
+/**
+ * Server-side element locator. Searches a page's raw HTML by visible text and/or
+ * tag and returns compact, clickable CSS selectors — so the full page never has
+ * to reach the model. Pure (no I/O) so it can be unit-tested directly.
+ */
+/** Escape a raw attribute value for use inside a double-quoted CSS string. */
+export function cssString(v) {
+    return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** Build a clickable CSS selector from an element's opening tag, preferring the
+ *  most stable identifier available. */
+export function suggestSelector(openTag, tag) {
+    const id = openTag.match(/\sid="([^"]+)"/)?.[1];
+    if (id && /^[A-Za-z_][\w-]*$/.test(id))
+        return `#${id}`;
+    const name = openTag.match(/\sname="([^"]+)"/)?.[1];
+    if (name)
+        return `${tag}[name="${cssString(name)}"]`;
+    const href = openTag.match(/\shref="([^"]+)"/)?.[1];
+    if (href && href !== "#" && !href.startsWith("javascript:"))
+        return `${tag}[href="${cssString(href)}"]`;
+    const cls = openTag
+        .match(/\sclass="([^"]+)"/)?.[1]
+        ?.split(/\s+/)
+        .find((c) => /^[A-Za-z_][\w-]{1,}$/.test(c));
+    if (cls)
+        return `${tag}.${cls}`;
+    const type = openTag.match(/\stype="([^"]+)"/)?.[1];
+    if (type)
+        return `${tag}[type="${cssString(type)}"]`;
+    return tag;
+}
+/** Locate elements in raw HTML by visible text and/or tag — runs server-side so
+ *  the full page never reaches the model. Returns compact, clickable matches. */
+export function findInHtml(html, opts) {
+    // Strip Floorp's injected automation overlay so it can't pollute matches.
+    html = html
+        .replace(/<style id="nr-webscraper[\s\S]*?<\/style>/gi, " ")
+        .replace(/<div[^>]*nr-webscraper[\s\S]*?<\/div>/gi, " ");
+    const out = [];
+    const tagFilter = opts.tag?.toLowerCase();
+    const strip = (s) => s.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+    // Text nodes never live in these — skip them so a text search returns visible elements.
+    const INVISIBLE = new Set(["title", "meta", "script", "style", "head", "link", "noscript", "html"]);
+    // Skip elements an attacker can hide to lure the agent into clicking them. Best
+    // effort over raw HTML: catches inline hiding, the hidden attr, type=hidden,
+    // aria-hidden (not CSS-class-based hiding, which needs computed styles).
+    const isHidden = (openTag) => /\stype\s*=\s*["']?hidden/i.test(openTag) ||
+        /\shidden(\s|>|=|\/)/i.test(openTag) ||
+        /\saria-hidden\s*=\s*["']?true/i.test(openTag) ||
+        /\sstyle\s*=\s*["'][^"']*(display\s*:\s*none|visibility\s*:\s*hidden)/i.test(openTag);
+    if (opts.text) {
+        const lc = html.toLowerCase();
+        const q = opts.text.toLowerCase();
+        const seen = new Set();
+        let from = 0;
+        while (out.length < opts.limit) {
+            const idx = lc.indexOf(q, from);
+            if (idx < 0)
+                break;
+            from = idx + q.length;
+            const open = html.lastIndexOf("<", idx);
+            if (open < 0 || seen.has(open))
+                continue;
+            seen.add(open);
+            const tm = html.slice(open).match(/^<([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/);
+            if (!tm)
+                continue;
+            const tg = tm[1].toLowerCase();
+            if (INVISIBLE.has(tg))
+                continue;
+            if (isHidden(tm[0]))
+                continue;
+            if (tagFilter && tg !== tagFilter)
+                continue;
+            // Preview = the matched text node only; cut at the next tag so it can't bleed.
+            const seg = html.slice(idx, idx + 120);
+            const cut = seg.indexOf("<");
+            const text = (cut >= 0 ? seg.slice(0, cut) : seg).replace(/\s+/g, " ").trim();
+            out.push({ tag: tg, selector: suggestSelector(tm[0], tg), text });
+        }
+    }
+    else if (tagFilter) {
+        const re = new RegExp(`<${tagFilter}\\b[^>]*>`, "gi");
+        let m;
+        while ((m = re.exec(html)) && out.length < opts.limit) {
+            if (isHidden(m[0]))
+                continue;
+            const after = html.slice(m.index + m[0].length, m.index + m[0].length + 90);
+            out.push({ tag: tagFilter, selector: suggestSelector(m[0], tagFilter), text: strip(after) });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=html-find.js.map

package/dist/html-find.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * floorp-mcp — an MCP server that drives the Floorp browser through its
+ * built-in automation API (http://127.0.0.1:58261, gated by
+ * `floorp.mcp.enabled` in about:config).
+ *
+ * MVP tool surface: tab management, page reading, and screenshots, operating on
+ * the user's real, logged-in session.
+ */
+export {};