@athenaintel/react 0.60.1 → 0.61.0

package/dist/agent-ui/contract.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.cjs","sources":["../../src/agent-ui/contract.ts"],"sourcesContent":["/*\n * Agent targets: the elements of an app the agent may see, point at and\n * operate on the screen the person has open.\n *\n * The contract is a handful of `data-agent-*` attributes on the element\n * itself. The DOM is the registry: what is in the document is what is on\n * screen, list rows and third-party components need nothing special, and a\n * plain web component can take part without React. `agentTarget()` writes the\n * attributes with types; `useAgentTarget()` also registers handlers for a\n * control that ordinary clicks and typing cannot drive.\n *\n * The app decides what the agent can touch: an element without\n * `data-agent-target` does not exist for the agent, a target lists the actions\n * it allows, and one marked dangerous or sensitive is treated as such by every\n * tool. Nothing here is a permission boundary. The tools drive the same\n * handlers a click would, as the signed-in person.\n */\n\n/** What the agent may do to a target, beyond pointing at it. */\nexport const AGENT_TARGET_ACTIONS = ['click', 'type', 'select', 'toggle', 'clear'] as const;\nexport type AgentTargetAction = (typeof AGENT_TARGET_ACTIONS)[number];\n\nexport function isAgentTargetAction(value: unknown): value is AgentTargetAction {\n  return AGENT_TARGET_ACTIONS.some((action) => action === value);\n}\n\n/** The attribute names of the contract. */\nexport const AGENT_ATTR = {\n  /** The target's id, stable across renders (`investors.search`). */\n  target: 'data-agent-target',\n  /** Which one of several targets sharing an id (a row's key). */\n  key: 'data-agent-key',\n  /** The name the person would call it. Falls back to the element's own accessible name. */\n  label: 'data-agent-label',\n  /** One line for the agent on what it is for. */\n  description: 'data-agent-description',\n  /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */\n  actions: 'data-agent-actions',\n  /** Present: acting on it changes or destroys something, so the person confirms every time. */\n  danger: 'data-agent-danger',\n  /** Present: its value is never read and never typed. */\n  sensitive: 'data-agent-sensitive',\n  /** On a container: a named part of the screen its targets belong to. */\n  region: 'data-agent-region',\n  /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */\n  layer: 'data-agent-ui-layer',\n} as const;\n\n/** What an app says about one target. */\nexport interface AgentTargetOptions {\n  /**\n   * The target's id: lowercase words joined by `.`, `-` or `_`\n   * (`investors.search`, `filters.stage`). Stable across renders and visits,\n   * since the agent names targets by it.\n   */\n  id: string;\n  /** Which one, when several targets share the id (a table row's key). */\n  key?: string;\n  /** The name a person would call it (\"Search investors\"). */\n  label?: string;\n  /** One line for the agent: what it is for, or what using it does. */\n  description?: string;\n  /**\n   * What the agent may do to it. Absent: what the element allows by its\n   * nature (a button is clicked, a text field typed into). An empty list: the\n   * agent may only point at it.\n   */\n  actions?: readonly AgentTargetAction[];\n  /** Acting on it changes or destroys something: the person confirms every time. */\n  danger?: boolean;\n  /** Its value is never read back to the agent and never typed by it. */\n  sensitive?: boolean;\n}\n\n/** The props an element takes to become a target. */\nexport type AgentTargetProps = Readonly<Record<string, string>>;\n\nconst TARGET_ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;\nconst NO_PROPS: AgentTargetProps = {};\n\n/** Whether `id` is a well-formed target id. */\nexport function isAgentTargetId(id: string): boolean {\n  return id.length <= 80 && TARGET_ID_PATTERN.test(id);\n}\n\n/**\n * The props that make an element an agent target. Spread them on the element\n * (any component that passes `data-*` props to its root works):\n *\n * ```tsx\n * <input {...agentTarget({ id: 'investors.search', label: 'Search investors' })} />\n * {rows.map((row) => (\n *   <tr key={row.id} {...agentTarget({ id: 'investors.row', key: row.id, label: row.name })} />\n * ))}\n * ```\n */\nexport function agentTarget(options: AgentTargetOptions): AgentTargetProps {\n  if (!isAgentTargetId(options.id)) {\n    // An id built from data must never take the page down with it: the\n    // element is simply not a target, and the console says why.\n    console.error(\n      `agentTarget: \"${options.id}\" is not a target id, so the element is not a target. Use lowercase words joined by \".\", \"-\" or \"_\" (e.g. \"investors.search\").`,\n    );\n    return NO_PROPS;\n  }\n  const props: Record<string, string> = { [AGENT_ATTR.target]: options.id };\n  if (options.key !== undefined && options.key !== '') props[AGENT_ATTR.key] = options.key;\n  if (options.label) props[AGENT_ATTR.label] = options.label;\n  if (options.description) props[AGENT_ATTR.description] = options.description;\n  if (options.actions) {\n    props[AGENT_ATTR.actions] = options.actions.length > 0 ? options.actions.join(' ') : 'none';\n  }\n  if (options.danger) props[AGENT_ATTR.danger] = '';\n  if (options.sensitive) props[AGENT_ATTR.sensitive] = '';\n  return props;\n}\n\n/** The props that name a part of the screen; targets inside it are grouped under it. */\nexport function agentRegion({ id, label }: { id: string; label?: string }): AgentTargetProps {\n  if (!isAgentTargetId(id)) {\n    console.error(`agentRegion: \"${id}\" is not a region id (e.g. \"filters\"), so the element names no region.`);\n    return NO_PROPS;\n  }\n  return label ? { [AGENT_ATTR.region]: id, [AGENT_ATTR.label]: label } : { [AGENT_ATTR.region]: id };\n}\n\n/** How the agent names one target: its id, with its key in brackets when it has one. */\nexport function agentTargetRef({ id, key }: { id: string; key?: string | null }): string {\n  return key ? `${id}[${key}]` : id;\n}\n\n/** A reference split into id and key; `null` when it is not one. */\nexport function parseAgentTargetRef(ref: string): { id: string; key: string | null } | null {\n  const text = ref.trim();\n  const match = /^([^[\\]]+)(?:\\[(.+)\\])?$/.exec(text);\n  if (!match?.[1]) return null;\n  return { id: match[1].trim(), key: match[2] ?? null };\n}\n\n/**\n * What a target does when ordinary input cannot drive it (a custom select, a\n * date picker, a canvas). A handler here replaces the tool's own click or\n * keystrokes for that action; it runs the app's own code, so validation and\n * undo apply as for a person.\n */\nexport interface AgentTargetHandlers {\n  click?: () => void | Promise<void>;\n  /** Called with the text so far as it is typed, then once more with `done: true`. */\n  type?: (args: { text: string; done: boolean }) => void | Promise<void>;\n  select?: (args: { option: string }) => void | Promise<void>;\n  toggle?: (args: { checked: boolean | null }) => void | Promise<void>;\n  clear?: () => void | Promise<void>;\n  /** The options a `select` may be given, when the element is not a native `<select>`. */\n  options?: () => readonly string[];\n  /** The target's current value, as the agent should read it. */\n  value?: () => string | null;\n}\n\nconst HANDLER_REGISTRY_KEY = Symbol.for('athena.agentUi.targetHandlers');\n\ntype HandlerRegistry = Map<string, AgentTargetHandlers>;\n\n/**\n * One registry per page, on `globalThis`: a host can carry more than one copy\n * of this module (the SDK bundles its own), and a handler registered through\n * one must be found by the tools of another.\n */\nfunction handlerRegistry(): HandlerRegistry {\n  const holder = globalThis as typeof globalThis & { [HANDLER_REGISTRY_KEY]?: HandlerRegistry };\n  let registry = holder[HANDLER_REGISTRY_KEY];\n  if (!registry) {\n    registry = new Map();\n    holder[HANDLER_REGISTRY_KEY] = registry;\n  }\n  return registry;\n}\n\n/** Register a target's handlers; returns the unregister function. */\nexport function registerAgentTargetHandlers({\n  ref,\n  handlers,\n}: {\n  ref: string;\n  handlers: AgentTargetHandlers;\n}): () => void {\n  const registry = handlerRegistry();\n  if (registry.has(ref)) {\n    // Handlers are found by reference: with two mounted targets sharing one,\n    // the agent would be shown one and run the other's.\n    console.error(\n      `useAgentTarget: two mounted targets share \"${ref}\" and both register handlers. Give each its own key.`,\n    );\n  }\n  registry.set(ref, handlers);\n  return () => {\n    if (registry.get(ref) === handlers) registry.delete(ref);\n  };\n}\n\n/** The handlers registered for a target reference, if any. */\nexport function agentTargetHandlers(ref: string): AgentTargetHandlers | undefined {\n  return handlerRegistry().get(ref);\n}\n"],"names":[],"mappings":";;AAmBO,MAAM,uBAAuB,CAAC,SAAS,QAAQ,UAAU,UAAU,OAAO;AAG1E,SAAS,oBAAoB,OAA4C;AAC9E,SAAO,qBAAqB,KAAK,CAAC,WAAW,WAAW,KAAK;AAC/D;AAGO,MAAM,aAAa;AAAA;AAAA,EAExB,QAAQ;AAAA;AAAA,EAER,KAAK;AAAA;AAAA,EAEL,OAAO;AAAA;AAAA,EAEP,aAAa;AAAA;AAAA,EAEb,SAAS;AAAA;AAAA,EAET,QAAQ;AAAA;AAAA,EAER,WAAW;AAAA;AAAA,EAEX,QAAQ;AAAA;AAAA,EAER,OAAO;AACT;AA+BA,MAAM,oBAAoB;AAC1B,MAAM,WAA6B,CAAA;AAG5B,SAAS,gBAAgB,IAAqB;AACnD,SAAO,GAAG,UAAU,MAAM,kBAAkB,KAAK,EAAE;AACrD;AAaO,SAAS,YAAY,SAA+C;AACzE,MAAI,CAAC,gBAAgB,QAAQ,EAAE,GAAG;AAGhC,YAAQ;AAAA,MACN,iBAAiB,QAAQ,EAAE;AAAA,IAAA;AAE7B,WAAO;AAAA,EACT;AACA,QAAM,QAAgC,EAAE,CAAC,WAAW,MAAM,GAAG,QAAQ,GAAA;AACrE,MAAI,QAAQ,QAAQ,UAAa,QAAQ,QAAQ,GAAI,OAAM,WAAW,GAAG,IAAI,QAAQ;AACrF,MAAI,QAAQ,MAAO,OAAM,WAAW,KAAK,IAAI,QAAQ;AACrD,MAAI,QAAQ,YAAa,OAAM,WAAW,WAAW,IAAI,QAAQ;AACjE,MAAI,QAAQ,SAAS;AACnB,UAAM,WAAW,OAAO,IAAI,QAAQ,QAAQ,SAAS,IAAI,QAAQ,QAAQ,KAAK,GAAG,IAAI;AAAA,EACvF;AACA,MAAI,QAAQ,OAAQ,OAAM,WAAW,MAAM,IAAI;AAC/C,MAAI,QAAQ,UAAW,OAAM,WAAW,SAAS,IAAI;AACrD,SAAO;AACT;AAGO,SAAS,YAAY,EAAE,IAAI,SAA2D;AAC3F,MAAI,CAAC,gBAAgB,EAAE,GAAG;AACxB,YAAQ,MAAM,iBAAiB,EAAE,wEAAwE;AACzG,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,EAAE,CAAC,WAAW,MAAM,GAAG,IAAI,CAAC,WAAW,KAAK,GAAG,UAAU,EAAE,CAAC,WAAW,MAAM,GAAG,GAAA;AACjG;AAGO,SAAS,eAAe,EAAE,IAAI,OAAoD;AACvF,SAAO,MAAM,GAAG,EAAE,IAAI,GAAG,MAAM;AACjC;AAGO,SAAS,oBAAoB,KAAwD;AAC1F,QAAM,OAAO,IAAI,KAAA;AACjB,QAAM,QAAQ,2BAA2B,KAAK,IAAI;AAClD,MAAI,EAAC,+BAAQ,IAAI,QAAO;AACxB,SAAO,EAAE,IAAI,MAAM,CAAC,EAAE,QAAQ,KAAK,MAAM,CAAC,KAAK,KAAA;AACjD;AAqBA,MAAM,uBAAuB,OAAO,IAAI,+BAA+B;AASvE,SAAS,kBAAmC;AAC1C,QAAM,SAAS;AACf,MAAI,WAAW,OAAO,oBAAoB;AAC1C,MAAI,CAAC,UAAU;AACb,mCAAe,IAAA;AACf,WAAO,oBAAoB,IAAI;AAAA,EACjC;AACA,SAAO;AACT;AAGO,SAAS,4BAA4B;AAAA,EAC1C;AAAA,EACA;AACF,GAGe;AACb,QAAM,WAAW,gBAAA;AACjB,MAAI,SAAS,IAAI,GAAG,GAAG;AAGrB,YAAQ;AAAA,MACN,8CAA8C,GAAG;AAAA,IAAA;AAAA,EAErD;AACA,WAAS,IAAI,KAAK,QAAQ;AAC1B,SAAO,MAAM;AACX,QAAI,SAAS,IAAI,GAAG,MAAM,SAAU,UAAS,OAAO,GAAG;AAAA,EACzD;AACF;AAGO,SAAS,oBAAoB,KAA8C;AAChF,SAAO,gBAAA,EAAkB,IAAI,GAAG;AAClC;;;;;;;;;;;"}

package/dist/agent-ui/contract.d.ts

@@ -0,0 +1,113 @@
+/** What the agent may do to a target, beyond pointing at it. */
+export declare const AGENT_TARGET_ACTIONS: readonly ['click', 'type', 'select', 'toggle', 'clear'];
+export type AgentTargetAction = (typeof AGENT_TARGET_ACTIONS)[number];
+export declare function isAgentTargetAction(value: unknown): value is AgentTargetAction;
+/** The attribute names of the contract. */
+export declare const AGENT_ATTR: {
+    /** The target's id, stable across renders (`investors.search`). */
+    readonly target: 'data-agent-target';
+    /** Which one of several targets sharing an id (a row's key). */
+    readonly key: 'data-agent-key';
+    /** The name the person would call it. Falls back to the element's own accessible name. */
+    readonly label: 'data-agent-label';
+    /** One line for the agent on what it is for. */
+    readonly description: 'data-agent-description';
+    /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */
+    readonly actions: 'data-agent-actions';
+    /** Present: acting on it changes or destroys something, so the person confirms every time. */
+    readonly danger: 'data-agent-danger';
+    /** Present: its value is never read and never typed. */
+    readonly sensitive: 'data-agent-sensitive';
+    /** On a container: a named part of the screen its targets belong to. */
+    readonly region: 'data-agent-region';
+    /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */
+    readonly layer: 'data-agent-ui-layer';
+};
+/** What an app says about one target. */
+export interface AgentTargetOptions {
+    /**
+     * The target's id: lowercase words joined by `.`, `-` or `_`
+     * (`investors.search`, `filters.stage`). Stable across renders and visits,
+     * since the agent names targets by it.
+     */
+    id: string;
+    /** Which one, when several targets share the id (a table row's key). */
+    key?: string;
+    /** The name a person would call it ("Search investors"). */
+    label?: string;
+    /** One line for the agent: what it is for, or what using it does. */
+    description?: string;
+    /**
+     * What the agent may do to it. Absent: what the element allows by its
+     * nature (a button is clicked, a text field typed into). An empty list: the
+     * agent may only point at it.
+     */
+    actions?: readonly AgentTargetAction[];
+    /** Acting on it changes or destroys something: the person confirms every time. */
+    danger?: boolean;
+    /** Its value is never read back to the agent and never typed by it. */
+    sensitive?: boolean;
+}
+/** The props an element takes to become a target. */
+export type AgentTargetProps = Readonly<Record<string, string>>;
+/** Whether `id` is a well-formed target id. */
+export declare function isAgentTargetId(id: string): boolean;
+/**
+ * The props that make an element an agent target. Spread them on the element
+ * (any component that passes `data-*` props to its root works):
+ *
+ * ```tsx
+ * <input {...agentTarget({ id: 'investors.search', label: 'Search investors' })} />
+ * {rows.map((row) => (
+ *   <tr key={row.id} {...agentTarget({ id: 'investors.row', key: row.id, label: row.name })} />
+ * ))}
+ * ```
+ */
+export declare function agentTarget(options: AgentTargetOptions): AgentTargetProps;
+/** The props that name a part of the screen; targets inside it are grouped under it. */
+export declare function agentRegion({ id, label }: {
+    id: string;
+    label?: string;
+}): AgentTargetProps;
+/** How the agent names one target: its id, with its key in brackets when it has one. */
+export declare function agentTargetRef({ id, key }: {
+    id: string;
+    key?: string | null;
+}): string;
+/** A reference split into id and key; `null` when it is not one. */
+export declare function parseAgentTargetRef(ref: string): {
+    id: string;
+    key: string | null;
+} | null;
+/**
+ * What a target does when ordinary input cannot drive it (a custom select, a
+ * date picker, a canvas). A handler here replaces the tool's own click or
+ * keystrokes for that action; it runs the app's own code, so validation and
+ * undo apply as for a person.
+ */
+export interface AgentTargetHandlers {
+    click?: () => void | Promise<void>;
+    /** Called with the text so far as it is typed, then once more with `done: true`. */
+    type?: (args: {
+        text: string;
+        done: boolean;
+    }) => void | Promise<void>;
+    select?: (args: {
+        option: string;
+    }) => void | Promise<void>;
+    toggle?: (args: {
+        checked: boolean | null;
+    }) => void | Promise<void>;
+    clear?: () => void | Promise<void>;
+    /** The options a `select` may be given, when the element is not a native `<select>`. */
+    options?: () => readonly string[];
+    /** The target's current value, as the agent should read it. */
+    value?: () => string | null;
+}
+/** Register a target's handlers; returns the unregister function. */
+export declare function registerAgentTargetHandlers({ ref, handlers, }: {
+    ref: string;
+    handlers: AgentTargetHandlers;
+}): () => void;
+/** The handlers registered for a target reference, if any. */
+export declare function agentTargetHandlers(ref: string): AgentTargetHandlers | undefined;

package/dist/agent-ui/contract.js

@@ -0,0 +1,104 @@
+const AGENT_TARGET_ACTIONS = ["click", "type", "select", "toggle", "clear"];
+function isAgentTargetAction(value) {
+  return AGENT_TARGET_ACTIONS.some((action) => action === value);
+}
+const AGENT_ATTR = {
+  /** The target's id, stable across renders (`investors.search`). */
+  target: "data-agent-target",
+  /** Which one of several targets sharing an id (a row's key). */
+  key: "data-agent-key",
+  /** The name the person would call it. Falls back to the element's own accessible name. */
+  label: "data-agent-label",
+  /** One line for the agent on what it is for. */
+  description: "data-agent-description",
+  /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */
+  actions: "data-agent-actions",
+  /** Present: acting on it changes or destroys something, so the person confirms every time. */
+  danger: "data-agent-danger",
+  /** Present: its value is never read and never typed. */
+  sensitive: "data-agent-sensitive",
+  /** On a container: a named part of the screen its targets belong to. */
+  region: "data-agent-region",
+  /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */
+  layer: "data-agent-ui-layer"
+};
+const TARGET_ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const NO_PROPS = {};
+function isAgentTargetId(id) {
+  return id.length <= 80 && TARGET_ID_PATTERN.test(id);
+}
+function agentTarget(options) {
+  if (!isAgentTargetId(options.id)) {
+    console.error(
+      `agentTarget: "${options.id}" is not a target id, so the element is not a target. Use lowercase words joined by ".", "-" or "_" (e.g. "investors.search").`
+    );
+    return NO_PROPS;
+  }
+  const props = { [AGENT_ATTR.target]: options.id };
+  if (options.key !== void 0 && options.key !== "") props[AGENT_ATTR.key] = options.key;
+  if (options.label) props[AGENT_ATTR.label] = options.label;
+  if (options.description) props[AGENT_ATTR.description] = options.description;
+  if (options.actions) {
+    props[AGENT_ATTR.actions] = options.actions.length > 0 ? options.actions.join(" ") : "none";
+  }
+  if (options.danger) props[AGENT_ATTR.danger] = "";
+  if (options.sensitive) props[AGENT_ATTR.sensitive] = "";
+  return props;
+}
+function agentRegion({ id, label }) {
+  if (!isAgentTargetId(id)) {
+    console.error(`agentRegion: "${id}" is not a region id (e.g. "filters"), so the element names no region.`);
+    return NO_PROPS;
+  }
+  return label ? { [AGENT_ATTR.region]: id, [AGENT_ATTR.label]: label } : { [AGENT_ATTR.region]: id };
+}
+function agentTargetRef({ id, key }) {
+  return key ? `${id}[${key}]` : id;
+}
+function parseAgentTargetRef(ref) {
+  const text = ref.trim();
+  const match = /^([^[\]]+)(?:\[(.+)\])?$/.exec(text);
+  if (!(match == null ? void 0 : match[1])) return null;
+  return { id: match[1].trim(), key: match[2] ?? null };
+}
+const HANDLER_REGISTRY_KEY = Symbol.for("athena.agentUi.targetHandlers");
+function handlerRegistry() {
+  const holder = globalThis;
+  let registry = holder[HANDLER_REGISTRY_KEY];
+  if (!registry) {
+    registry = /* @__PURE__ */ new Map();
+    holder[HANDLER_REGISTRY_KEY] = registry;
+  }
+  return registry;
+}
+function registerAgentTargetHandlers({
+  ref,
+  handlers
+}) {
+  const registry = handlerRegistry();
+  if (registry.has(ref)) {
+    console.error(
+      `useAgentTarget: two mounted targets share "${ref}" and both register handlers. Give each its own key.`
+    );
+  }
+  registry.set(ref, handlers);
+  return () => {
+    if (registry.get(ref) === handlers) registry.delete(ref);
+  };
+}
+function agentTargetHandlers(ref) {
+  return handlerRegistry().get(ref);
+}
+export {
+  AGENT_ATTR,
+  AGENT_TARGET_ACTIONS,
+  agentRegion,
+  agentTarget,
+  agentTargetHandlers,
+  agentTargetRef,
+  isAgentTargetAction,
+  isAgentTargetId,
+  parseAgentTargetRef,
+  registerAgentTargetHandlers
+};
+//# sourceMappingURL=contract.js.map

package/dist/agent-ui/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sources":["../../src/agent-ui/contract.ts"],"sourcesContent":["/*\n * Agent targets: the elements of an app the agent may see, point at and\n * operate on the screen the person has open.\n *\n * The contract is a handful of `data-agent-*` attributes on the element\n * itself. The DOM is the registry: what is in the document is what is on\n * screen, list rows and third-party components need nothing special, and a\n * plain web component can take part without React. `agentTarget()` writes the\n * attributes with types; `useAgentTarget()` also registers handlers for a\n * control that ordinary clicks and typing cannot drive.\n *\n * The app decides what the agent can touch: an element without\n * `data-agent-target` does not exist for the agent, a target lists the actions\n * it allows, and one marked dangerous or sensitive is treated as such by every\n * tool. Nothing here is a permission boundary. The tools drive the same\n * handlers a click would, as the signed-in person.\n */\n\n/** What the agent may do to a target, beyond pointing at it. */\nexport const AGENT_TARGET_ACTIONS = ['click', 'type', 'select', 'toggle', 'clear'] as const;\nexport type AgentTargetAction = (typeof AGENT_TARGET_ACTIONS)[number];\n\nexport function isAgentTargetAction(value: unknown): value is AgentTargetAction {\n  return AGENT_TARGET_ACTIONS.some((action) => action === value);\n}\n\n/** The attribute names of the contract. */\nexport const AGENT_ATTR = {\n  /** The target's id, stable across renders (`investors.search`). */\n  target: 'data-agent-target',\n  /** Which one of several targets sharing an id (a row's key). */\n  key: 'data-agent-key',\n  /** The name the person would call it. Falls back to the element's own accessible name. */\n  label: 'data-agent-label',\n  /** One line for the agent on what it is for. */\n  description: 'data-agent-description',\n  /** Space-separated actions the agent may take, or `none`. Derived from the element when absent. */\n  actions: 'data-agent-actions',\n  /** Present: acting on it changes or destroys something, so the person confirms every time. */\n  danger: 'data-agent-danger',\n  /** Present: its value is never read and never typed. */\n  sensitive: 'data-agent-sensitive',\n  /** On a container: a named part of the screen its targets belong to. */\n  region: 'data-agent-region',\n  /** Present on the overlay's own root: never a target, and input inside it is the overlay's. */\n  layer: 'data-agent-ui-layer',\n} as const;\n\n/** What an app says about one target. */\nexport interface AgentTargetOptions {\n  /**\n   * The target's id: lowercase words joined by `.`, `-` or `_`\n   * (`investors.search`, `filters.stage`). Stable across renders and visits,\n   * since the agent names targets by it.\n   */\n  id: string;\n  /** Which one, when several targets share the id (a table row's key). */\n  key?: string;\n  /** The name a person would call it (\"Search investors\"). */\n  label?: string;\n  /** One line for the agent: what it is for, or what using it does. */\n  description?: string;\n  /**\n   * What the agent may do to it. Absent: what the element allows by its\n   * nature (a button is clicked, a text field typed into). An empty list: the\n   * agent may only point at it.\n   */\n  actions?: readonly AgentTargetAction[];\n  /** Acting on it changes or destroys something: the person confirms every time. */\n  danger?: boolean;\n  /** Its value is never read back to the agent and never typed by it. */\n  sensitive?: boolean;\n}\n\n/** The props an element takes to become a target. */\nexport type AgentTargetProps = Readonly<Record<string, string>>;\n\nconst TARGET_ID_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;\nconst NO_PROPS: AgentTargetProps = {};\n\n/** Whether `id` is a well-formed target id. */\nexport function isAgentTargetId(id: string): boolean {\n  return id.length <= 80 && TARGET_ID_PATTERN.test(id);\n}\n\n/**\n * The props that make an element an agent target. Spread them on the element\n * (any component that passes `data-*` props to its root works):\n *\n * ```tsx\n * <input {...agentTarget({ id: 'investors.search', label: 'Search investors' })} />\n * {rows.map((row) => (\n *   <tr key={row.id} {...agentTarget({ id: 'investors.row', key: row.id, label: row.name })} />\n * ))}\n * ```\n */\nexport function agentTarget(options: AgentTargetOptions): AgentTargetProps {\n  if (!isAgentTargetId(options.id)) {\n    // An id built from data must never take the page down with it: the\n    // element is simply not a target, and the console says why.\n    console.error(\n      `agentTarget: \"${options.id}\" is not a target id, so the element is not a target. Use lowercase words joined by \".\", \"-\" or \"_\" (e.g. \"investors.search\").`,\n    );\n    return NO_PROPS;\n  }\n  const props: Record<string, string> = { [AGENT_ATTR.target]: options.id };\n  if (options.key !== undefined && options.key !== '') props[AGENT_ATTR.key] = options.key;\n  if (options.label) props[AGENT_ATTR.label] = options.label;\n  if (options.description) props[AGENT_ATTR.description] = options.description;\n  if (options.actions) {\n    props[AGENT_ATTR.actions] = options.actions.length > 0 ? options.actions.join(' ') : 'none';\n  }\n  if (options.danger) props[AGENT_ATTR.danger] = '';\n  if (options.sensitive) props[AGENT_ATTR.sensitive] = '';\n  return props;\n}\n\n/** The props that name a part of the screen; targets inside it are grouped under it. */\nexport function agentRegion({ id, label }: { id: string; label?: string }): AgentTargetProps {\n  if (!isAgentTargetId(id)) {\n    console.error(`agentRegion: \"${id}\" is not a region id (e.g. \"filters\"), so the element names no region.`);\n    return NO_PROPS;\n  }\n  return label ? { [AGENT_ATTR.region]: id, [AGENT_ATTR.label]: label } : { [AGENT_ATTR.region]: id };\n}\n\n/** How the agent names one target: its id, with its key in brackets when it has one. */\nexport function agentTargetRef({ id, key }: { id: string; key?: string | null }): string {\n  return key ? `${id}[${key}]` : id;\n}\n\n/** A reference split into id and key; `null` when it is not one. */\nexport function parseAgentTargetRef(ref: string): { id: string; key: string | null } | null {\n  const text = ref.trim();\n  const match = /^([^[\\]]+)(?:\\[(.+)\\])?$/.exec(text);\n  if (!match?.[1]) return null;\n  return { id: match[1].trim(), key: match[2] ?? null };\n}\n\n/**\n * What a target does when ordinary input cannot drive it (a custom select, a\n * date picker, a canvas). A handler here replaces the tool's own click or\n * keystrokes for that action; it runs the app's own code, so validation and\n * undo apply as for a person.\n */\nexport interface AgentTargetHandlers {\n  click?: () => void | Promise<void>;\n  /** Called with the text so far as it is typed, then once more with `done: true`. */\n  type?: (args: { text: string; done: boolean }) => void | Promise<void>;\n  select?: (args: { option: string }) => void | Promise<void>;\n  toggle?: (args: { checked: boolean | null }) => void | Promise<void>;\n  clear?: () => void | Promise<void>;\n  /** The options a `select` may be given, when the element is not a native `<select>`. */\n  options?: () => readonly string[];\n  /** The target's current value, as the agent should read it. */\n  value?: () => string | null;\n}\n\nconst HANDLER_REGISTRY_KEY = Symbol.for('athena.agentUi.targetHandlers');\n\ntype HandlerRegistry = Map<string, AgentTargetHandlers>;\n\n/**\n * One registry per page, on `globalThis`: a host can carry more than one copy\n * of this module (the SDK bundles its own), and a handler registered through\n * one must be found by the tools of another.\n */\nfunction handlerRegistry(): HandlerRegistry {\n  const holder = globalThis as typeof globalThis & { [HANDLER_REGISTRY_KEY]?: HandlerRegistry };\n  let registry = holder[HANDLER_REGISTRY_KEY];\n  if (!registry) {\n    registry = new Map();\n    holder[HANDLER_REGISTRY_KEY] = registry;\n  }\n  return registry;\n}\n\n/** Register a target's handlers; returns the unregister function. */\nexport function registerAgentTargetHandlers({\n  ref,\n  handlers,\n}: {\n  ref: string;\n  handlers: AgentTargetHandlers;\n}): () => void {\n  const registry = handlerRegistry();\n  if (registry.has(ref)) {\n    // Handlers are found by reference: with two mounted targets sharing one,\n    // the agent would be shown one and run the other's.\n    console.error(\n      `useAgentTarget: two mounted targets share \"${ref}\" and both register handlers. Give each its own key.`,\n    );\n  }\n  registry.set(ref, handlers);\n  return () => {\n    if (registry.get(ref) === handlers) registry.delete(ref);\n  };\n}\n\n/** The handlers registered for a target reference, if any. */\nexport function agentTargetHandlers(ref: string): AgentTargetHandlers | undefined {\n  return handlerRegistry().get(ref);\n}\n"],"names":[],"mappings":"AAmBO,MAAM,uBAAuB,CAAC,SAAS,QAAQ,UAAU,UAAU,OAAO;AAG1E,SAAS,oBAAoB,OAA4C;AAC9E,SAAO,qBAAqB,KAAK,CAAC,WAAW,WAAW,KAAK;AAC/D;AAGO,MAAM,aAAa;AAAA;AAAA,EAExB,QAAQ;AAAA;AAAA,EAER,KAAK;AAAA;AAAA,EAEL,OAAO;AAAA;AAAA,EAEP,aAAa;AAAA;AAAA,EAEb,SAAS;AAAA;AAAA,EAET,QAAQ;AAAA;AAAA,EAER,WAAW;AAAA;AAAA,EAEX,QAAQ;AAAA;AAAA,EAER,OAAO;AACT;AA+BA,MAAM,oBAAoB;AAC1B,MAAM,WAA6B,CAAA;AAG5B,SAAS,gBAAgB,IAAqB;AACnD,SAAO,GAAG,UAAU,MAAM,kBAAkB,KAAK,EAAE;AACrD;AAaO,SAAS,YAAY,SAA+C;AACzE,MAAI,CAAC,gBAAgB,QAAQ,EAAE,GAAG;AAGhC,YAAQ;AAAA,MACN,iBAAiB,QAAQ,EAAE;AAAA,IAAA;AAE7B,WAAO;AAAA,EACT;AACA,QAAM,QAAgC,EAAE,CAAC,WAAW,MAAM,GAAG,QAAQ,GAAA;AACrE,MAAI,QAAQ,QAAQ,UAAa,QAAQ,QAAQ,GAAI,OAAM,WAAW,GAAG,IAAI,QAAQ;AACrF,MAAI,QAAQ,MAAO,OAAM,WAAW,KAAK,IAAI,QAAQ;AACrD,MAAI,QAAQ,YAAa,OAAM,WAAW,WAAW,IAAI,QAAQ;AACjE,MAAI,QAAQ,SAAS;AACnB,UAAM,WAAW,OAAO,IAAI,QAAQ,QAAQ,SAAS,IAAI,QAAQ,QAAQ,KAAK,GAAG,IAAI;AAAA,EACvF;AACA,MAAI,QAAQ,OAAQ,OAAM,WAAW,MAAM,IAAI;AAC/C,MAAI,QAAQ,UAAW,OAAM,WAAW,SAAS,IAAI;AACrD,SAAO;AACT;AAGO,SAAS,YAAY,EAAE,IAAI,SAA2D;AAC3F,MAAI,CAAC,gBAAgB,EAAE,GAAG;AACxB,YAAQ,MAAM,iBAAiB,EAAE,wEAAwE;AACzG,WAAO;AAAA,EACT;AACA,SAAO,QAAQ,EAAE,CAAC,WAAW,MAAM,GAAG,IAAI,CAAC,WAAW,KAAK,GAAG,UAAU,EAAE,CAAC,WAAW,MAAM,GAAG,GAAA;AACjG;AAGO,SAAS,eAAe,EAAE,IAAI,OAAoD;AACvF,SAAO,MAAM,GAAG,EAAE,IAAI,GAAG,MAAM;AACjC;AAGO,SAAS,oBAAoB,KAAwD;AAC1F,QAAM,OAAO,IAAI,KAAA;AACjB,QAAM,QAAQ,2BAA2B,KAAK,IAAI;AAClD,MAAI,EAAC,+BAAQ,IAAI,QAAO;AACxB,SAAO,EAAE,IAAI,MAAM,CAAC,EAAE,QAAQ,KAAK,MAAM,CAAC,KAAK,KAAA;AACjD;AAqBA,MAAM,uBAAuB,OAAO,IAAI,+BAA+B;AASvE,SAAS,kBAAmC;AAC1C,QAAM,SAAS;AACf,MAAI,WAAW,OAAO,oBAAoB;AAC1C,MAAI,CAAC,UAAU;AACb,mCAAe,IAAA;AACf,WAAO,oBAAoB,IAAI;AAAA,EACjC;AACA,SAAO;AACT;AAGO,SAAS,4BAA4B;AAAA,EAC1C;AAAA,EACA;AACF,GAGe;AACb,QAAM,WAAW,gBAAA;AACjB,MAAI,SAAS,IAAI,GAAG,GAAG;AAGrB,YAAQ;AAAA,MACN,8CAA8C,GAAG;AAAA,IAAA;AAAA,EAErD;AACA,WAAS,IAAI,KAAK,QAAQ;AAC1B,SAAO,MAAM;AACX,QAAI,SAAS,IAAI,GAAG,MAAM,SAAU,UAAS,OAAO,GAAG;AAAA,EACzD;AACF;AAGO,SAAS,oBAAoB,KAA8C;AAChF,SAAO,gBAAA,EAAkB,IAAI,GAAG;AAClC;"}

package/dist/agent-ui/driver.cjs

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const pace = require("./pace.cjs");
+const screen = require("./screen.cjs");
+const tagOf = (element) => element.tagName.toUpperCase();
+function isFocusable(element) {
+  return typeof element.focus === "function";
+}
+async function revealElement({
+  element,
+  pace: pace$1,
+  signal
+}) {
+  pace.throwIfInterrupted(signal);
+  if (screen.isInViewport(element) && isFullyInViewport(element)) return;
+  element.scrollIntoView({
+    behavior: pace$1.smoothScroll ? "smooth" : "auto",
+    block: "center",
+    inline: "nearest"
+  });
+  if (pace$1.scrollSettleMaxMs <= 0) return;
+  const deadline = Date.now() + pace$1.scrollSettleMaxMs;
+  let last = element.getBoundingClientRect();
+  let still = 0;
+  while (Date.now() < deadline && still < 3) {
+    await pace.pause(50, signal);
+    const next = element.getBoundingClientRect();
+    still = Math.abs(next.top - last.top) < 0.5 && Math.abs(next.left - last.left) < 0.5 ? still + 1 : 0;
+    last = next;
+  }
+}
+function isFullyInViewport(element) {
+  const view = element.ownerDocument.defaultView;
+  if (!view) return false;
+  const rect = element.getBoundingClientRect();
+  return rect.top >= 0 && rect.left >= 0 && rect.bottom <= view.innerHeight && rect.right <= view.innerWidth;
+}
+function setNativeValue(control, value) {
+  var _a, _b, _c, _d;
+  const view = control.ownerDocument.defaultView;
+  const prototype = tagOf(control) === "TEXTAREA" ? (_a = view == null ? void 0 : view.HTMLTextAreaElement) == null ? void 0 : _a.prototype : tagOf(control) === "SELECT" ? (_b = view == null ? void 0 : view.HTMLSelectElement) == null ? void 0 : _b.prototype : (_c = view == null ? void 0 : view.HTMLInputElement) == null ? void 0 : _c.prototype;
+  const setter = prototype ? (_d = Object.getOwnPropertyDescriptor(prototype, "value")) == null ? void 0 : _d.set : void 0;
+  if (setter) setter.call(control, value);
+  else control.value = value;
+}
+function fire(element, type, init = {}) {
+  const view = element.ownerDocument.defaultView;
+  const EventClass = (view == null ? void 0 : view.Event) ?? Event;
+  const event = new EventClass(type, { bubbles: true, cancelable: true, ...init });
+  return element.dispatchEvent(event);
+}
+function fireInput(control, data) {
+  const view = control.ownerDocument.defaultView;
+  const InputEventClass = view == null ? void 0 : view.InputEvent;
+  if (InputEventClass) {
+    control.dispatchEvent(
+      new InputEventClass("input", {
+        bubbles: true,
+        cancelable: false,
+        data,
+        inputType: data === null ? "deleteContentBackward" : "insertText"
+      })
+    );
+  } else {
+    fire(control, "input");
+  }
+}
+function isEditable(control) {
+  const editable = control.getAttribute("contenteditable");
+  return editable === "" || editable === "true";
+}
+function writeValue(control, value, typed) {
+  if (isEditable(control)) control.textContent = value;
+  else setNativeValue(control, value);
+  fireInput(control, typed);
+}
+function typingSteps({ text, pace: pace2 }) {
+  const characters = Array.from(text);
+  if (!pace2.typeByCharacter || characters.length === 0) return [text];
+  const most = pace2.typeCharMs > 0 ? Math.max(1, Math.floor(pace2.typeMaxMs / pace2.typeCharMs)) : 1;
+  const size = Math.max(1, Math.ceil(characters.length / most));
+  const steps = [];
+  for (let index = size; index < characters.length; index += size) {
+    steps.push(characters.slice(0, index).join(""));
+  }
+  steps.push(text);
+  return steps;
+}
+function pressEnter(control) {
+  const view = control.ownerDocument.defaultView;
+  const KeyboardEventClass = (view == null ? void 0 : view.KeyboardEvent) ?? KeyboardEvent;
+  const init = { key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true };
+  const proceeded = control.dispatchEvent(new KeyboardEventClass("keydown", init));
+  const form = control.form;
+  if (proceeded && form && typeof form.requestSubmit === "function") form.requestSubmit();
+  control.dispatchEvent(new KeyboardEventClass("keyup", init));
+}
+function clickElement(element) {
+  const view = element.ownerDocument.defaultView;
+  const rect = element.getBoundingClientRect();
+  const point = {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    button: 0,
+    clientX: rect.left + rect.width / 2,
+    clientY: rect.top + rect.height / 2,
+    view
+  };
+  const PointerEventClass = view == null ? void 0 : view.PointerEvent;
+  const MouseEventClass = (view == null ? void 0 : view.MouseEvent) ?? MouseEvent;
+  const pointer = { ...point, pointerId: 1, pointerType: "mouse", isPrimary: true };
+  if (PointerEventClass) element.dispatchEvent(new PointerEventClass("pointerdown", { ...pointer, buttons: 1 }));
+  element.dispatchEvent(new MouseEventClass("mousedown", { ...point, buttons: 1 }));
+  if (isFocusable(element)) element.focus({ preventScroll: true });
+  if (PointerEventClass) element.dispatchEvent(new PointerEventClass("pointerup", pointer));
+  element.dispatchEvent(new MouseEventClass("mouseup", point));
+  if (typeof element.click === "function") element.click();
+  else element.dispatchEvent(new MouseEventClass("click", point));
+}
+const sameWords = (text) => text.replace(/\s+/g, " ").trim().toLowerCase();
+function matchOption(options, wanted) {
+  const text = sameWords(wanted).replace(/…$/, "").trimEnd();
+  const exact = options.filter(
+    (option) => sameWords(option.label) === text || option.value.toLowerCase() === text
+  );
+  if (exact[0]) return exact[0];
+  const starts = options.filter((option) => sameWords(option.label).startsWith(text));
+  if (starts.length === 1) return starts[0];
+  const holds = options.filter((option) => sameWords(option.label).includes(text));
+  return holds.length === 1 ? holds[0] : void 0;
+}
+function assertCanAct({
+  target,
+  action
+}) {
+  if (!target.actions.includes(action)) {
+    const allowed = target.actions.length > 0 ? target.actions.join(", ") : "nothing: it can only be pointed at";
+    throw new screen.AgentUiError(
+      `"${target.ref}" (${target.label}) does not allow "${action}". It allows: ${allowed}.`
+    );
+  }
+  if (target.disabled) {
+    throw new screen.AgentUiError(`"${target.ref}" (${target.label}) is disabled right now.`);
+  }
+}
+async function performAct({
+  target,
+  action,
+  text,
+  submit,
+  option,
+  checked,
+  pace: pace$1,
+  signal,
+  onPress,
+  beforeTouch
+}) {
+  var _a;
+  assertCanAct({ target, action });
+  const { handlers } = target;
+  const control = target.control;
+  switch (action) {
+    case "click": {
+      onPress == null ? void 0 : onPress();
+      await pace.pause(pace$1.pressMs, signal);
+      beforeTouch == null ? void 0 : beforeTouch();
+      if (handlers == null ? void 0 : handlers.click) await handlers.click();
+      else clickElement(target.element);
+      return { detail: `Clicked ${target.label}.` };
+    }
+    case "toggle": {
+      const current = target.checked;
+      const wanted = checked ?? (current === null ? null : !current);
+      if (wanted !== null && current === wanted) {
+        return { unchanged: true, detail: `${target.label} is already ${wanted ? "on" : "off"}.` };
+      }
+      if (target.role === "radio" && wanted === false) {
+        throw new screen.AgentUiError(`"${target.ref}" is a radio button: choose another option instead of turning it off.`);
+      }
+      onPress == null ? void 0 : onPress();
+      await pace.pause(pace$1.pressMs, signal);
+      beforeTouch == null ? void 0 : beforeTouch();
+      if (handlers == null ? void 0 : handlers.toggle) await handlers.toggle({ checked: wanted });
+      else clickElement(control ?? target.element);
+      return { detail: `Turned ${target.label} ${wanted === false ? "off" : "on"}.` };
+    }
+    case "select": {
+      if (typeof option !== "string" || !option.trim()) {
+        throw new screen.AgentUiError(`Give the option to choose: act_on({ target: "${target.ref}", action: "select", option: "…" }).`);
+      }
+      if (handlers == null ? void 0 : handlers.select) {
+        const known = (_a = handlers.options) == null ? void 0 : _a.call(handlers);
+        const chosen2 = known ? matchOption(known.map((label) => ({ label, value: label })), option) : void 0;
+        if (known && !chosen2) {
+          throw new screen.AgentUiError(`"${option}" is not an option of ${target.label}. Options: ${known.join(", ")}.`);
+        }
+        onPress == null ? void 0 : onPress();
+        await pace.pause(pace$1.pressMs, signal);
+        beforeTouch == null ? void 0 : beforeTouch();
+        beforeTouch == null ? void 0 : beforeTouch();
+        await handlers.select({ option: (chosen2 == null ? void 0 : chosen2.label) ?? option.trim() });
+        return { detail: `Chose ${(chosen2 == null ? void 0 : chosen2.label) ?? option.trim()} in ${target.label}.` };
+      }
+      if (!control || tagOf(control) !== "SELECT") {
+        throw new screen.AgentUiError(`"${target.ref}" has no list of options to choose from.`);
+      }
+      const select = control;
+      const options = Array.from(select.options).filter((entry) => !entry.disabled).map((entry) => ({ label: (entry.label || entry.text).trim(), value: entry.value, entry }));
+      const chosen = matchOption(options, option);
+      if (!chosen) {
+        const listed = options.slice(0, 30).map((entry) => entry.label);
+        throw new screen.AgentUiError(
+          `"${option}" is not an option of ${target.label}. Options: ${listed.join(", ")}${options.length > listed.length ? ", …" : ""}.`
+        );
+      }
+      const already = select.multiple ? chosen.entry.selected : select.value === chosen.value;
+      if (already) {
+        return { unchanged: true, detail: `${target.label} is already ${chosen.label}.` };
+      }
+      onPress == null ? void 0 : onPress();
+      await pace.pause(pace$1.pressMs, signal);
+      beforeTouch == null ? void 0 : beforeTouch();
+      if (isFocusable(control)) control.focus({ preventScroll: true });
+      if (select.multiple) chosen.entry.selected = true;
+      else setNativeValue(control, chosen.value);
+      fire(control, "input");
+      fire(control, "change");
+      return { detail: `Chose ${chosen.label} in ${target.label}.` };
+    }
+    case "clear":
+    case "type": {
+      const value = action === "clear" ? "" : text ?? "";
+      if (action === "type" && typeof text !== "string") {
+        throw new screen.AgentUiError(`Give the text to type: act_on({ target: "${target.ref}", action: "type", text: "…" }).`);
+      }
+      if (target.sensitive && action === "type") {
+        throw new screen.AgentUiError(`"${target.ref}" holds a secret: only the person types into it.`);
+      }
+      if (action === "clear" && (handlers == null ? void 0 : handlers.clear)) {
+        beforeTouch == null ? void 0 : beforeTouch();
+        await handlers.clear();
+        return { detail: `Cleared ${target.label}.` };
+      }
+      if (handlers == null ? void 0 : handlers.type) {
+        for (const step of typingSteps({ text: value, pace: pace$1 })) {
+          pace.throwIfInterrupted(signal);
+          beforeTouch == null ? void 0 : beforeTouch();
+          await handlers.type({ text: step, done: false });
+          await pace.pause(pace$1.typeCharMs, signal);
+        }
+        await handlers.type({ text: value, done: true });
+        return { detail: action === "clear" ? `Cleared ${target.label}.` : `Typed into ${target.label}.` };
+      }
+      if (!control) {
+        throw new screen.AgentUiError(`"${target.ref}" has no field to type into.`);
+      }
+      if (target.readOnly) {
+        throw new screen.AgentUiError(`"${target.ref}" (${target.label}) is read-only: nobody can type into it.`);
+      }
+      const longest = Number(control.maxLength);
+      if (Number.isFinite(longest) && longest >= 0 && Array.from(value).length > longest) {
+        throw new screen.AgentUiError(`${target.label} takes at most ${longest} characters, and this text has ${Array.from(value).length}.`);
+      }
+      beforeTouch == null ? void 0 : beforeTouch();
+      if (isFocusable(control)) control.focus({ preventScroll: true });
+      if (value === "") {
+        writeValue(control, "", null);
+      } else {
+        let previous = "";
+        for (const step of typingSteps({ text: value, pace: pace$1 })) {
+          pace.throwIfInterrupted(signal);
+          beforeTouch == null ? void 0 : beforeTouch();
+          writeValue(control, step, step.slice(previous.length));
+          previous = step;
+          await pace.pause(pace$1.typeCharMs, signal);
+        }
+      }
+      fire(control, "change");
+      if (submit) pressEnter(control);
+      return {
+        detail: action === "clear" ? `Cleared ${target.label}.` : `Typed into ${target.label}${submit ? " and pressed Enter" : ""}.`
+      };
+    }
+  }
+}
+async function waitForPageToSettle({
+  doc,
+  pace: pace$1,
+  signal
+}) {
+  var _a;
+  await pace.pause(pace$1.afterActMs, signal);
+  const Observer = (_a = doc.defaultView) == null ? void 0 : _a.MutationObserver;
+  if (pace$1.settleMaxMs <= 0 || !Observer || !doc.body) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    return;
+  }
+  let lastChange = Date.now();
+  const observer = new Observer(() => {
+    lastChange = Date.now();
+  });
+  observer.observe(doc.body, { subtree: true, childList: true, attributes: true, characterData: true });
+  const deadline = Date.now() + pace$1.settleMaxMs;
+  try {
+    while (Date.now() < deadline && Date.now() - lastChange < pace$1.settleQuietMs) {
+      await pace.pause(40, signal);
+    }
+  } finally {
+    observer.disconnect();
+  }
+}
+function watchForPerson({
+  doc,
+  isLayerEvent,
+  isPersonEvent = (event) => event.isTrusted,
+  onTakeover
+}) {
+  const types = ["pointerdown", "keydown", "wheel", "touchstart"];
+  const listener = (event) => {
+    if (!isPersonEvent(event) || isLayerEvent(event)) return;
+    onTakeover("person");
+  };
+  for (const type of types) doc.addEventListener(type, listener, { capture: true, passive: true });
+  return () => {
+    for (const type of types) doc.removeEventListener(type, listener, { capture: true });
+  };
+}
+exports.assertCanAct = assertCanAct;
+exports.performAct = performAct;
+exports.revealElement = revealElement;
+exports.typingSteps = typingSteps;
+exports.waitForPageToSettle = waitForPageToSettle;
+exports.watchForPerson = watchForPerson;
+//# sourceMappingURL=driver.cjs.map