@burdenoff/fe-libs 2026.1024.4 → 2026.1027.1

package/dist/shared/agent-tools/types.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+/**
+ * ★ BOFF-9783: one definition of an action an AI agent may take in the page,
+ * exposed through every channel that can reach the page — the browser's own
+ * agent through W3C WebMCP (`document.modelContext`) and the product's in-app
+ * assistant through client tool calls.
+ *
+ * A tool is code the product chose to expose. It runs in the person's tab, with
+ * the person's session, through the same API calls the UI makes, so the
+ * gateway's `@rbac` and tenant checks apply exactly as they do to a click.
+ * Nothing here is a security boundary on its own: the hints are advisory, the
+ * confirmation is a courtesy to the person, the backend decides.
+ */
+/** Who asked for the tool to run. Logged; never trusted for authorization. */
+export type AgentToolInitiator = 'webmcp' | 'assistant';
+/**
+ * Advisory hints, mapped one to one onto WebMCP's `ToolAnnotations`.
+ *
+ * `consequential` is ALSO enforced here: such a tool never runs until the
+ * person confirms it in the page with a real click (`requestAgentConfirmation`).
+ */
+export interface AgentToolAnnotations {
+    /** The tool changes nothing. */
+    readOnly?: boolean;
+    /** The result carries text other people wrote (names, run output, errors). */
+    untrustedContent?: boolean;
+    /** The tool changes something that matters: it is confirmed before it runs. */
+    consequential?: boolean;
+}
+/** What the confirmation dialog says. Plain text — never markup. */
+export interface AgentToolConfirmation {
+    title: string;
+    body: string;
+    /** The confirm button's words, e.g. "Cancel run". */
+    confirmLabel: string;
+}
+export interface AgentToolExecuteContext {
+    /** Aborted when the agent cancels the call or the tool is unregistered. */
+    signal: AbortSignal;
+    initiator: AgentToolInitiator;
+}
+/** The input type a tool's zod object describes. */
+export type AgentToolInputSchema = z.ZodObject<z.ZodRawShape>;
+export interface AgentToolDefinition<S extends AgentToolInputSchema = AgentToolInputSchema, O = unknown> {
+    /** `^[a-z][a-z0-9_]*$`, at most 30 characters, e.g. `fg_runs_list`. */
+    name: string;
+    /** Short human title, shown in the confirmation dialog and the assistant's status line. */
+    title: string;
+    /** What the tool does and when to use it. At most 500 characters. */
+    description: string;
+    /**
+     * A STRICT zod object. Unknown keys are rejected, so every parameter has to be
+     * declared — each with a `.describe()` of at most 150 characters.
+     */
+    input: S;
+    annotations?: AgentToolAnnotations;
+    /** Required for consequential tools: what the person is asked to confirm. */
+    confirm?: (input: z.output<S>) => AgentToolConfirmation;
+    /**
+     * Do the work. Return only the fields an agent needs: the result is capped
+     * (`AGENT_TOOL_OUTPUT_MAX_BYTES`). Throw `AgentToolError` for an expected
+     * failure; anything else is reported as `FAILED` without its message.
+     */
+    execute: (input: z.output<S>, context: AgentToolExecuteContext) => Promise<O> | O;
+}
+/** A definition after `defineAgentTool` checked it and derived its JSON Schema. */
+export interface DefinedAgentTool<S extends AgentToolInputSchema = AgentToolInputSchema, O = unknown> extends AgentToolDefinition<S, O> {
+    /** JSON Schema (draft 2020-12) of the input, `additionalProperties: false`. */
+    readonly inputSchema: Record<string, unknown>;
+}
+/** Any defined tool, whatever its input and output types. */
+export type AnyDefinedAgentTool = DefinedAgentTool<AgentToolInputSchema, unknown>;
+export type AgentToolErrorCode = 
+/** The input failed validation; `message` says which field and why. */
+'INVALID_INPUT'
+/** The person is signed out. */
+ | 'UNAUTHENTICATED'
+/** The backend refused: the person may not do this here. */
+ | 'FORBIDDEN'
+/** Nothing with that id in the person's current workspace. */
+ | 'NOT_FOUND'
+/** The record is in a state that does not allow this. */
+ | 'CONFLICT'
+/** Only the person can do this step (a file picker, a sign-in popup, a confirmation they declined to give here). */
+ | 'NEEDS_USER'
+/** The person declined, or the call was cancelled. */
+ | 'CANCELLED'
+/** Anything else. */
+ | 'FAILED';
+export interface AgentToolSuccess<O = unknown> {
+    ok: true;
+    data: O;
+    /** Set when the result was cut to fit the output budget. */
+    truncated?: true;
+}
+export interface AgentToolFailure {
+    ok: false;
+    error: {
+        code: AgentToolErrorCode;
+        message: string;
+        /** True when the same call may succeed later or with corrected input. */
+        retryable: boolean;
+    };
+}
+/** What every channel returns to the agent. */
+export type AgentToolResult<O = unknown> = AgentToolSuccess<O> | AgentToolFailure;

