@classic-homes/page-agent-core 0.1.0 → 0.2.1

package/README.md

@@ -37,7 +37,8 @@ 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
+  `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.
@@ -45,8 +46,21 @@ durationMs })`, `point(ref, { label, durationMs })`, `scrollToTarget(ref)`,
 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.
+- **Visibility**: `measureVisibility(el)` says what of a target the user can
+  see: clipped to the viewport and its scroll boxes, cut where a strip
+  covers one side of it (a sticky header / footer / dock, or a menu over one
+  end: a cover spanning the target's visible part along one axis and
+  reaching past an edge on the other, viewport-wide or not; cuts combine),
+  drawn over smaller covers (hit-tested with `document.elementsFromPoint`
+  at a 3 x 3 grid plus a probe inside each edge, the layer skipped), and
+  `covered` under a cover that hides most of it, behind a modal dialog or in
+  `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 {
@@ -78,7 +92,7 @@ const result = await executePageCall({
 | ------------------ | ----------------------------------------- | --------------------------------------------------------- |
 | `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                      |
+| `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"`   |
@@ -88,6 +102,33 @@ const result = await executePageCall({
 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:
@@ -96,12 +137,14 @@ output? }` with `status` one of `ok`, `not_found`, `ambiguous`, `hidden`,
   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.
+- 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, the tab is selected, the host's navigation resolved).
+  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.
@@ -117,11 +160,16 @@ keeps the page clickable), the ghost cursor (`.chpa-pointer`,
 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
+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"`, one cut by a menu over its right end
+`data-cut="right"`, 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.
+`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 })`.

package/dist/index.d.ts

@@ -129,6 +129,12 @@ interface TabSummary {
     selected: boolean;
     disabled: boolean;
     visible: boolean;
+    /**
+     * `menu` when the tab row is collapsed into a drop-down (classic-theme
+     * `Tabs` on a narrow page): `select_tab` still works, but the user sees a
+     * menu showing the selected tab, not a row of tabs.
+     */
+    shownAs?: 'menu';
 }
 interface Candidate {
     id?: string;
@@ -148,6 +154,13 @@ type NavigateHandler = (path: string) => void | boolean | Promise<void | boolean
  * `visibility`, `hidden`, `inert`) always run regardless.
  */
 type MeasureElement = (el: Element) => DOMRect | null;
+/**
+ * Hit test: the topmost element drawn at a viewport point, or null. The
+ * default uses `document.elementsFromPoint()` and skips the layer's own UI
+ * (`.chpa`); without it (jsdom), nothing counts as covered. Tests and
+ * unusual hosts (canvas overlays, iframes) can swap it.
+ */
+type HitTestPoint = (x: number, y: number) => Element | null;
 interface PageAgentConfig {
     /** Called by the `navigate` tool. Without it, `navigate` is refused. */
     navigate?: NavigateHandler;
@@ -157,6 +170,8 @@ interface PageAgentConfig {
     ignoreSelector?: string;
     /** Layout reader; see {@link MeasureElement}. */
     measure?: MeasureElement;
+    /** Hit test used to tell whether a target is covered; see {@link HitTestPoint}. */
+    hitTest?: HitTestPoint;
     /** How long `select_tab` waits for `aria-selected="true"`. Default 600 ms, max 5000. */
     tabSettleMs?: number;
 }
@@ -165,13 +180,17 @@ interface ResolvedPageAgentConfig {
     aliasAttributes: string[];
     ignoreSelector: string | null;
     measure: MeasureElement | null;
+    hitTest: HitTestPoint | null;
     tabSettleMs: number;
 }
 type ResolveResult = {
     status: 'ok';
+    /** The element to act on (for a collapsed tab: the tab to click, or the menu to point at). */
     el: Element;
     id?: string;
     label: string;
+    /** The target is a tab in a collapsed row, shown to the user as a drop-down menu. */
+    shownAs?: 'menu';
 } | {
     status: 'not_found';
     message: string;
@@ -195,6 +214,143 @@ type ResolveFailure = Exclude<ResolveResult, {
 declare function configurePageAgent(next: PageAgentConfig): ResolvedPageAgentConfig;
 declare function getPageAgentConfig(): ResolvedPageAgentConfig;
 
+/**
+ * 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;
+    bounds?: RectLike | null;
+}): 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;
+/** Overlap of two boxes; null when they do not overlap. */
+declare function intersectBoxes(a: RectLike, b: RectLike): Box | null;
+/** Which sides of a target are cut off (by clipping, the viewport or a covering strip). */
+interface CutSides {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+}
+/**
+ * - `visible`: wholly visible.
+ * - `partial`: partly visible (`visible` is that part).
+ * - `covered`: on screen but under something else (a dialog, a sticky header).
+ * - `clipped`: hidden by a scroll box / `overflow` ancestor.
+ * - `offscreen`: outside the viewport.
+ * - `unrendered`: no layout box.
+ */
+type VisibilityState = 'visible' | 'partial' | 'covered' | 'clipped' | 'offscreen' | 'unrendered';
+interface TargetVisibility {
+    state: VisibilityState;
+    /** The target's whole layout box, in viewport px; null when unrendered. */
+    rect: Box | null;
+    /** The part the user can see; null unless `state` is `visible` or `partial`. */
+    visible: Box | null;
+    /**
+     * The area the target is shown in: the viewport, narrowed by clipping
+     * ancestors and by the strips (sticky header, footer, side dock, a menu
+     * over one end) that cut it. Captions are kept inside it. Null when there
+     * is none.
+     */
+    bounds: Box | null;
+    cut: CutSides;
+    /** With `covered`: a modal dialog / inert page, or another element on top. */
+    coveredBy?: 'modal' | 'element';
+    /**
+     * Strips that cut the target (or a header-like cover over all of it), as
+     * measured: sticky headers and footers, docks, menus over one side.
+     */
+    bands: Box[];
+}
+interface VisibilityInput {
+    /** The target's layout box; null when it has none. */
+    rect: RectLike | null;
+    viewport: Size;
+    /** Boxes of clipping ancestors (scroll boxes, `overflow: hidden`), innermost first. */
+    clips?: readonly RectLike[];
+    /** The target is behind a modal dialog or inside an `inert` subtree. */
+    behindModal?: boolean;
+    /**
+     * Hit test: the box of whatever is drawn on top of the target at this
+     * viewport point, or null when the target itself (or nothing) is.
+     */
+    coverAt?: (x: number, y: number) => RectLike | null;
+    /**
+     * Sample grid per side (default 3, so 9 points), plus one probe just
+     * inside the middle of each edge of the visible part (see
+     * {@link computeVisibility}).
+     */
+    grid?: number;
+}
+/**
+ * Where the user can actually see a target: its box intersected with the
+ * viewport and every clipping ancestor, then hit-tested at a grid of points.
+ *
+ * Occlusion rules, chosen to be robust with coarse sampling:
+ * - something that covers the whole visible part (a dialog backdrop) hides it;
+ * - a side strip, a cover that spans the visible part's full height and
+ *   reaches past its left or right edge (a side dock, a menu over the end of
+ *   a heading), or its full width and past its top or bottom edge (a sticky
+ *   header or footer), cuts the target off exactly at the cover's edge, so
+ *   the effect stops where the cover starts. The cover does not have to
+ *   span the viewport, and cuts on several sides combine;
+ * - anything else on top (a floating button over a corner, a popover over
+ *   the middle) hides the target only when it covers most of the grid
+ *   points left uncut, and is otherwise drawn over: clipping around
+ *   arbitrary shapes is not worth the wrong guesses.
+ *
+ * Sampling: a `grid` x `grid` set of points over the visible part (weighs
+ * covers for the "most of it" rule), plus a probe just inside the middle of
+ * each edge (finds side strips the grid falls short of, such as a menu over
+ * the last tenth of a wide heading: any strip of an edge's full length
+ * contains that edge's midpoint). After each cut the new edges are probed
+ * again, so a strip that only spans the part below a header is found too.
+ * Edge probes only find strips; they never count towards "most of it".
+ * 9 + 4 hit tests for an unobstructed target, 4 more per cut.
+ */
+declare function computeVisibility(input: VisibilityInput): TargetVisibility;
+
 declare const EFFECT_DEFAULT_MS = 8000;
 declare const EFFECT_MIN_MS = 1000;
 declare const EFFECT_MAX_MS = 60000;
@@ -235,6 +391,13 @@ declare function getEffects(): readonly PageEffect[];
 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;
+/**
+ * What of an effect's element the user can see right now (clipped by
+ * scroll boxes, cut under sticky headers, hidden behind dialogs). Bindings
+ * draw `visible` and hide the effect, without removing it, while it is
+ * null. See `measureVisibility`.
+ */
+declare function visibilityOf(effect: PageEffect): TargetVisibility;
 /** Tell the agent layer the route changed (SPA navigation): clears every effect. */
 declare function notifyNavigated(): void;
 /**
@@ -251,6 +414,14 @@ declare function attachPageAgent(): () => void;
  * Returns whether anything scrolled.
  */
 declare function scrollIntoContainers(el: Element): boolean;
+/**
+ * After {@link scrollIntoContainers}: when a sticky header or footer still
+ * covers part of the target (`visibility.bands`), scroll its nearest
+ * vertical scroll container (else the window) so the target sits in the
+ * middle of the uncovered area (`visibility.bounds`), or starts at its top
+ * when it is taller. Returns whether anything scrolled.
+ */
+declare function nudgeIntoBounds(el: Element, visibility: TargetVisibility): boolean;
 
 /**
  * A same-origin app path, normalised, or null. Accepts only paths starting
@@ -301,6 +472,9 @@ 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.
+     * A tab in a collapsed row (see `tabs.ts`) counts as visible while its
+     * stand-in menu is, and resolves to the tab itself (the thing to click).
+     * Without this flag such a tab resolves to the visible menu instead.
      */
     tabsOnly?: boolean;
 }
@@ -328,7 +502,11 @@ declare function listTargets(options?: {
     kind?: AgentTargetKind;
     limit?: number;
 }): TargetSummary[];
-/** Every `[role="tab"]` outside ignored regions, with label and state. */
+/**
+ * Every `[role="tab"]` outside ignored regions, with label and state. A tab
+ * in a collapsed row (see `tabs.ts`) is `visible` while its stand-in menu
+ * is, and carries `shownAs: 'menu'`.
+ */
 declare function listTabs(options?: {
     limit?: number;
 }): TabSummary[];
@@ -402,55 +580,40 @@ 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).
+ * Boxes of the ancestors that clip `el` (any `overflow` other than
+ * `visible`), innermost first, up to the first `position: fixed` one (its
+ * ancestors do not clip it). Absolutely positioned elements that escape a
+ * non-positioned clipper are over-clipped; menus and popovers are usually
+ * portalled, so this is rare.
  */
-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';
-}
+declare function clippingBoxes(el: Element): Box[];
 /**
- * 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.
+ * Inside an `inert` subtree, or not inside the topmost open modal dialog
+ * (`aria-modal="true"` or a `<dialog>` opened with `showModal()`). Modals
+ * that are not rendered (closed, `display: none`) and the layer's own UI do
+ * not count. Topmost = last in document order, which is where portalled
+ * dialogs land.
  */
-declare function placeLabel(rect: RectLike, size: Size, viewport: Size, opts?: {
-    gap?: number;
-    preferBelow?: boolean;
-}): LabelPlacement;
+declare function isBehindModal(el: Element): boolean;
 /**
- * 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.
+ * Where (and whether) the user can see `el` right now: clipped to the
+ * viewport and its scroll boxes, with covers (sticky headers, dialogs,
+ * docks) hit-tested. See {@link computeVisibility} for the rules. Style
+ * checks (`hidden`, `display: none`, …) are not repeated here; callers
+ * check {@link isRendered} first. Cheap enough per animation frame for a
+ * handful of effects (13 hit tests each, 4 more per cut side; reads only).
  */
-declare function pointerTarget(rect: RectLike, viewport: Size, margin?: number): Point;
+declare function measureVisibility(el: Element): TargetVisibility;
+
+declare const TABLIST_MENU_ATTR = "data-tablist-menu";
+/**
+ * For a tab in a collapsed tab row: the visible stand-in control, or null
+ * when the row is collapsed but its stand-in is missing, ignored or not
+ * rendered. `undefined` when the tab is not in a collapsed row.
+ */
+declare function collapsedTabMenu(tab: Element): Element | null | undefined;
 
 /** 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 };
+export { type AgentTarget, type AgentTargetHandle, type AgentTargetKind, type Box, CALL_LABEL_MAX, CANDIDATES_MAX, type Candidate, type CutSides, 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 HitTestPoint, 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, TABLIST_MENU_ATTR, TARGET_ID_MAX, TARGET_LABEL_MAX, TARGET_TEXT_MAX, TRUNCATION_MARKER, type TabSummary, type TargetRef, type TargetSummary, type TargetVisibility, type ViewportSize, type VisibilityInput, type VisibilityState, attachPageAgent, clampDuration, clampToViewport, clearEffects, clippingBoxes, collapsedTabMenu, computeVisibility, configurePageAgent, executePageCall, getAgentTargets, getEffects, getPageAgentConfig, highlight, inflate, intersectBoxes, intersectsViewport, isBehindModal, isFullyInViewport, isRendered, listTabs, listTargets, measureVisibility, notifyNavigated, nudgeIntoBounds, onAgentTargetsChange, onEffectsChange, parseAppPath, placeLabel, point, pointerTarget, prefersReducedMotion, readPageText, rectOf, registerAgentTarget, resetPageAgent, resolveTarget, scanAgentAttributes, scrollIntoContainers, scrollToTarget, targetIdOf, unionRects, viewportSize, visibilityOf };

package/dist/index.js

@@ -7,6 +7,7 @@ var defaults = () => ({
   aliasAttributes: [],
   ignoreSelector: null,
   measure: null,
+  hitTest: null,
   tabSettleMs: DEFAULT_TAB_SETTLE_MS
 });
 var config = defaults();
@@ -25,6 +26,7 @@ function configurePageAgent(next) {
     merged.ignoreSelector = validSelector(next.ignoreSelector) ? next.ignoreSelector.trim() : null;
   }
   if ("measure" in next) merged.measure = typeof next.measure === "function" ? next.measure : null;
+  if ("hitTest" in next) merged.hitTest = typeof next.hitTest === "function" ? next.hitTest : null;
   if (next.tabSettleMs !== void 0 && Number.isFinite(next.tabSettleMs)) {
     merged.tabSettleMs = Math.min(Math.max(Math.round(next.tabSettleMs), 0), MAX_TAB_SETTLE_MS);
   }
@@ -182,11 +184,20 @@ function intersectsViewport(rect, viewport) {
 function placeLabel(rect, size, viewport, opts = {}) {
   const { gap = 8, preferBelow = false } = opts;
   const box = toBox(rect);
-  const fitsAbove = box.top - size.height - gap >= 0;
+  const area = opts.bounds && intersectBoxes(opts.bounds, viewportBox(viewport)) || viewportBox(viewport);
+  const areaBottom = area.top + area.height;
+  const areaRight = area.left + area.width;
+  const fitsAbove = box.top - size.height - gap >= area.top;
   const above = !preferBelow && fitsAbove;
   let top = above ? box.top - size.height - gap : box.top + box.height + gap;
-  top = Math.min(Math.max(top, gap), Math.max(gap, viewport.height - size.height - gap));
-  const left = Math.min(Math.max(box.left, gap), Math.max(gap, viewport.width - size.width - gap));
+  top = Math.min(
+    Math.max(top, area.top + gap),
+    Math.max(area.top + gap, areaBottom - size.height - gap)
+  );
+  const left = Math.min(
+    Math.max(box.left, area.left + gap),
+    Math.max(area.left + gap, areaRight - size.width - gap)
+  );
   return { top: Math.round(top), left: Math.round(left), placement: above ? "above" : "below" };
 }
 function pointerTarget(rect, viewport, margin = 12) {
@@ -198,6 +209,171 @@ function pointerTarget(rect, viewport, margin = 12) {
     left: Math.round(Math.min(Math.max(left, margin), viewport.width - margin))
   };
 }
+var EDGE = 1;
+var MIN_VISIBLE = 4;
+var PROBE_INSET = 2;
+var MAX_TRIM_ROUNDS = 6;
+var viewportBox = (viewport) => ({
+  top: 0,
+  left: 0,
+  width: viewport.width,
+  height: viewport.height
+});
+function intersectBoxes(a, b) {
+  const top = Math.max(a.top, b.top);
+  const left = Math.max(a.left, b.left);
+  const right = Math.min(a.left + a.width, b.left + b.width);
+  const bottom = Math.min(a.top + a.height, b.top + b.height);
+  if (right <= left || bottom <= top) return null;
+  return { top, left, width: right - left, height: bottom - top };
+}
+function containsBox(outer, inner) {
+  return outer.top <= inner.top + EDGE && outer.left <= inner.left + EDGE && outer.top + outer.height >= inner.top + inner.height - EDGE && outer.left + outer.width >= inner.left + inner.width - EDGE;
+}
+var containsPoint = (box, x, y) => x >= box.left && x <= box.left + box.width && y >= box.top && y <= box.top + box.height;
+var NO_CUT = { top: false, right: false, bottom: false, left: false };
+function computeVisibility(input) {
+  if (!input.rect) {
+    return { state: "unrendered", rect: null, visible: null, bounds: null, cut: NO_CUT, bands: [] };
+  }
+  const rect = toBox(input.rect);
+  const vp = viewportBox(input.viewport);
+  let bounds = vp;
+  for (const clip of input.clips ?? []) {
+    bounds = intersectBoxes(bounds, clip);
+    if (!bounds) break;
+  }
+  const result = (state, visible2, extra = {}) => ({
+    state,
+    rect,
+    visible: visible2,
+    bounds,
+    cut: NO_CUT,
+    bands: [],
+    ...extra
+  });
+  if (!intersectBoxes(rect, vp)) return result("offscreen", null);
+  if (input.behindModal) return result("covered", null, { coveredBy: "modal" });
+  let visible = bounds ? intersectBoxes(rect, bounds) : null;
+  if (!visible || visible.width < MIN_VISIBLE || visible.height < MIN_VISIBLE) {
+    return result("clipped", null);
+  }
+  const bands = [];
+  if (input.coverAt) {
+    const n = Math.min(Math.max(Math.round(input.grid ?? 3), 1), 5);
+    const samples = [];
+    for (let row = 0; row < n; row++) {
+      for (let col = 0; col < n; col++) {
+        const x = visible.left + visible.width * (col + 0.5) / n;
+        const y = visible.top + visible.height * (row + 0.5) / n;
+        const hit = input.coverAt(x, y);
+        const cover = hit ? toBox(hit) : null;
+        samples.push({ x, y, cover: cover && containsPoint(cover, x, y) ? cover : null });
+      }
+    }
+    const covers = [];
+    const addCover = (cover) => {
+      if (cover && !covers.some((c) => sameBox(c, cover))) covers.push(cover);
+    };
+    for (const s of samples) addCover(s.cover);
+    const probed = /* @__PURE__ */ new Set();
+    const probeEdges = (box) => {
+      for (const [x, y] of edgeProbes(box)) {
+        const key = `${Math.round(x * 2)},${Math.round(y * 2)}`;
+        if (probed.has(key)) continue;
+        probed.add(key);
+        const hit = input.coverAt(x, y);
+        const cover = hit ? toBox(hit) : null;
+        addCover(cover && containsPoint(cover, x, y) ? cover : null);
+      }
+    };
+    probeEdges(visible);
+    let trimmed = true;
+    for (let round = 0; trimmed && visible && round < MAX_TRIM_ROUNDS; round++) {
+      trimmed = false;
+      for (const cover of covers) {
+        if (bands.includes(cover) || !visible || !intersectBoxes(cover, visible)) continue;
+        if (containsBox(cover, visible)) {
+          const edge = bounds && !containsBox(cover, bounds) ? trimBand(bounds, cover) : null;
+          if (edge?.visible) {
+            bounds = edge.visible;
+            bands.push(cover);
+          }
+          return result("covered", null, { coveredBy: "element", bands });
+        }
+        const band = trimBand(visible, cover);
+        if (!band) continue;
+        visible = band.visible;
+        bounds = bounds ? cutBox(bounds, band.side, band.line) : null;
+        bands.push(cover);
+        trimmed = true;
+      }
+      if (trimmed && visible && visible.width >= MIN_VISIBLE && visible.height >= MIN_VISIBLE) {
+        probeEdges(visible);
+      }
+    }
+    if (!visible || visible.width < MIN_VISIBLE || visible.height < MIN_VISIBLE) {
+      return result("covered", null, { coveredBy: "element", bands });
+    }
+    const inside = samples.filter((s) => containsPoint(visible, s.x, s.y));
+    const spotted = inside.filter((s) => s.cover && !bands.includes(s.cover)).length;
+    if (inside.length > 0 && spotted * 2 > inside.length) {
+      return result("covered", null, { coveredBy: "element", bands });
+    }
+  }
+  const cut = cutSides(rect, visible);
+  const whole = !cut.top && !cut.right && !cut.bottom && !cut.left;
+  return { state: whole ? "visible" : "partial", rect, visible, bounds, cut, bands };
+}
+function edgeProbes(box) {
+  const dx = Math.min(PROBE_INSET, box.width / 4);
+  const dy = Math.min(PROBE_INSET, box.height / 4);
+  const cx = box.left + box.width / 2;
+  const cy = box.top + box.height / 2;
+  return [
+    [cx, box.top + dy],
+    [box.left + box.width - dx, cy],
+    [cx, box.top + box.height - dy],
+    [box.left + dx, cy]
+  ];
+}
+function sameBox(a, b) {
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+}
+function cutSides(rect, visible) {
+  const half = 0.5;
+  return {
+    top: visible.top > rect.top + half,
+    left: visible.left > rect.left + half,
+    bottom: visible.top + visible.height < rect.top + rect.height - half,
+    right: visible.left + visible.width < rect.left + rect.width - half
+  };
+}
+function cutBox(box, side, line) {
+  let { top, left } = box;
+  let bottom = box.top + box.height;
+  let right = box.left + box.width;
+  if (side === "top") top = Math.max(top, line);
+  if (side === "bottom") bottom = Math.min(bottom, line);
+  if (side === "left") left = Math.max(left, line);
+  if (side === "right") right = Math.min(right, line);
+  if (right <= left || bottom <= top) return null;
+  return { top, left, width: right - left, height: bottom - top };
+}
+function trimBand(visible, cover) {
+  const vRight = visible.left + visible.width;
+  const vBottom = visible.top + visible.height;
+  const cRight = cover.left + cover.width;
+  const cBottom = cover.top + cover.height;
+  const spansX = cover.left <= visible.left + EDGE && cRight >= vRight - EDGE;
+  const spansY = cover.top <= visible.top + EDGE && cBottom >= vBottom - EDGE;
+  const trim = (side, line) => ({ visible: cutBox(visible, side, line), side, line });
+  if (spansX && cover.top <= visible.top + EDGE) return trim("top", cBottom);
+  if (spansX && cBottom >= vBottom - EDGE) return trim("bottom", cover.top);
+  if (spansY && cover.left <= visible.left + EDGE) return trim("left", cRight);
+  if (spansY && cRight >= vRight - EDGE) return trim("right", cover.left);
+  return null;
+}
 
 // src/registry.ts
 var TARGET_LABEL_MAX = 80;
