@classic-homes/page-agent-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @classic-homes/page-agent-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic page layer for an in-app AI agent: it lets the agent
+**point at things on the host page** (outline, spotlight, a labelled ghost
+cursor, scroll into view, switch a tab, go to another page) without ever
+running model-generated selectors, HTML or code.
+
+Most apps install the framework binding instead (it draws the effects):
+`@classic-homes/page-agent-svelte`.
+
+```bash
+npm install @classic-homes/page-agent-core
+```
+
+```css
+@import '@classic-homes/page-agent-core/styles.css';
+```
+
+No runtime dependencies. ESM only (the registry, config and effect store are
+module singletons). Safe to import during SSR.
+
+## What is in here
+
+- **Registry**: `registerAgentTarget({ el, id, label, kind })` →
+  `{ update, destroy }`, `getAgentTargets`, batched `onAgentTargetsChange`,
+  and `scanAgentAttributes` for markup targets (`data-agent-id`,
+  `data-agent-label`, `data-agent-kind`, `data-agent-description`, plus the
+  host's alias attributes such as `data-tour`).
+- **Resolution**: `resolveTarget({ id } | { text, within? })`. By id
+  (registry, then markup), or by visible text (exact, then case-insensitive;
+  the smallest match, promoted to the button/tab/link carrying the same
+  text). Several matches return `ambiguous` with up to 8 candidates rather
+  than guessing.
+- **Snapshot**: `listTargets()` (max 200, `{ id, label, kind, visible,
+inViewport }`), `listTabs()` and `readPageText({ maxChars,
+ignoreSelector })`.
+- **Effects**: `highlight(ref, { style: 'outline' | 'spotlight', label,
+durationMs })`, `point(ref, { label, durationMs })`, `scrollToTarget(ref)`,
+  `clearEffects()`, `getEffects()` / `onEffectsChange()` (safe for
+  `useSyncExternalStore`) and `rectOf(effect)` for drawing. Effects expire
+  (default 8 s, max 60 s); at most 8 at once, one pointer and one spotlight.
+  `attachPageAgent()` wires Escape and `popstate` to clear; call
+  `notifyNavigated()` after SPA navigation.
+- **Executor**: `configurePageAgent({ navigate, aliasAttributes,
+ignoreSelector })` and `executePageCall(call)`, the single entry point for
+  the model's tool calls. `PAGE_TOOL_NAMES` and `PAGE_TOOLS` (plain-JSON
+  input shapes) let the agent server mirror the contract exactly.
+- **Geometry**: `unionRects`, `inflate`, `clampToViewport`, `placeLabel`,
+  `pointerTarget` for the UI layer.
+
+```ts
+import {
+  attachPageAgent,
+  configurePageAgent,
+  executePageCall,
+} from '@classic-homes/page-agent-core';
+import { goto } from '$app/navigation';
+
+configurePageAgent({ navigate: (path) => goto(path), aliasAttributes: ['data-tour'] });
+const detach = attachPageAgent();
+
+// From the chat's client-call hook:
+const result = await executePageCall({
+  tool: 'highlight',
+  input: { target: { id: 'closing-date' } },
+});
+// → { status: 'ok', output: { effectId, target: { id, label }, style, scrolled, inViewport } }
+```
+
+```html
+<section data-agent-id="closing-date" data-agent-label="Closing date">…</section>
+<div data-agent-ignore><!-- never read, never pointed at --></div>
+```
+
+## Tools
+
+| Tool               | Input                                     | Does                                                      |
+| ------------------ | ----------------------------------------- | --------------------------------------------------------- |
+| `list_targets`     | `{ kind?, limit? }`                       | Named targets and tabs on the page                        |
+| `highlight`        | `{ target, style?, label?, durationMs? }` | Outline or spotlight, scrolling into view first if needed |
+| `point`            | `{ target, label?, durationMs? }`         | Moves the ghost cursor to the target                      |
+| `scroll_to`        | `{ target }`                              | Scrolls into view (no-op if already fully visible)        |
+| `clear_highlights` | `{}`                                      | Removes every effect                                      |
+| `select_tab`       | `{ target }`                              | Clicks a `role="tab"`, `ok` once `aria-selected="true"`   |
+| `navigate`         | `{ path }`                                | Calls the host's `navigate` with a same-origin path       |
+
+`target` is `{ id }` or `{ text, within? }`. Results are `{ status, message?,
+output? }` with `status` one of `ok`, `not_found`, `ambiguous`, `hidden`,
+`refused`, `error`.
+
+## Security
+
+`executePageCall` treats its input as untrusted:
+
+- Every field is checked by hand (type, length, enum, range); unknown tools,
+  unknown keys and malformed input return `refused`. It never throws.
+- Targets are ids (compared verbatim with attribute values) or visible
+  text. No CSS selectors, HTML or code are accepted.
+- Nothing is clicked except a non-disabled `role="tab"` element.
+- `navigate` accepts only paths starting with a single `/` (no `//`,
+  backslashes, schemes, whitespace or control characters, also after
+  decoding) and goes through the host's handler; without one it is refused.
+- `ok` is reported only once the effect is in place (the effect is in the
+  store, the tab is selected, the host's navigation resolved).
+- `[data-agent-ignore]`, the host `ignoreSelector` and the layer's own UI
+  (`.chpa`) are invisible to resolution, snapshots and `readPageText`, which
+  also never reads password, hidden, card or one-time-code field values.
+  Treat page text as untrusted data on the server.
+
+## Styles
+
+`styles.css` holds the `.chpa-*` classes the bindings render: the
+click-through layer (`.chpa-layer`), outlines (`.chpa-outline` +
+`.chpa-tag`), the spotlight (`.chpa-spotlight`, dims with a spread shadow and
+keeps the page clickable), the ghost cursor (`.chpa-pointer`,
+`.chpa-pointer-icon`, `.chpa-pointer-label`), the "Agent is pointing ·
+Dismiss" chip (`.chpa-chip`, `.chpa-chip-text`, `.chpa-chip-btn`, 44 px
+target) and a live region (`.chpa-sr`). Override `--chpa-accent` (default
+`#6d28d9`) and `--chpa-z` (default `2147482000`, below the Access
+Inspector). Dark mode follows `.dark` / `[data-theme='dark']`; reduced
+motion drops the glide and pulse.
+
+## Testing
+
+jsdom has no layout, so pass `configurePageAgent({ measure })` to supply
+element boxes. The style rules (`hidden`, `display: none`, `visibility`,
+`opacity: 0`) still run for real.

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+/**
+ * Public types for `@classic-homes/page-agent-core`.
+ *
+ * Everything the model can send arrives as a {@link PageCall} and is
+ * validated by hand in `executePageCall` before any of it touches the DOM.
+ * Nothing in a call is ever used as a CSS selector, HTML or code.
+ */
+/** What a target is, so the model can tell a section from a button. */
+type AgentTargetKind = 'region' | 'tab' | 'field' | 'action';
+/** A named thing on the page the agent may point at. */
+interface AgentTarget {
+    el: Element;
+    /** Stable id the model uses, e.g. `closing-date`. */
+    id: string;
+    /** Human label, e.g. "Closing date". */
+    label: string;
+    kind: AgentTargetKind;
+    /** Optional extra hint for the model. */
+    description?: string;
+}
+/**
+ * How a call names its target: a registered/attribute id, or visible text
+ * (optionally scoped to inside another target, by id). Never a selector.
+ */
+type TargetRef = {
+    id: string;
+} | {
+    text: string;
+    within?: string;
+};
+type HighlightStyle = 'outline' | 'spotlight';
+type EffectKind = 'outline' | 'spotlight' | 'pointer';
+/** One visual effect on the page (an outline, the spotlight or the ghost cursor). */
+interface PageEffect {
+    /** Unique per effect, e.g. `chpa-3`. */
+    id: string;
+    kind: EffectKind;
+    el: Element;
+    /** Plain-text caption from the call (capped, control characters removed). */
+    label?: string;
+    /** Label of the target itself, for announcements ("Closing date"). */
+    targetLabel: string;
+    /** Target id when the target has one. */
+    targetId?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+interface HighlightOptions {
+    style?: HighlightStyle;
+    label?: string;
+    /** Default 8000, clamped to 1000…60000. */
+    durationMs?: number;
+}
+interface PointOptions {
+    label?: string;
+    /** Default 8000, clamped to 1000…60000. */
+    durationMs?: number;
+}
+interface ListTargetsInput {
+    kind?: AgentTargetKind;
+    /** Default 200 (the maximum). */
+    limit?: number;
+}
+interface HighlightInput {
+    target: TargetRef;
+    style?: HighlightStyle;
+    label?: string;
+    durationMs?: number;
+}
+interface PointInput {
+    target: TargetRef;
+    label?: string;
+    durationMs?: number;
+}
+interface ScrollToInput {
+    target: TargetRef;
+}
+interface SelectTabInput {
+    target: TargetRef;
+}
+interface NavigateInput {
+    /** Same-origin app path: starts with a single `/`, e.g. `/homes/123?tab=docs`. */
+    path: string;
+}
+/** A tool call from the model, discriminated on `tool`. */
+type PageCall = {
+    tool: 'list_targets';
+    input?: ListTargetsInput;
+} | {
+    tool: 'highlight';
+    input: HighlightInput;
+} | {
+    tool: 'point';
+    input: PointInput;
+} | {
+    tool: 'scroll_to';
+    input: ScrollToInput;
+} | {
+    tool: 'clear_highlights';
+    input?: Record<string, never>;
+} | {
+    tool: 'select_tab';
+    input: SelectTabInput;
+} | {
+    tool: 'navigate';
+    input: NavigateInput;
+};
+type PageToolName = PageCall['tool'];
+type PageCallStatus = 'ok' | 'not_found' | 'ambiguous' | 'hidden' | 'refused' | 'error';
+/** What goes back to the model. `ok` only once the effect is confirmed. */
+interface PageCallResult {
+    status: PageCallStatus;
+    /** Short plain-text explanation, safe to show the model. */
+    message?: string;
+    /** Tool-specific data, JSON-serialisable. */
+    output?: unknown;
+}
+interface TargetSummary {
+    id: string;
+    label: string;
+    kind: AgentTargetKind;
+    visible: boolean;
+    inViewport: boolean;
+}
+interface TabSummary {
+    /** Present when the tab has a registered or attribute id. */
+    id?: string;
+    label: string;
+    selected: boolean;
+    disabled: boolean;
+    visible: boolean;
+}
+interface Candidate {
+    id?: string;
+    label: string;
+}
+interface ListTargetsOutput {
+    targets: TargetSummary[];
+    tabs: TabSummary[];
+    truncated: boolean;
+}
+/** Host router hook. Resolve (or return true / nothing) once navigation finished. */
+type NavigateHandler = (path: string) => void | boolean | Promise<void | boolean>;
+/**
+ * Reads an element's layout box. Return null when it has none. The default
+ * uses `getClientRects()` / `getBoundingClientRect()`; tests (jsdom has no
+ * layout) and unusual hosts can swap it. Style checks (`display`,
+ * `visibility`, `hidden`, `inert`) always run regardless.
+ */
+type MeasureElement = (el: Element) => DOMRect | null;
+interface PageAgentConfig {
+    /** Called by the `navigate` tool. Without it, `navigate` is refused. */
+    navigate?: NavigateHandler;
+    /** Extra id attributes scanned as targets, e.g. `['data-tour']`. Must match `data-[a-z0-9-]+`. */
+    aliasAttributes?: string[];
+    /** Host CSS selector for regions the agent must never see or point at (in addition to `[data-agent-ignore]`). */
+    ignoreSelector?: string;
+    /** Layout reader; see {@link MeasureElement}. */
+    measure?: MeasureElement;
+    /** How long `select_tab` waits for `aria-selected="true"`. Default 600 ms, max 5000. */
+    tabSettleMs?: number;
+}
+interface ResolvedPageAgentConfig {
+    navigate: NavigateHandler | null;
+    aliasAttributes: string[];
+    ignoreSelector: string | null;
+    measure: MeasureElement | null;
+    tabSettleMs: number;
+}
+type ResolveResult = {
+    status: 'ok';
+    el: Element;
+    id?: string;
+    label: string;
+} | {
+    status: 'not_found';
+    message: string;
+} | {
+    status: 'hidden';
+    message: string;
+} | {
+    status: 'ambiguous';
+    message: string;
+    candidates: Candidate[];
+};
+type ResolveFailure = Exclude<ResolveResult, {
+    status: 'ok';
+}>;
+
+/**
+ * Configure the page agent once, at app start. Later calls merge into the
+ * current config (pass `navigate: undefined` to keep the handler). Alias
+ * attributes that are not plain `data-*` names are dropped.
+ */
+declare function configurePageAgent(next: PageAgentConfig): ResolvedPageAgentConfig;
+declare function getPageAgentConfig(): ResolvedPageAgentConfig;
+
+declare const EFFECT_DEFAULT_MS = 8000;
+declare const EFFECT_MIN_MS = 1000;
+declare const EFFECT_MAX_MS = 60000;
+/** Concurrent effects; the oldest is dropped beyond this. */
+declare const EFFECTS_MAX = 8;
+/** Longest caption on an effect. */
+declare const EFFECT_LABEL_MAX = 80;
+type EffectOutcome = {
+    status: 'ok';
+    effect: PageEffect;
+} | ResolveFailure;
+type ScrollOutcome = {
+    status: 'ok';
+    el: Element;
+    scrolled: boolean;
+} | ResolveFailure;
+/** Default 8 s; anything else clamped to 1…60 s. Non-numbers get the default. */
+declare function clampDuration(ms: number | undefined): number;
+/** Outline (default) or spotlight a target. Does not scroll; see {@link scrollToTarget}. */
+declare function highlight(ref: TargetRef | Element, options?: HighlightOptions): EffectOutcome;
+/** Move the ghost cursor to a target (replaces the previous pointer). */
+declare function point(ref: TargetRef | Element, options?: PointOptions): EffectOutcome;
+/**
+ * Bring a target into view, scrolling each scrollable ancestor and then the
+ * window only as far as needed. No-op when it is already fully visible.
+ * Smooth unless the user prefers reduced motion.
+ */
+declare function scrollToTarget(ref: TargetRef | Element): ScrollOutcome;
+/** Drop every effect now. */
+declare function clearEffects(): void;
+/**
+ * Current effects (stable array between changes, safe for
+ * `useSyncExternalStore`). Effects whose element left the document are
+ * dropped here, with a change notification.
+ */
+declare function getEffects(): readonly PageEffect[];
+/** Called (batched, once per microtask) whenever effects change. */
+declare function onEffectsChange(listener: () => void): () => void;
+/** Viewport rect of an effect's element, or null when it has no layout box (skip drawing). */
+declare function rectOf(effect: PageEffect): DOMRect | null;
+/** Tell the agent layer the route changed (SPA navigation): clears every effect. */
+declare function notifyNavigated(): void;
+/**
+ * Wire Escape-to-clear and clear-on-history-navigation (`popstate`). Call
+ * once from the app shell; returns the detach function. Browser-only, no-op
+ * on the server. Escape only acts while something is shown, and never stops
+ * the event, so dialogs still get it.
+ */
+declare function attachPageAgent(): () => void;
+/**
+ * Scroll `el` into view through its scroll containers. Unlike
+ * `scrollIntoView`, never scrolls `overflow: hidden` clippers (carousels,
+ * clamp boxes) and does nothing when the element is already fully in view.
+ * Returns whether anything scrolled.
+ */
+declare function scrollIntoContainers(el: Element): boolean;
+
+/**
+ * A same-origin app path, normalised, or null. Accepts only paths starting
+ * with exactly one `/`; refuses `//host`, backslashes (raw or `%5C`),
+ * encoded leading slashes, schemes (`javascript:`, `https:`), whitespace,
+ * control characters and malformed escapes.
+ */
+declare function parseAppPath(path: unknown): string | null;
+/**
+ * Run one tool call from the model. Accepts `unknown` on purpose: anything
+ * that is not `{ tool, input }` with a known tool and a valid input comes
+ * back `refused`. Never throws.
+ */
+declare function executePageCall(call: unknown): Promise<PageCallResult>;
+
+/** Longest label taken from markup or registration. */
+declare const TARGET_LABEL_MAX = 80;
+interface AgentTargetHandle {
+    update(next: Partial<Omit<AgentTarget, 'el'>>): void;
+    destroy(): void;
+}
+declare function registerAgentTarget(entry: AgentTarget): AgentTargetHandle;
+/** Registered targets whose element is still in the document. */
+declare function getAgentTargets(): AgentTarget[];
+/** Called (batched, once per microtask) whenever a registration changes. */
+declare function onAgentTargetsChange(listener: () => void): () => void;
+/**
+ * Targets marked in plain markup, for pages that cannot use the framework
+ * helpers, plus the host's alias attributes (`configurePageAgent({
+ * aliasAttributes: ['data-tour'] })`):
+ *
+ * ```html
+ * <section data-agent-id="closing" data-agent-label="Closing date" data-agent-kind="region">…</section>
+ * <button data-tour="export-button">Export</button>
+ * ```
+ *
+ * Ignored subtrees are not filtered here; resolution and snapshots do that.
+ */
+declare function scanAgentAttributes(root?: ParentNode): AgentTarget[];
+
+/** Longest id a call may use. */
+declare const TARGET_ID_MAX = 128;
+/** Longest text a call may search for. */
+declare const TARGET_TEXT_MAX = 200;
+/** Most candidates returned with `ambiguous`. */
+declare const CANDIDATES_MAX = 8;
+interface ResolveOptions {
+    /**
+     * Only `role="tab"` elements count (for `select_tab`): a text match is
+     * promoted to its enclosing tab, and matches outside any tab are dropped.
+     */
+    tabsOnly?: boolean;
+}
+/**
+ * Find the element a call means. Never guesses: several equally good text
+ * matches return `ambiguous` with a capped candidate list (labels and ids
+ * only, never markup). Ignored regions and the layer's own UI are invisible
+ * to it; elements without a layout box resolve as `hidden`.
+ */
+declare function resolveTarget(ref: TargetRef, options?: ResolveOptions): ResolveResult;
+/** Id of an element: its registration, else its markup attribute. */
+declare function targetIdOf(el: Element): string | undefined;
+
+/** Most targets / tabs `listTargets()` / `listTabs()` return. */
+declare const LIST_MAX = 200;
+/** Default and maximum `readPageText` budget. */
+declare const PAGE_TEXT_DEFAULT = 20000;
+declare const PAGE_TEXT_MAX = 100000;
+declare const TRUNCATION_MARKER = "\n[\u2026truncated]";
+/**
+ * Named targets on the page (registered and markup), ignored regions
+ * removed, at most `limit` (default and max 200). Visible ones first.
+ */
+declare function listTargets(options?: {
+    kind?: AgentTargetKind;
+    limit?: number;
+}): TargetSummary[];
+/** Every `[role="tab"]` outside ignored regions, with label and state. */
+declare function listTabs(options?: {
+    limit?: number;
+}): TabSummary[];
+interface ReadPageTextOptions {
+    /** Default 20000, max 100000. */
+    maxChars?: number;
+    /** Extra host selector to skip, on top of `[data-agent-ignore]`, `.chpa` and the configured `ignoreSelector`. */
+    ignoreSelector?: string;
+    /** Default `document.body`. */
+    root?: Element;
+}
+/**
+ * Visible page text for the model (treat it as untrusted data on the
+ * server). Skips ignored regions, the layer's own UI, script/style/template/
+ * noscript, hidden elements, and secret inputs (passwords, card fields,
+ * one-time codes, hidden inputs). Form values of other text inputs are
+ * included in brackets. Truncated with {@link TRUNCATION_MARKER}.
+ */
+declare function readPageText(options?: ReadPageTextOptions): string;
+
+declare const PAGE_TOOL_NAMES: readonly ["list_targets", "highlight", "point", "scroll_to", "clear_highlights", "select_tab", "navigate"];
+/** Longest path `navigate` accepts. */
+declare const NAVIGATE_PATH_MAX = 2048;
+/** Longest raw `label` a call may send (it is then cut to {@link EFFECT_LABEL_MAX}). */
+declare const CALL_LABEL_MAX = 200;
+/** JSON-schema-like shape, enough to generate a zod schema or a tool definition. */
+interface JsonShape {
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean';
+    description?: string;
+    properties?: Record<string, JsonShape>;
+    required?: readonly string[];
+    additionalProperties?: boolean;
+    enum?: readonly string[];
+    oneOf?: readonly JsonShape[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    default?: unknown;
+    pattern?: string;
+}
+interface PageToolDescription {
+    name: PageToolName;
+    description: string;
+    input: JsonShape;
+}
+declare const PAGE_TOOLS: readonly PageToolDescription[];
+
+/** The layer's own UI. Nothing inside it is ever a target or page text. */
+declare const LAYER_CLASS = "chpa";
+/**
+ * Per-call memo of "this element and its ancestors are not hidden by
+ * `hidden`, `display: none` or `opacity: 0`". Snapshots check up to 200
+ * targets that share most of their ancestors; without it every target
+ * re-reads the computed style of the whole chain.
+ */
+type RenderCache = Map<Element, boolean>;
+/**
+ * Rendered and perceivable: connected, no `hidden` / `display: none` /
+ * `opacity: 0` on it or an ancestor, not `visibility: hidden`, and with a
+ * layout box. The style walk runs even when `measure` is swapped, so jsdom
+ * tests exercise the same rules as browsers. Pass one `cache` for a batch of
+ * checks made against an unchanging DOM.
+ */
+declare function isRendered(el: Element, cache?: RenderCache): boolean;
+interface ViewportSize {
+    width: number;
+    height: number;
+}
+declare function viewportSize(): ViewportSize;
+declare function prefersReducedMotion(): boolean;
+
+/**
+ * Pure rect maths for drawing effects. No DOM access: callers pass the
+ * viewport size (see `viewportSize()` on the UI side).
+ */
+interface Box {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+interface Point {
+    top: number;
+    left: number;
+}
+type RectLike = Pick<DOMRect, 'top' | 'left' | 'width' | 'height'>;
+/** Smallest box covering every rect; null for none. */
+declare function unionRects(rects: readonly RectLike[]): Box | null;
+/** Grow a box by `pad` on every side (outline breathing room). */
+declare function inflate(rect: RectLike, pad: number): Box;
+/** The part of a box inside the viewport (minus `margin`); null when none is. */
+declare function clampToViewport(rect: RectLike, viewport: Size, margin?: number): Box | null;
+/** Wholly inside the viewport. */
+declare function isFullyInViewport(rect: RectLike, viewport: Size): boolean;
+/** At least partly inside the viewport. */
+declare function intersectsViewport(rect: RectLike, viewport: Size): boolean;
+interface LabelPlacement extends Point {
+    placement: 'above' | 'below';
+}
+/**
+ * Where to put a caption of `size` next to a target rect: above its
+ * top-left corner, or below when there is no room above (or `preferBelow`),
+ * then clamped into the viewport. Same rules as feedback-core's selection
+ * button, re-implemented to keep this package dependency-free.
+ */
+declare function placeLabel(rect: RectLike, size: Size, viewport: Size, opts?: {
+    gap?: number;
+    preferBelow?: boolean;
+}): LabelPlacement;
+/**
+ * Where the ghost cursor's tip should rest: just inside the target's
+ * bottom-right quarter, clamped into the viewport so it never points off
+ * screen.
+ */
+declare function pointerTarget(rect: RectLike, viewport: Size, margin?: number): Point;
+
+/** Back to a clean slate: default config, no effects. Registrations are kept (their owners destroy them). */
+declare function resetPageAgent(): void;
+
+export { type AgentTarget, type AgentTargetHandle, type AgentTargetKind, type Box, CALL_LABEL_MAX, CANDIDATES_MAX, type Candidate, EFFECTS_MAX, EFFECT_DEFAULT_MS, EFFECT_LABEL_MAX, EFFECT_MAX_MS, EFFECT_MIN_MS, type EffectKind, type EffectOutcome, type HighlightInput, type HighlightOptions, type HighlightStyle, type JsonShape, LAYER_CLASS, LIST_MAX, type LabelPlacement, type ListTargetsInput, type ListTargetsOutput, type MeasureElement, NAVIGATE_PATH_MAX, type NavigateHandler, type NavigateInput, PAGE_TEXT_DEFAULT, PAGE_TEXT_MAX, PAGE_TOOLS, PAGE_TOOL_NAMES, type PageAgentConfig, type PageCall, type PageCallResult, type PageCallStatus, type PageEffect, type PageToolDescription, type PageToolName, type Point, type PointInput, type PointOptions, type ReadPageTextOptions, type RenderCache, type ResolveFailure, type ResolveOptions, type ResolveResult, type ResolvedPageAgentConfig, type ScrollOutcome, type ScrollToInput, type SelectTabInput, type Size, TARGET_ID_MAX, TARGET_LABEL_MAX, TARGET_TEXT_MAX, TRUNCATION_MARKER, type TabSummary, type TargetRef, type TargetSummary, type ViewportSize, attachPageAgent, clampDuration, clampToViewport, clearEffects, configurePageAgent, executePageCall, getAgentTargets, getEffects, getPageAgentConfig, highlight, inflate, intersectsViewport, isFullyInViewport, isRendered, listTabs, listTargets, notifyNavigated, onAgentTargetsChange, onEffectsChange, parseAppPath, placeLabel, point, pointerTarget, prefersReducedMotion, readPageText, rectOf, registerAgentTarget, resetPageAgent, resolveTarget, scanAgentAttributes, scrollIntoContainers, scrollToTarget, targetIdOf, unionRects, viewportSize };