package/dist/shared/agent-tools/ui/dom.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ★ BOFF-9783: the DOM rules the generic UI tools live by — what counts as a
+ * control, what a control is called, and which parts of the page an agent may
+ * never see or touch.
+ *
+ * These read the page the way assistive technology does (roles, accessible
+ * names, states), so the agent's view is the same one a screen-reader user
+ * gets, and a page that is accessible is also operable by an agent.
+ */
+/** Elements an agent can operate. */
+export declare const INTERACTIVE_SELECTOR: string;
+/**
+ * ★★ Regions an agent never sees or operates:
+ *  - anything a product marks `data-agent="deny"` (billing, secrets, vault…);
+ *  - the assistant's own panel, overlay and voice session — an agent must not
+ *    drive the conversation it is part of;
+ *  - every confirmation dialog — the person's decision, never the agent's
+ *    (the dialogs also ignore untrusted clicks; this is the second line).
+ */
+export declare const DENY_SELECTOR: string;
+export declare function isDenied(element: Element): boolean;
+/** A credential, payment or one-time-code field, or one a product marked sensitive. */
+export declare function isSensitiveField(element: Element): boolean;
+/**
+ * Rendered and reachable: not hidden, not inert, not behind a modal (a modal
+ * dialog marks the rest of the page `aria-hidden`), not `display: none`.
+ */
+export declare function isVisible(element: Element): boolean;
+export declare function isDisabled(element: Element): boolean;
+/** The ARIA role, explicit or implied by the element. */
+export declare function roleOf(element: Element): string;
+/**
+ * The accessible name, in the order assistive technology computes it:
+ * aria-labelledby → aria-label → associated <label> → title → own text (for
+ * buttons, links and the like) → placeholder.
+ */
+export declare function accessibleName(element: Element): string;
+/** Short state flags: "disabled", "checked", "expanded", … */
+export declare function stateOf(element: Element): string[];
+/** The current value of a field, unless it is sensitive. */
+export declare function valueOf(element: Element): string | null;
+/** The open dialog's title, if a (non-denied) dialog is open. */
+export declare function openDialogTitle(doc: Document): string | null;

package/dist/shared/agent-tools/ui/dom.js