@@ -302,6 +478,30 @@ function allTargets(root) {
   return out;
 }
 
+// src/tabs.ts
+var TABLIST_MENU_ATTR = "data-tablist-menu";
+function collapsedTabMenu(tab) {
+  const list = tab.closest('[role="tablist"]');
+  if (!list || !list.hasAttribute(TABLIST_MENU_ATTR)) return void 0;
+  const id2 = (list.getAttribute(TABLIST_MENU_ATTR) ?? "").trim();
+  const menu = id2 ? tab.ownerDocument.getElementById(id2) : null;
+  if (!menu || menu === list || list.contains(menu) || menu.contains(list)) return null;
+  if (isIgnored(menu) || !isRendered(menu)) return null;
+  return menu;
+}
+function collapsedStandIn(el) {
+  const tab = el.closest('[role="tab"]');
+  return tab ? collapsedTabMenu(tab) ?? null : null;
+}
+function isTabDisabled(el) {
+  if (el.getAttribute("aria-disabled") === "true" || el.hasAttribute("disabled") || el.hasAttribute("data-disabled")) {
+    return true;
+  }
+  const menu = collapsedTabMenu(el);
+  if (menu !== void 0) return menu !== null && menu.closest("[inert]") !== null;
+  return el.closest("[inert]") !== null;
+}
+
 // src/resolve.ts
 var TARGET_ID_MAX = 128;
 var TARGET_TEXT_MAX = 200;
