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

package/README.md

@@ -1,3 +1,170 @@
-# 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 `visibilityOf(effect)` / `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.
+- **Visibility**: `measureVisibility(el)` says what of a target the user can
+  see: clipped to the viewport and its scroll boxes, cut where a sticky
+  header / footer / dock covers it (hit-tested with
+  `document.elementsFromPoint`, the layer skipped), and `covered` behind a
+  modal dialog or `inert`. Bindings draw only `visible` and hide (not
+  remove) effects while it is null. The maths is the pure
+  `computeVisibility({ rect, viewport, clips, behindModal, coverAt })`.
+- **Collapsed tab rows**: `collapsedTabMenu(tab)` and the
+  `data-tablist-menu` DOM contract (below).
+- **Geometry**: `unionRects`, `inflate`, `clampToViewport`, `intersectBoxes`,
+  `placeLabel` (with optional `bounds`), `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, scrolling into view if needed     |
+| `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`.
+
+`highlight`, `point` and `scroll_to` wait for their scroll to settle, scroll
+once more if a sticky header or footer still covers the target, and measure
+`inViewport` after that. `highlight` / `point` on a target the user cannot
+see because something covers it return `hidden` with `output.reason`
+`'behind_dialog'` or `'covered'`, and show nothing.
+
+## Collapsed tab rows
+
+A tab widget that swaps its row for a drop-down when it does not fit (theme
+`Tabs`, `collapse="auto"`) keeps the `role="tab"` buttons in the DOM,
+invisible and `inert`, and marks the row while collapsed:
+
+```html
+<div role="tablist" data-tablist-menu="rec-menu">
+  <button role="tab" aria-selected="false">Documents</button>
+</div>
+<button id="rec-menu">Overview ▾</button>
+```
+
+`select_tab` then still clicks the hidden tab (browsers run a script
+`click()` on inert elements), confirms `aria-selected="true"` and answers
+with `output.shownAs: 'menu'` and a `message` that the tabs are a drop-down.
+`highlight` / `point` on such a tab go to the visible stand-in (the
+attribute's id). `listTabs()` reports them `visible` (while the stand-in is)
+with `shownAs: 'menu'`. A tab is never treated as collapsed without the
+attribute, and nothing but `role="tab"` is ever clicked.
+
+## 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 (also in a
+  collapsed row; never its drop-down or any `<select>`).
+- `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 and its target is not covered, 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). The layer stays on top so targets inside dialogs can be pointed
+at; covers are handled by drawing only the visible part (an outline cut by
+a header carries `data-cut="top"` and is left open on that side). 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. jsdom has no hit testing either: nothing
+counts as covered unless you pass `configurePageAgent({ hitTest: (x, y) =>
+element | null })`.