@@ -0,0 +1,178 @@
+//#region src/shared/agent-tools/ui/dom.ts
+var e = [
+	"a[href]",
+	"button",
+	"input:not([type=\"hidden\"])",
+	"select",
+	"textarea",
+	"summary",
+	"[contenteditable=\"true\"]",
+	"[contenteditable=\"\"]",
+	...[
+		"button",
+		"link",
+		"tab",
+		"menuitem",
+		"menuitemcheckbox",
+		"menuitemradio",
+		"option",
+		"checkbox",
+		"radio",
+		"switch",
+		"combobox",
+		"textbox",
+		"searchbox",
+		"slider",
+		"spinbutton",
+		"treeitem"
+	].map((e) => `[role="${e}"]`)
+].join(", "), t = [
+	"[data-agent=\"deny\"]",
+	"[data-assistant-panel]",
+	"[data-assistant-overlay]",
+	"[data-assistant-voice-session]",
+	"[data-testid^=\"agent-tool-confirm\"]",
+	"[role=\"alertdialog\"][data-testid^=\"assistant-\"]",
+	"[role=\"dialog\"][data-testid^=\"assistant-\"]"
+].join(", "), n = /(^|\s)(current-password|new-password|one-time-code|cc-[a-z-]+|webauthn)(\s|$)/i, r = /pass(word|code|phrase)|passwd|pwd|secret|token|api[-_]?key|private[-_]?key|client[-_]?secret|cvv|cvc|card[-_]?number|iban|ssn/i;
+function i(e) {
+	return e.closest(t) !== null;
+}
+function a(e) {
+	if (e.closest("[data-agent-sensitive]")) return !0;
+	let t = e.tagName.toLowerCase();
+	if (t !== "input" && t !== "textarea") return !1;
+	if ((e.getAttribute("type") ?? "").toLowerCase() === "password" || n.test(e.getAttribute("autocomplete") ?? "")) return !0;
+	let i = `${e.getAttribute("name") ?? ""} ${e.getAttribute("id") ?? ""}`;
+	return r.test(i);
+}
+function o(e) {
+	if (!e.isConnected || e.closest("[hidden], [inert], [aria-hidden=\"true\"]")) return !1;
+	let t = e;
+	if (typeof t.checkVisibility == "function") return t.checkVisibility({
+		checkOpacity: !1,
+		checkVisibilityCSS: !0
+	});
+	let n = e.ownerDocument.defaultView;
+	if (!n) return !0;
+	for (let t = e; t; t = t.parentElement) {
+		let e = n.getComputedStyle(t);
+		if (e.display === "none" || e.visibility === "hidden") return !1;
+	}
+	return !0;
+}
+function s(e) {
+	return e.getAttribute("aria-disabled") === "true" ? !0 : "disabled" in e && e.disabled === !0;
+}
+var c = {
+	checkbox: "checkbox",
+	radio: "radio",
+	range: "slider",
+	number: "spinbutton",
+	button: "button",
+	submit: "button",
+	reset: "button",
+	image: "button",
+	search: "searchbox",
+	file: "file"
+};
+function l(e) {
+	let t = e.getAttribute("role")?.trim().split(/\s+/)[0];
+	if (t) return t;
+	switch (e.tagName.toLowerCase()) {
+		case "a": return "link";
+		case "button":
+		case "summary": return "button";
+		case "select": return e.multiple ? "listbox" : "combobox";
+		case "textarea": return "textbox";
+		case "input": return c[(e.getAttribute("type") ?? "text").toLowerCase()] ?? "textbox";
+		default: return e.hasAttribute("contenteditable") ? "textbox" : "generic";
+	}
+}
+function u(e) {
+	return (e ?? "").replace(/\s+/g, " ").trim();
+}
+var d = 80;
+function f(e) {
+	let t = e.ownerDocument, n = (e) => e.length > d ? `${e.slice(0, d - 1)}…` : e, r = e.getAttribute("aria-labelledby");
+	if (r) {
+		let e = u(r.split(/\s+/).map((e) => t.getElementById(e)?.textContent ?? "").join(" "));
+		if (e) return n(e);
+	}
+	let i = u(e.getAttribute("aria-label"));
+	if (i) return n(i);
+	let a = e.labels;
+	if (a && a.length > 0) {
+		let e = u(Array.from(a, (e) => e.textContent ?? "").join(" "));
+		if (e) return n(e);
+	}
+	let o = u(e.getAttribute("title"));
+	if (o) return n(o);
+	let s = e.tagName.toLowerCase();
+	if (!(s === "textarea" || s === "select" || s === "input" && ![
+		"button",
+		"submit",
+		"reset"
+	].includes((e.getAttribute("type") ?? "").toLowerCase()))) {
+		let t = u(e.textContent);
+		if (t) return n(t);
+		let r = u(e.querySelector("img[alt]")?.getAttribute("alt"));
+		if (r) return n(r);
+		if (s === "input") {
+			let t = u(e.value);
+			if (t) return n(t);
+		}
+	}
+	return n(u(e.getAttribute("placeholder")));
+}
+function p(e) {
+	let t = [];
+	s(e) && t.push("disabled");
+	let n = e.tagName.toLowerCase(), r = (e.getAttribute("type") ?? "").toLowerCase();
+	n === "input" && (r === "checkbox" || r === "radio") ? e.checked && t.push("checked") : e.getAttribute("aria-checked") === "true" && t.push("checked");
+	for (let n of [
+		"expanded",
+		"selected",
+		"pressed"
+	]) e.getAttribute(`aria-${n}`) === "true" && t.push(n);
+	return e.getAttribute("aria-current") && e.getAttribute("aria-current") !== "false" && t.push("current"), (e.hasAttribute("required") || e.getAttribute("aria-required") === "true") && t.push("required"), t;
+}
+var m = 60;
+function h(e) {
+	if (a(e)) return null;
+	let t = e.tagName.toLowerCase(), n = null;
+	if (t === "select") {
+		let t = e;
+		n = t.selectedOptions[0]?.textContent ?? t.value;
+	} else if (t === "textarea") n = e.value;
+	else if (t === "input") {
+		let t = (e.getAttribute("type") ?? "text").toLowerCase();
+		if ([
+			"checkbox",
+			"radio",
+			"button",
+			"submit",
+			"reset",
+			"image",
+			"file"
+		].includes(t)) return null;
+		n = e.value;
+	} else (e.getAttribute("role") === "combobox" || e.hasAttribute("aria-valuenow")) && (n = e.getAttribute("aria-valuetext") ?? e.getAttribute("aria-valuenow"));
+	let r = u(n);
+	return r ? r.length > m ? `${r.slice(0, m - 1)}…` : r : null;
+}
+function g(e) {
+	let t = Array.from(e.querySelectorAll("[role=\"dialog\"], [role=\"alertdialog\"], dialog[open]")).filter((e) => o(e) && !i(e)), n = t[t.length - 1];
+	return n ? _(n) || "Dialog" : null;
+}
+function _(e) {
+	let t = e.getAttribute("aria-labelledby");
+	if (t) {
+		let n = u(e.ownerDocument.getElementById(t)?.textContent);
+		if (n) return n.slice(0, d);
+	}
+	let n = u(e.getAttribute("aria-label"));
+	return n ? n.slice(0, d) : u(e.querySelector("h1, h2, h3")?.textContent).slice(0, d);
+}
+//#endregion
+export { t as DENY_SELECTOR, e as INTERACTIVE_SELECTOR, f as accessibleName, i as isDenied, s as isDisabled, a as isSensitiveField, o as isVisible, g as openDialogTitle, l as roleOf, p as stateOf, h as valueOf };