@@ -311,7 +511,7 @@ var TEXT_LENGTH_MAX = 2e3;
 var SKIP_TAGS = /* @__PURE__ */ new Set(["script", "style", "template", "noscript", "head", "title", "meta"]);
 function resolveTarget(ref, options = {}) {
   if (!hasDom()) return { status: "not_found", message: "No page is available." };
-  if ("id" in ref) return resolveById(ref.id);
+  if ("id" in ref) return resolveById(ref.id, options);
   let scope = document.body ?? document.documentElement;
   if (ref.within !== void 0) {
     const parent = resolveById(ref.within);
@@ -325,16 +525,24 @@ function resolveTarget(ref, options = {}) {
 function targetIdOf(el) {
   return getAgentTargets().find((t) => t.el === el)?.id ?? markupId(el);
 }
-function resolveById(id2) {
+function resolveById(id2, options = {}) {
   const matches = allTargets().filter((t) => t.id === id2 && !isIgnored(t.el));
   if (matches.length === 0) {
     return { status: "not_found", message: `No target with id "${quote(id2)}".` };
   }
   const visible = matches.find((t) => isRendered(t.el));
-  if (!visible) {
-    return { status: "hidden", message: `Target "${quote(id2)}" is not visible right now.` };
+  if (visible) return { status: "ok", el: visible.el, id: visible.id, label: visible.label };
+  for (const t of matches) {
+    const shown = shownElement(t.el, options);
+    if (shown) return { status: "ok", el: shown, id: t.id, label: t.label, shownAs: "menu" };
+  }
+  return { status: "hidden", message: `Target "${quote(id2)}" is not visible right now.` };
+}
+function shownElement(el, options) {
+  if (options.tabsOnly) {
+    return el.getAttribute("role") === "tab" && collapsedTabMenu(el) ? el : null;
   }
-  return { status: "ok", el: visible.el, id: visible.id, label: visible.label };
+  return collapsedStandIn(el);
 }
 function resolveByText(text, scope, options) {
   const query = normalizeText(text);
@@ -364,7 +572,18 @@ function resolveByText(text, scope, options) {
     };
   }
   const rendered = /* @__PURE__ */ new Map();
-  const visible = matches.filter((el) => isRendered(el, rendered));
+  const shown = /* @__PURE__ */ new Map();
+  for (const el of matches) {
+    if (isRendered(el, rendered)) {
+      if (!shown.has(el)) shown.set(el, null);
+      continue;
+    }
+    const standIn = shownElement(el, options);
+    if (standIn && !shown.get(standIn)) {
+      shown.set(standIn, { tab: el.closest('[role="tab"]') ?? el });
+    }
+  }
+  const visible = Array.from(shown.keys());
   if (visible.length === 0) {
     return {
       status: "hidden",
@@ -373,8 +592,16 @@ function resolveByText(text, scope, options) {
   }
   if (visible.length === 1) {
     const el = visible[0];
-    const id2 = targetIdOf(el);
-    return { status: "ok", el, ...id2 ? { id: id2 } : {}, label: labelFor(el, id2 ?? query) };
+    const collapsed = shown.get(el);
+    const named = collapsed ? collapsed.tab : el;
+    const id2 = targetIdOf(named);
+    return {
+      status: "ok",
+      el,
+      ...id2 ? { id: id2 } : {},
+      label: labelFor(named, id2 ?? query) || query,
+      ...collapsed ? { shownAs: "menu" } : {}
+    };
   }
   return {
     status: "ambiguous",
@@ -417,6 +644,103 @@ function quote(value) {
   return cleanText(value, 60).replace(/"/g, "'");
 }
 
+// src/visibility.ts
+var CLIPS = /^(hidden|clip|auto|scroll|overlay)$/;
+var COVER_WALK_MAX = 16;
+function defaultHitTest(x, y) {
+  if (typeof document.elementsFromPoint !== "function") return null;
+  for (const el of document.elementsFromPoint(x, y)) {
+    if (!el.closest(`.${LAYER_CLASS}`)) return el;
+  }
+  return null;
+}
+function hitTest(x, y) {
+  const custom = getPageAgentConfig().hitTest;
+  try {
+    return custom ? custom(x, y) : defaultHitTest(x, y);
+  } catch {
+    return null;
+  }
+}
+var toBox2 = (r) => ({ top: r.top, left: r.left, width: r.width, height: r.height });
+function clippingBoxes(el) {
+  const view = el.ownerDocument.defaultView;
+  if (!view) return [];
+  const out = [];
+  if (view.getComputedStyle(el).position === "fixed") return out;
+  const doc = el.ownerDocument;
+  for (let node = el.parentElement; node && node !== doc.body && node !== doc.documentElement; node = node.parentElement) {
+    const style = view.getComputedStyle(node);
+    if (CLIPS.test(style.overflowX) || CLIPS.test(style.overflowY) || CLIPS.test(style.overflow)) {
+      const rect = layoutRect(node);
+      if (rect) out.push(paddingBox(node, rect));
+    }
+    if (style.position === "fixed") break;
+  }
+  return out;
+}
+function paddingBox(node, rect) {
+  if (node.clientWidth > 0 && node.clientHeight > 0) {
+    return {
+      top: rect.top + node.clientTop,
+      left: rect.left + node.clientLeft,
+      width: Math.min(node.clientWidth, rect.width),
+      height: Math.min(node.clientHeight, rect.height)
+    };
+  }
+  return toBox2(rect);
+}
+function isModalDialog(el) {
+  if (el.getAttribute("aria-modal") === "true") return true;
+  if (el.tagName === "DIALOG") {
+    try {
+      return el.matches(":modal");
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function isBehindModal(el) {
+  if (el.closest("[inert]")) return true;
+  const doc = el.ownerDocument;
+  const modals = Array.from(doc.querySelectorAll('[aria-modal="true"], dialog')).filter(
+    (m) => isModalDialog(m) && !m.closest(`.${LAYER_CLASS}`) && isRendered(m)
+  );
+  const top = modals[modals.length - 1];
+  return !!top && !top.contains(el);
+}
+function coverBox(el, x, y) {
+  const hit = hitTest(x, y);
+  if (!hit || hit === el || el.contains(hit) || hit.contains(el)) return null;
+  let box = layoutRect(hit);
+  if (!box) return null;
+  let node = hit.parentElement;
+  for (let i = 0; node && i < COVER_WALK_MAX && !node.contains(el); i++) {
+    const outer = layoutRect(node);
+    if (!outer || !encloses(outer, box)) break;
+    box = outer;
+    node = node.parentElement;
+  }
+  return box;
+}
+function encloses(outer, inner) {
+  return outer.top <= inner.top + 1 && outer.left <= inner.left + 1 && outer.bottom >= inner.bottom - 1 && outer.right >= inner.right - 1;
+}
+function measureVisibility(el) {
+  const rect = hasDom() && el.isConnected ? layoutRect(el) : null;
+  if (!rect) {
+    return computeVisibility({ rect: null, viewport: viewportSize() });
+  }
+  return computeVisibility({
+    rect,
+    viewport: viewportSize(),
+    clips: clippingBoxes(el),
+    behindModal: isBehindModal(el),
+    coverAt: (x, y) => coverBox(el, x, y)
+  });
+}
+
 // src/controller.ts
 var EFFECT_DEFAULT_MS = 8e3;
 var EFFECT_MIN_MS = 1e3;
@@ -496,12 +820,22 @@ function add(kind, resolved, label2, durationMs2) {
 function highlight(ref, options = {}) {
   const resolved = target(ref);
   if (resolved.status !== "ok") return resolved;
-  const kind = options.style === "spotlight" ? "spotlight" : "outline";
-  return { status: "ok", effect: add(kind, resolved, options.label, options.durationMs) };
+  return highlightResolved(resolved, options);
 }
 function point(ref, options = {}) {
   const resolved = target(ref);
   if (resolved.status !== "ok") return resolved;
+  return pointResolved(resolved, options);
+}
+function highlightResolved(resolved, options = {}) {
+  if (!resolved.el.isConnected)
+    return { status: "not_found", message: "Element is not available." };
+  const kind = options.style === "spotlight" ? "spotlight" : "outline";
+  return { status: "ok", effect: add(kind, resolved, options.label, options.durationMs) };
+}
+function pointResolved(resolved, options = {}) {
+  if (!resolved.el.isConnected)
+    return { status: "not_found", message: "Element is not available." };
   return { status: "ok", effect: add("pointer", resolved, options.label, options.durationMs) };
 }
 function scrollToTarget(ref) {
@@ -531,6 +865,9 @@ function onEffectsChange(listener) {
 function rectOf(effect) {
   return layoutRect(effect.el);
 }
+function visibilityOf(effect) {
+  return measureVisibility(effect.el);
+}
 function notifyNavigated() {
   clearEffects();
 }
@@ -606,6 +943,34 @@ function scrollIntoContainers(el) {
   }
   return scrolled;
 }
+function nudgeIntoBounds(el, visibility) {
+  if (typeof window === "undefined") return false;
+  const { rect, bounds } = visibility;
+  if (!rect || !bounds) return false;
+  const margin = 8;
+  const top = bounds.top + margin;
+  const room = bounds.height - margin * 2;
+  if (room <= 0) return false;
+  const bottom = rect.top + rect.height;
+  if (rect.top >= bounds.top && bottom <= bounds.top + bounds.height) return false;
+  const want = rect.height <= room ? rect.top - (top + (room - rect.height) / 2) : rect.top - top;
+  const view = el.ownerDocument.defaultView ?? window;
+  if (view.getComputedStyle(el).position === "fixed") return false;
+  const behavior = prefersReducedMotion() ? "auto" : "smooth";
+  for (let node = el.parentElement; node && node !== document.body && node !== document.documentElement; node = node.parentElement) {
+    const style = view.getComputedStyle(node);
+    if (style.position === "fixed") return false;
+    if (!isScrollable(node, style).y) continue;
+    const dy2 = clampScroll(node.scrollTop, want, node.scrollHeight - node.clientHeight);
+    if (!dy2) return false;
+    scrollBy(node, 0, dy2, behavior);
+    return true;
+  }
+  const dy = Math.round(Math.max(want, -(view.scrollY || 0)));
+  if (!dy) return false;
+  scrollBy(view, 0, dy, behavior);
+  return true;
+}
 function clampScroll(current, want, max) {
   const next = Math.min(Math.max(current + want, 0), Math.max(max, 0));
   return Math.round(next - current);
@@ -650,9 +1015,6 @@ function collectTargets(options = {}) {
   out.sort((a, b) => Number(b.visible) - Number(a.visible));
   return { targets: out.slice(0, limit), total: out.length };
 }
-function isTabDisabled(el) {
-  return el.getAttribute("aria-disabled") === "true" || el.hasAttribute("disabled") || el.hasAttribute("data-disabled") || el.closest("[inert]") !== null;
-}
 function listTabs(options = {}) {
   if (!hasDom()) return [];
   const limit = clampLimit(options.limit, LIST_MAX);
@@ -662,12 +1024,14 @@ function listTabs(options = {}) {
     if (out.length >= limit) break;
     if (isIgnored(el)) continue;
     const id2 = targetIdOf(el);
+    const menu = collapsedTabMenu(el);
     out.push({
       ...id2 ? { id: id2 } : {},
       label: labelFor(el, id2 ?? "") || "Tab",
       selected: el.getAttribute("aria-selected") === "true",
       disabled: isTabDisabled(el),
-      visible: isRendered(el, rendered)
+      visible: menu === void 0 ? isRendered(el, rendered) : menu !== null,
+      ...menu !== void 0 ? { shownAs: "menu" } : {}
     });
   }
   return out;
@@ -966,12 +1330,50 @@ function failure(result) {
 function summary(resolved) {
   return { ...resolved.id ? { id: resolved.id } : {}, label: resolved.label };
 }
-function inViewport(el, scrolled = false) {
-  if (scrolled) return true;
-  const rect = layoutRect(el);
-  return !!rect && intersectsViewport(rect, viewportSize());
-}
+var MENU_NOTE = "The tabs are shown as a drop-down menu here (the page is narrow), not as a row of tabs.";
 var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var SCROLL_SETTLE_MAX_MS = 1e3;
+var SCROLL_SETTLE_STEP_MS = 50;
+async function settleLayout(el) {
+  const key = () => {
+    const r = layoutRect(el);
+    return r ? `${Math.round(r.top)},${Math.round(r.left)}` : "";
+  };
+  let last = key();
+  let stable = 0;
+  for (let waited = 0; waited < SCROLL_SETTLE_MAX_MS; waited += SCROLL_SETTLE_STEP_MS) {
+    await wait(SCROLL_SETTLE_STEP_MS);
+    const next = key();
+    if (next === last) {
+      if (++stable >= 2) return;
+    } else {
+      stable = 0;
+      last = next;
+    }
+  }
+}
+async function reveal(el, scrolledAlready) {
+  let scrolled = scrolledAlready ?? scrollIntoContainers(el);
+  if (scrolled) await settleLayout(el);
+  let visibility = measureVisibility(el);
+  if (visibility.bands.length > 0 && nudgeIntoBounds(el, visibility)) {
+    scrolled = true;
+    await settleLayout(el);
+    visibility = measureVisibility(el);
+  }
+  return { scrolled, visibility };
+}
+var onScreen = (v) => v.state === "visible" || v.state === "partial";
+function coveredResult(visibility, label2) {
+  if (visibility.state !== "covered") return null;
+  const what = `"${label2.replace(/"/g, "'")}"`;
+  const modal = visibility.coveredBy === "modal";
+  return {
+    status: "hidden",
+    message: modal ? `${what} is behind a dialog right now, so it cannot be shown. Point at something in the dialog, or ask the user to close it.` : `${what} is covered by another part of the page (such as a header, panel or popup), so it cannot be shown right now.`,
+    output: { reason: modal ? "behind_dialog" : "covered" }
+  };
+}
 async function confirmSelected(el, settleMs) {
   const selected = () => el.isConnected && el.getAttribute("aria-selected") === "true";
   await Promise.resolve();
@@ -1005,7 +1407,7 @@ var handlers = {
     };
     return { status: "ok", output };
   },
-  highlight(raw) {
+  async highlight(raw) {
     const input = object(raw, "input", ["target", "style", "label", "durationMs"]);
     const target2 = targetRef2(input.target);
     let style = "outline";
@@ -1018,54 +1420,78 @@ var handlers = {
     const durationMs2 = optionalDuration(input.durationMs);
     const resolved = resolveTarget(target2);
     if (resolved.status !== "ok") return failure(resolved);
-    const scrolled = scrollIntoContainers(resolved.el);
-    const outcome = highlight(resolved.el, { style, label: label2, durationMs: durationMs2 });
+    const { scrolled, visibility } = await reveal(resolved.el);
+    const covered = coveredResult(visibility, resolved.label);
+    if (covered) return covered;
+    if (!isRendered(resolved.el)) {
+      return { status: "hidden", message: "That target is no longer visible." };
+    }
+    const outcome = highlightResolved(resolved, { style, label: label2, durationMs: durationMs2 });
     if (outcome.status !== "ok") return failure(outcome);
     if (!getEffects().some((e) => e.id === outcome.effect.id)) {
       return { status: "error", message: "The highlight could not be shown." };
     }
     return {
       status: "ok",
+      ...resolved.shownAs ? { message: `${MENU_NOTE} Highlighted that menu.` } : {},
       output: {
         effectId: outcome.effect.id,
         target: summary(resolved),
         style,
         scrolled,
-        inViewport: inViewport(resolved.el, scrolled)
+        inViewport: onScreen(visibility),
+        ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
       }
     };
   },
-  point(raw) {
+  async point(raw) {
     const input = object(raw, "input", ["target", "label", "durationMs"]);
     const target2 = targetRef2(input.target);
     const label2 = optionalLabel(input.label);
     const durationMs2 = optionalDuration(input.durationMs);
     const resolved = resolveTarget(target2);
     if (resolved.status !== "ok") return failure(resolved);
-    const scrolled = scrollIntoContainers(resolved.el);
-    const outcome = point(resolved.el, { label: label2, durationMs: durationMs2 });
+    const { scrolled, visibility } = await reveal(resolved.el);
+    const covered = coveredResult(visibility, resolved.label);
+    if (covered) return covered;
+    if (!isRendered(resolved.el)) {
+      return { status: "hidden", message: "That target is no longer visible." };
+    }
+    const outcome = pointResolved(resolved, { label: label2, durationMs: durationMs2 });
     if (outcome.status !== "ok") return failure(outcome);
     if (!getEffects().some((e) => e.id === outcome.effect.id)) {
       return { status: "error", message: "The pointer could not be shown." };
     }
     return {
       status: "ok",
+      ...resolved.shownAs ? { message: `${MENU_NOTE} Pointed at that menu.` } : {},
       output: {
         effectId: outcome.effect.id,
         target: summary(resolved),
         scrolled,
-        inViewport: inViewport(resolved.el, scrolled)
+        inViewport: onScreen(visibility),
+        ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
       }
     };
   },
-  scroll_to(raw) {
+  async scroll_to(raw) {
     const input = object(raw, "input", ["target"]);
     const target2 = targetRef2(input.target);
     const resolved = resolveTarget(target2);
     if (resolved.status !== "ok") return failure(resolved);
     const outcome = scrollToTarget(resolved.el);
     if (outcome.status !== "ok") return failure(outcome);
-    return { status: "ok", output: { target: summary(resolved), scrolled: outcome.scrolled } };
+    const { scrolled, visibility } = await reveal(resolved.el, outcome.scrolled);
+    return {
+      status: "ok",
+      output: {
+        target: summary(resolved),
+        scrolled,
+        inViewport: onScreen(visibility),
+        ...visibility.state === "covered" ? { covered: true } : {},
+        ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
+      }
+    };
   },
   clear_highlights(raw) {
     optionalInput(raw, []);
@@ -1085,15 +1511,30 @@ var handlers = {
     if (!(el instanceof HTMLElement))
       return { status: "refused", message: "That tab cannot be activated." };
     if (isTabDisabled(el)) return { status: "refused", message: "That tab is disabled." };
+    const menu = collapsedTabMenu(el);
+    const asMenu = menu !== void 0;
+    const extra = asMenu ? { shownAs: "menu" } : {};
     if (el.getAttribute("aria-selected") === "true") {
-      return { status: "ok", output: { target: summary(resolved), alreadySelected: true } };
+      return {
+        status: "ok",
+        ...asMenu ? { message: MENU_NOTE } : {},
+        output: { target: summary(resolved), alreadySelected: true, ...extra }
+      };
+    }
+    const shown = asMenu ? menu : isRendered(el) ? el : null;
+    if (!shown) return { status: "hidden", message: "That tab is not visible right now." };
+    if (isBehindModal(shown)) {
+      return { status: "hidden", message: "That tab is behind a dialog right now." };
     }
-    if (!isRendered(el)) return { status: "hidden", message: "That tab is not visible right now." };
     el.click();
     if (!await confirmSelected(el, getPageAgentConfig().tabSettleMs)) {
       return { status: "error", message: "The tab did not become selected." };
     }
-    return { status: "ok", output: { target: summary(resolved), alreadySelected: false } };
+    return {
+      status: "ok",
+      ...asMenu ? { message: `${MENU_NOTE} The menu now shows this tab.` } : {},
+      output: { target: summary(resolved), alreadySelected: false, ...extra }
+    };
   },
   async navigate(raw) {
     const input = object(raw, "input", ["path"]);
@@ -1133,4 +1574,4 @@ function resetPageAgent() {
   resetPageAgentConfig();
 }
 
-export { CALL_LABEL_MAX, CANDIDATES_MAX, EFFECTS_MAX, EFFECT_DEFAULT_MS, EFFECT_LABEL_MAX, EFFECT_MAX_MS, EFFECT_MIN_MS, LAYER_CLASS, LIST_MAX, NAVIGATE_PATH_MAX, PAGE_TEXT_DEFAULT, PAGE_TEXT_MAX, PAGE_TOOLS, PAGE_TOOL_NAMES, TARGET_ID_MAX, TARGET_LABEL_MAX, TARGET_TEXT_MAX, TRUNCATION_MARKER, 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 };
+export { CALL_LABEL_MAX, CANDIDATES_MAX, EFFECTS_MAX, EFFECT_DEFAULT_MS, EFFECT_LABEL_MAX, EFFECT_MAX_MS, EFFECT_MIN_MS, LAYER_CLASS, LIST_MAX, NAVIGATE_PATH_MAX, PAGE_TEXT_DEFAULT, PAGE_TEXT_MAX, PAGE_TOOLS, PAGE_TOOL_NAMES, TABLIST_MENU_ATTR, TARGET_ID_MAX, TARGET_LABEL_MAX, TARGET_TEXT_MAX, TRUNCATION_MARKER, attachPageAgent, clampDuration, clampToViewport, clearEffects, clippingBoxes, collapsedTabMenu, computeVisibility, configurePageAgent, executePageCall, getAgentTargets, getEffects, getPageAgentConfig, highlight, inflate, intersectBoxes, intersectsViewport, isBehindModal, isFullyInViewport, isRendered, listTabs, listTargets, measureVisibility, notifyNavigated, nudgeIntoBounds, onAgentTargetsChange, onEffectsChange, parseAppPath, placeLabel, point, pointerTarget, prefersReducedMotion, readPageText, rectOf, registerAgentTarget, resetPageAgent, resolveTarget, scanAgentAttributes, scrollIntoContainers, scrollToTarget, targetIdOf, unionRects, viewportSize, visibilityOf };

package/dist/styles.css

@@ -7,8 +7,9 @@
  *
  *   <div class="chpa">                              root; never a target
  *     <div class="chpa-layer" aria-hidden="true">    fixed, click-through
- *       <div class="chpa-outline" style="top/left/width/height">
- *         <span class="chpa-tag" data-placement="above|below">caption</span>
+ *       <div class="chpa-outline" style="top/left/width/height[; clip-path]"
+ *            data-cut="top right bottom left (the sides cut off, if any)">
+ *         <span class="chpa-tag" data-placement="above|below|inside">caption</span>
  *       </div>
  *       <div class="chpa-spotlight" style="top/left/width/height"></div>
  *       <div class="chpa-pointer" style="transform: translate(x, y)">
@@ -29,6 +30,11 @@
  * back to the classic-theme HSL tokens. Dark mode follows `.dark` or
  * `[data-theme='dark']` on an ancestor.
  *
+ * The layer sits above everything (so targets inside dialogs can be
+ * pointed at); the bindings draw only the part of a target the user can
+ * see, so it never paints over a sticky header, dock or dialog that covers
+ * the target (see `measureVisibility`).
+ *
  * Motion only under `prefers-reduced-motion: no-preference` (pointer glide,
  * spotlight pulse). Hover never transitions colour.
  */
@@ -116,6 +122,40 @@
   bottom: auto;
 }
 
+.chpa-tag[data-placement='inside'] {
+  top: 4px;
+  bottom: auto;
+}
+
+/*
+ * A side of the target is cut off (it continues under a sticky header, past
+ * a scroll box's edge): leave that side open, square, so the outline reads
+ * as running on under it. The binding also clips the ring there.
+ */
+.chpa-outline[data-cut~='top'] {
+  border-top-color: transparent;
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+.chpa-outline[data-cut~='bottom'] {
+  border-bottom-color: transparent;
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.chpa-outline[data-cut~='left'] {
+  border-left-color: transparent;
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+.chpa-outline[data-cut~='right'] {
+  border-right-color: transparent;
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
 /*
  * Spotlight: a clear hole over the target with the rest of the page dimmed
  * by a huge spread shadow. Purely visual; `pointer-events: none` keeps the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/page-agent-core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Framework-agnostic page layer for an in-app AI agent: named targets, safe target resolution, a page snapshot, highlight / spotlight / pointer effects and one schema-validated executor for model tool calls",
   "type": "module",
   "module": "dist/index.js",