package/dist/shared/agent-tools/ui/refs.d.ts

@@ -0,0 +1,8 @@
+export declare const REF_PATTERN: RegExp;
+export declare function refFor(element: Element): string;
+/** The element for `ref`, or null when it is gone from the page. */
+export declare function elementFor(ref: string): Element | null;
+/** Forget refs whose elements are gone. Called on every snapshot. */
+export declare function pruneRefs(): void;
+/** Test seam. */
+export declare function resetRefs(): void;

package/dist/shared/agent-tools/ui/refs.js

@@ -0,0 +1,20 @@
+//#region src/shared/agent-tools/ui/refs.ts
+var e = /* @__PURE__ */ new WeakMap(), t = /* @__PURE__ */ new Map(), n = 1, r = /^e\d{1,7}$/;
+function i(r) {
+	let i = e.get(r);
+	if (i) return t.has(i) || t.set(i, new WeakRef(r)), i;
+	let a = `e${n}`;
+	return n += 1, e.set(r, a), t.set(a, new WeakRef(r)), a;
+}
+function a(e) {
+	let n = t.get(e)?.deref();
+	return !n || !n.isConnected ? null : n;
+}
+function o() {
+	for (let [e, n] of t) {
+		let r = n.deref();
+		(!r || !r.isConnected) && t.delete(e);
+	}
+}
+//#endregion
+export { r as REF_PATTERN, a as elementFor, o as pruneRefs, i as refFor };

package/dist/shared/agent-tools/ui/uiTools.d.ts

@@ -0,0 +1,40 @@
+import { AnyDefinedAgentTool } from '../types';
+/**
+ * ★ BOFF-9783: generic UI tools — see the page, click, type, choose, press a
+ * key — so an agent can do in any product what the person can do with a mouse
+ * and keyboard, without each product writing a tool per button.
+ *
+ * Guards, in order of strength:
+ *  - deny zones (`dom.ts`) are invisible and inoperable: products mark billing,
+ *    secrets and the like `data-agent="deny"`; the assistant panel and every
+ *    confirmation dialog are always denied;
+ *  - sensitive fields (passwords, payment, one-time codes) are listed but never
+ *    read or filled;
+ *  - a click on something consequential ("Delete", "Cancel run", "Log out", or
+ *    `data-agent="confirm"`) waits for the person to confirm with a real click;
+ *  - what only a person can start (a file picker, a link out of the tab) is
+ *    refused with `NEEDS_USER`.
+ *
+ * Every action is an ordinary page event, so the app's own handlers, validation
+ * and confirmation dialogs run as they would for the person — and those
+ * dialogs ignore the untrusted clicks scripts make, so an agent can open a
+ * "Delete?" dialog but never answer it.
+ */
+export interface UiToolsOptions {
+    /** Where the agent may look. Default `document.body`. */
+    root?: () => Element | null;
+}
+/**
+ * Would a click on this deserve the person's confirmation?
+ *
+ * ★ Locale-independent signals come first, because a product's labels may be
+ * in any language ("Supprimer", "Eliminar"):
+ *  - `data-agent="confirm"` on the control or a wrapper (product-declared);
+ *  - a destructive button (`data-variant="destructive"`, the shared Button);
+ *  - any control inside an alert dialog except its cancel button
+ *    (`data-slot="alert-dialog-cancel"`): alert dialogs are where the app asks
+ *    "are you sure?", so their action is the consequential step.
+ * The English verb list is an extra net for unmarked controls, not the rule.
+ */
+export declare function isConsequentialControl(element: Element, name: string): boolean;
+export declare function createUiTools(options?: UiToolsOptions): AnyDefinedAgentTool[];

package/dist/shared/agent-tools/ui/uiTools.js

@@ -0,0 +1,277 @@
+import { AgentToolError as e } from "../errors.js";
+import { requestAgentConfirmation as t } from "../confirm/confirmStore.js";
+import { defineAgentTool as n } from "../defineAgentTool.js";
+import { INTERACTIVE_SELECTOR as r, accessibleName as i, isDenied as a, isDisabled as o, isSensitiveField as s, isVisible as c, openDialogTitle as l, roleOf as u, stateOf as d, valueOf as f } from "./dom.js";
+import { REF_PATTERN as p, elementFor as m, pruneRefs as h, refFor as g } from "./refs.js";
+import { z as _ } from "zod";
+//#region src/shared/agent-tools/ui/uiTools.ts
+var v = 1100, y = new TextEncoder(), b = 250, x = 3e3, S = 1200, C = /\b(delete|remove|archive|revoke|deactivate|disable|cancel|terminate|stop|pay|purchase|buy|checkout|transfer|subscribe|unsubscribe|upgrade|downgrade|log ?out|sign ?out|reset|publish|send|invite|uninstall|disconnect|approve|reject)\b/i, w = /^(cancel|close|dismiss|back|no|not now|keep editing)$/i;
+function T(e, t) {
+	if (e.closest("[data-agent=\"confirm\"]") || e.closest("[data-variant=\"destructive\"]")) return !0;
+	if (e.closest("[role=\"alertdialog\"]")) return e.closest("[data-slot=\"alert-dialog-cancel\"]") === null;
+	let n = t.trim();
+	return w.test(n) ? !1 : C.test(n);
+}
+var E = _.string().regex(p, "must be a ref from ui_snapshot, like \"e12\"").describe("The ref of the element, from ui_snapshot (e.g. \"e12\").");
+function D() {
+	return typeof document > "u" ? null : document.body;
+}
+function O(t) {
+	let n = m(t);
+	if (!n) throw new e("NOT_FOUND", "That element is no longer on the page. Take a new ui_snapshot.", { retryable: !0 });
+	if (a(n)) throw new e("FORBIDDEN", "That part of the page is off-limits to agents.");
+	if (!c(n)) throw new e("CONFLICT", "That element is not visible right now. Take a new ui_snapshot.", { retryable: !0 });
+	return n;
+}
+function k(e) {
+	let { outline: t, outlineOffset: n } = e.style;
+	e.style.outline = "2px solid var(--ring)", e.style.outlineOffset = "2px", setTimeout(() => {
+		e.style.outline = t, e.style.outlineOffset = n;
+	}, S);
+}
+function A(e) {
+	e.scrollIntoView?.({
+		block: "center",
+		inline: "nearest"
+	}), k(e);
+}
+function j(e, t) {
+	return new Promise((n) => {
+		let r = e.defaultView;
+		if (!r || typeof r.MutationObserver != "function") {
+			n();
+			return;
+		}
+		let i, a = () => {
+			o.disconnect(), clearTimeout(i), clearTimeout(s), t.removeEventListener("abort", a), n();
+		}, o = new r.MutationObserver(() => {
+			clearTimeout(i), i = setTimeout(a, b);
+		});
+		o.observe(e.body, {
+			childList: !0,
+			subtree: !0,
+			attributes: !0,
+			characterData: !0
+		}), i = setTimeout(a, b);
+		let s = setTimeout(a, x);
+		t.addEventListener("abort", a, { once: !0 });
+	});
+}
+function M(e) {
+	let t = Array.from(e.querySelectorAll("[data-sonner-toast], [role=\"alert\"]")).filter((e) => c(e) && !a(e)).map((e) => (e.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 120)).filter(Boolean).slice(-3), n = l(e);
+	return {
+		path: e.defaultView?.location.pathname ?? null,
+		...n ? { dialog: n } : {},
+		...t.length > 0 ? { notices: t } : {}
+	};
+}
+function N(e, t) {
+	let n = {
+		bubbles: !0,
+		cancelable: !0,
+		composed: !0,
+		button: 0,
+		view: t
+	};
+	return typeof t.PointerEvent == "function" ? new t.PointerEvent(e, {
+		...n,
+		pointerType: "mouse",
+		isPrimary: !0
+	}) : new t.MouseEvent(e, n);
+}
+function P(e) {
+	let t = e.ownerDocument.defaultView;
+	e.focus?.({ preventScroll: !0 }), t && (e.dispatchEvent(N("pointerdown", t)), e.dispatchEvent(new t.MouseEvent("mousedown", {
+		bubbles: !0,
+		cancelable: !0
+	})), e.dispatchEvent(N("pointerup", t)), e.dispatchEvent(new t.MouseEvent("mouseup", {
+		bubbles: !0,
+		cancelable: !0
+	}))), e.click();
+}
+function F(e, t) {
+	let n = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(e), "value")?.set;
+	n ? n.call(e, t) : e.value = t;
+	let r = e.ownerDocument.defaultView, i = r?.InputEvent ?? r?.Event;
+	i && e.dispatchEvent(new i("input", {
+		bubbles: !0,
+		cancelable: !1,
+		composed: !0
+	})), e.dispatchEvent(new Event("change", { bubbles: !0 }));
+}
+function I(e) {
+	let t = e.closest("a[href]");
+	if (!t) return !1;
+	if (t.target && t.target !== "_self") return !0;
+	let n = e.ownerDocument.defaultView?.location.origin;
+	try {
+		return !!n && new URL(t.href, n).origin !== n;
+	} catch {
+		return !0;
+	}
+}
+function L(p = {}) {
+	let m = p.root ?? D;
+	return [
+		n({
+			name: "ui_snapshot",
+			title: "Read the screen",
+			description: "Lists the controls visible on the page (links, buttons, fields, tabs, menu items) with a ref, role, name, current value and state. Use the refs with ui_click, ui_fill, ui_select and ui_press_key. Take a new snapshot after the page changes. Page through long lists with offset.",
+			input: _.strictObject({
+				filter: _.string().trim().max(60).optional().describe("Only list controls whose name or role contains this text."),
+				offset: _.number().int().min(0).max(5e3).default(0).describe("Index of the first control to list, from nextOffset of a previous call.")
+			}),
+			annotations: {
+				readOnly: !0,
+				untrustedContent: !0
+			},
+			execute: ({ filter: t, offset: n }) => {
+				let o = m();
+				if (!o) throw new e("NEEDS_USER", "The page is not available.");
+				h();
+				let p = t?.toLowerCase(), _ = Array.from(o.querySelectorAll(r)).filter((e) => c(e) && !a(e) && u(e) !== "generic"), b = [];
+				for (let e of _) {
+					let t = u(e), n = i(e);
+					if (p && !`${t} ${n}`.toLowerCase().includes(p)) continue;
+					let r = s(e), a = r ? null : f(e), o = d(e);
+					r && o.push("sensitive"), b.push(`${g(e)} ${t} ${JSON.stringify(n)}${a ? ` value=${JSON.stringify(a)}` : ""}${o.length > 0 ? ` [${o.join(",")}]` : ""}`);
+				}
+				let x = [], S = 0, C = n;
+				for (; C < b.length; C += 1) {
+					let e = b[C] ?? "", t = y.encode(e).length + 3;
+					if (x.length > 0 && S + t > v) break;
+					x.push(e), S += t;
+				}
+				let w = o.ownerDocument, T = w.querySelector("main h1, h1")?.textContent?.replace(/\s+/g, " ").trim(), E = l(w);
+				return {
+					path: w.defaultView?.location.pathname ?? null,
+					...T ? { heading: T.slice(0, 120) } : {},
+					...E ? { dialog: E } : {},
+					total: b.length,
+					items: x,
+					...C < b.length ? { nextOffset: C } : {}
+				};
+			}
+		}),
+		n({
+			name: "ui_click",
+			title: "Click",
+			description: "Clicks a control from ui_snapshot (button, link, tab, menu item, checkbox). Returns the page path, any dialog that opened and new notices. Clicks that delete, cancel, pay or similar first ask the person to confirm.",
+			input: _.strictObject({ ref: E }),
+			execute: async ({ ref: n }, { signal: r }) => {
+				let a = O(n);
+				if (o(a)) throw new e("CONFLICT", "That control is disabled right now.");
+				if (s(a)) throw new e("NEEDS_USER", "That control belongs to a password, key or payment field: ask the person to use it.");
+				if (a instanceof HTMLInputElement && a.type === "file") throw new e("NEEDS_USER", "Choosing a file needs the person: ask them to pick it.");
+				if (I(a)) throw new e("NEEDS_USER", "That link opens outside this tab: ask the person to open it.");
+				let c = i(a), l = u(a);
+				if (T(a, c)) {
+					if (!await t("Click", {
+						title: "Allow this click?",
+						body: `An AI agent wants to click "${c || u(a)}" on this page.`,
+						confirmLabel: "Allow"
+					}, r)) throw new e("CANCELLED", "The person declined this click.");
+					let s = O(n);
+					if (s !== a || o(s) || i(s) !== c || u(s) !== l) throw new e("CONFLICT", "The page changed. Take a new ui_snapshot.", { retryable: !0 });
+				}
+				return A(a), P(a), await j(a.ownerDocument, r), {
+					clicked: c || u(a),
+					...M(a.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_fill",
+			title: "Type into a field",
+			description: "Replaces the text of a text field, text area or search box from ui_snapshot. Does not submit; click the submit button or press Enter afterwards. Password, payment and code fields are refused.",
+			input: _.strictObject({
+				ref: E,
+				value: _.string().max(2e3).describe("The text the field should contain.")
+			}),
+			execute: async ({ ref: t, value: n }, { signal: r }) => {
+				let a = O(t);
+				if (s(a)) throw new e("NEEDS_USER", "That is a password, payment or code field: ask the person to fill it.");
+				if (o(a) || a.readOnly) throw new e("CONFLICT", "That field cannot be edited right now.");
+				if (A(a), a.focus?.({ preventScroll: !0 }), a instanceof HTMLInputElement || a instanceof HTMLTextAreaElement) {
+					let t = u(a);
+					if (![
+						"textbox",
+						"searchbox",
+						"combobox",
+						"spinbutton"
+					].includes(t)) throw new e("INVALID_INPUT", `A ${t} is not a text field; use ui_click.`);
+					if (a.maxLength > 0 && n.length > a.maxLength) throw new e("INVALID_INPUT", `That field takes at most ${a.maxLength} characters.`);
+					F(a, n);
+				} else if (a.isContentEditable) a.textContent = n, a.dispatchEvent(new Event("input", { bubbles: !0 }));
+				else throw new e("INVALID_INPUT", "That element is not a text field. Use ui_click, or ui_select for a dropdown.");
+				return await j(a.ownerDocument, r), {
+					filled: i(a),
+					...M(a.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_select",
+			title: "Choose an option",
+			description: "Chooses an option in a native dropdown (select) from ui_snapshot, by its visible text or value. For a custom dropdown, ui_click it, take a new ui_snapshot and ui_click the option.",
+			input: _.strictObject({
+				ref: E,
+				option: _.string().trim().min(1).max(200).describe("The option text (or value) to choose.")
+			}),
+			execute: async ({ ref: t, option: n }, { signal: r }) => {
+				let i = O(t);
+				if (!(i instanceof HTMLSelectElement)) throw new e("INVALID_INPUT", "That is not a native dropdown: ui_click it, take a new ui_snapshot, then ui_click the option.");
+				if (o(i)) throw new e("CONFLICT", "That dropdown is disabled.");
+				let a = n.toLowerCase(), s = Array.from(i.options).find((e) => !e.disabled && ((e.textContent ?? "").trim().toLowerCase() === a || e.value.toLowerCase() === a));
+				if (!s) {
+					let t = Array.from(i.options).filter((e) => !e.disabled).slice(0, 15).map((e) => (e.textContent ?? "").trim()).join(", ");
+					throw new e("INVALID_INPUT", `No option "${n.slice(0, 60)}". Options: ${t}`);
+				}
+				A(i);
+				let c = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value")?.set;
+				return c ? c.call(i, s.value) : i.value = s.value, i.dispatchEvent(new Event("input", { bubbles: !0 })), i.dispatchEvent(new Event("change", { bubbles: !0 })), await j(i.ownerDocument, r), {
+					selected: (s.textContent ?? "").trim(),
+					...M(i.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_press_key",
+			title: "Press a key",
+			description: "Presses a key on a control from ui_snapshot, or on the focused element: Enter to submit or activate, Escape to close a menu or dialog, arrow keys to move in lists.",
+			input: _.strictObject({
+				key: _.enum([
+					"Enter",
+					"Escape",
+					"ArrowUp",
+					"ArrowDown",
+					"ArrowLeft",
+					"ArrowRight"
+				]).describe("The key to press."),
+				ref: E.optional().describe("Element to press it on. Default: the focused element.")
+			}),
+			execute: async ({ key: t, ref: n }, { signal: r }) => {
+				let o = m()?.ownerDocument ?? (typeof document > "u" ? null : document);
+				if (!o) throw new e("NEEDS_USER", "The page is not available.");
+				let s = n ? O(n) : o.activeElement ?? o.body;
+				if (!s) throw new e("NEEDS_USER", "Nothing has focus on the page.");
+				if (a(s)) throw new e("FORBIDDEN", "Focus is in a part of the page that is off-limits to agents.");
+				if (t === "Enter" && T(s, i(s))) throw new e("NEEDS_USER", "Use ui_click on that control: it needs the person to confirm.");
+				s.focus?.({ preventScroll: !0 });
+				let c = o.defaultView?.KeyboardEvent ?? KeyboardEvent, l = {
+					key: t,
+					code: t,
+					bubbles: !0,
+					cancelable: !0,
+					composed: !0
+				};
+				return s.dispatchEvent(new c("keydown", l)), s.dispatchEvent(new c("keyup", l)), await j(o, r), {
+					pressed: t,
+					...M(o)
+				};
+			}
+		})
+	];
+}
+//#endregion
+export { L as createUiTools, T as isConsequentialControl };