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

package/README.md

@@ -43,7 +43,7 @@ durationMs })`, `point(ref, { label, durationMs })`, `scrollToTarget(ref)`,
   `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
+ignoreSelector, agentUiSelector, clearTheWay })` 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
@@ -57,10 +57,16 @@ ignoreSelector })` and `executePageCall(call)`, the single entry point for
   `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 })`.
+  A target hidden only by the agent's own UI (`agentUiSelector`) is
+  `coveredBy: 'agent'`; whenever that UI hides all or part of it, the
+  result carries `agentCover` and `visibleWithoutAgent`.
 - **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.
+  `placeLabel` (with optional `bounds`), `pointerTarget` for the UI layer,
+  and `findClearPosition(viewport, windowRect, keepClear, { margin, edge })`,
+  `overlaps(a, b, margin)` and `CLEAR_MARGIN` for hosts moving their chat
+  window or dock off a target (below).
 
 ```ts
 import {
@@ -105,8 +111,110 @@ output? }` with `status` one of `ok`, `not_found`, `ambiguous`, `hidden`,
 `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.
+see because something covers it return `hidden` with `output.reason` (type
+`CoveredReason`, exactly these three):
+
+| `output.reason`    | Covered by                                                                    |
+| ------------------ | ----------------------------------------------------------------------------- |
+| `behind_dialog`    | A modal dialog, or the target is in an `inert` subtree                        |
+| `covered`          | Another part of the page (a header, panel, popup) that scrolling cannot clear |
+| `covered_by_agent` | The agent's own UI (`agentUiSelector`): its chat window, dock or launcher     |
+
+`scroll_to` also returns `hidden` / `covered_by_agent` when its target ends up
+wholly under the agent's UI; under any other cover it still answers `ok` with
+`covered: true`. A target only partly under the agent's UI is `ok`, with
+`output.partlyCoveredByAgent: true`.
+
+## The agent's own UI
+
+The agent's chat window, or a panel docked to one edge that overlaps the
+page, can sit over the very thing the user asked about. Tell the core which
+elements are that UI; it then sees beneath it, says when it is in the way,
+and lets you move it:
+
+```ts
+import {
+  configurePageAgent,
+  findClearPosition,
+  overlaps,
+  viewportSize,
+  CLEAR_MARGIN,
+  type ClearTheWayHandler,
+} from '@classic-homes/page-agent-core';
+
+// Your chat: floatAt(point), setDockEdge('left' | 'right'), and its state.
+const clearTheWay: ClearTheWayHandler = ({ rect, cover }) => {
+  const vp = viewportSize();
+  if (chat.mode === 'dock') {
+    // Would the target be clear with the dock on the other edge?
+    const other = chat.edge === 'left' ? 'right' : 'left';
+    const there = {
+      top: 0,
+      height: vp.height,
+      width: chat.dockWidth,
+      left: other === 'left' ? 0 : vp.width - chat.dockWidth,
+    };
+    if (!overlaps(there, rect, CLEAR_MARGIN)) {
+      chat.setDockEdge(other);
+      return true;
+    }
+  }
+  // Floating (or no free edge: turn the dock into the floating window).
+  const size = chat.floatSize; // { width, height } of the floating window
+  const from = chat.mode === 'dock' ? { ...cover.rect, ...size } : cover.rect;
+  const to = findClearPosition(vp, from, rect); // default margin: CLEAR_MARGIN
+  if (!to) return false; // nowhere to go: the effect is cut, or covered_by_agent
+  chat.floatAt(to);
+  return true;
+};
+
+configurePageAgent({ agentUiSelector: '[data-assistant-ui]', clearTheWay });
+```
+
+- `agentUiSelector` (default none) is never read or pointed at, like
+  `ignoreSelector`. It is a separate option because neither
+  `ignoreSelector` nor `[data-agent-ignore]` means "the agent's UI":
+  `data-agent-ignore` also marks sensitive page regions (an MFA dialog), and
+  a target under one of those is plainly `covered`.
+- **Everything else sees beneath it.** `list_targets` / `listTargets()` and
+  `listTabs()` report targets under the panel as `visible` and `inViewport`
+  (they never hit-test), `readPageText` reads the page text under it (never
+  the panel's own), resolution by id or text finds targets under it, and
+  `select_tab` clicks a tab under it.
+- **Wholly hidden**: a target counts as `covered_by_agent` only when it
+  would be at least partly visible without the agent's UI; under the chat
+  window _and_ a sticky header, it is `covered`. `highlight`, `point` and
+  `scroll_to` then answer `hidden` with that reason.
+- **Partly hidden**: when the agent's UI covers part of the target (a dock
+  over the right 40% of a heading cuts it; a window over a corner is drawn
+  over), the call still answers `ok`, with the effect cut at the panel, and
+  `output.partlyCoveredByAgent: true` when that is still so at the end.
+- `clearTheWay(request)` is called at most once per `highlight`, `point`,
+  `scroll_to` or `select_tab`, whenever the agent's UI hides all or part of
+  the target, never for other covers. `request` is `{ tool, target: { id?,
+label }, rect, cover: { element, rect }, viewport }`, all in viewport px:
+  `rect` is what the user would see of the target without the agent's UI
+  (`visibleWithoutAgent`), `cover.element` the outermost `agentUiSelector`
+  element hit and `cover.rect` its box over the target. Return (or resolve
+  to) `true` when you moved something; the call then waits for the target
+  and that element to stop moving (at most 1 s) and measures once more
+  (`select_tab` clicks straight away). No answer within
+  `CLEAR_THE_WAY_TIMEOUT_MS` (1000), a throw or a rejection count as "did
+  nothing". Results after a move carry `output.clearedTheWay: true`.
+- **Keep room for the caption.** An outline's caption sits up to 34 px above
+  (or below) `rect`. `findClearPosition`'s default margin, `CLEAR_MARGIN`
+  (40), allows for it; use the same margin with `overlaps`. A ghost
+  cursor's label can reach further right (up to 240 px); pass a larger
+  margin for `point` if your window sits right of the target.
+- Effects already on screen that later end up under the agent's UI (the
+  user drags the window over an outline) are hidden or cut as before; the
+  hook is not called for them.
+- `findClearPosition(viewport, windowRect, keepClear, { margin, edge })`
+  returns the nearest top-left position for a floating window that keeps
+  `margin` px (default 40) from `keepClear` and `edge` px (default 8) from
+  the viewport edges (the current one if it already does), or null when
+  none fits. `overlaps(a, b, margin)` answers "is `a` in the way of `b`
+  plus `margin`?" for a dock at the other edge.
 
 ## Collapsed tab rows
 
@@ -145,8 +253,8 @@ attribute, and nothing but `role="tab"` is ever clicked.
 - `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
+- `[data-agent-ignore]`, the host `ignoreSelector` and `agentUiSelector`,
+  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.
 
@@ -172,4 +280,6 @@ 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 })`.
+element | null })`. A custom `hitTest` cannot look through the agent's UI,
+so points it reports under `agentUiSelector` count as uncovered when
+telling `covered_by_agent` from `covered`.

package/dist/index.d.ts

@@ -107,6 +107,13 @@ type PageCall = {
 };
 type PageToolName = PageCall['tool'];
 type PageCallStatus = 'ok' | 'not_found' | 'ambiguous' | 'hidden' | 'refused' | 'error';
+/**
+ * `output.reason` of a `hidden` result for a covered target: behind a modal
+ * dialog, under another part of the page, or under the agent's own UI (see
+ * {@link PageAgentConfig.agentUiSelector}). A closed set: agent servers
+ * mirror it as an enum.
+ */
+type CoveredReason = 'behind_dialog' | 'covered' | 'covered_by_agent';
 /** What goes back to the model. `ok` only once the effect is confirmed. */
 interface PageCallResult {
     status: PageCallStatus;
@@ -161,6 +168,51 @@ type MeasureElement = (el: Element) => DOMRect | null;
  * unusual hosts (canvas overlays, iframes) can swap it.
  */
 type HitTestPoint = (x: number, y: number) => Element | null;
+/** A box in viewport px (same shape as the geometry helpers' `Box`). */
+interface ViewportBox {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+/** What {@link ClearTheWayHandler} gets: enough to move the agent's window off a target. */
+interface ClearTheWayRequest {
+    /** The tool whose target is covered (for `select_tab`: the tab, or its drop-down). */
+    tool: 'highlight' | 'point' | 'scroll_to' | 'select_tab';
+    /** The target, as the result would name it. */
+    target: {
+        id?: string;
+        label: string;
+    };
+    /**
+     * The part of the target the user would see without the agent's UI in
+     * the way (`visibleWithoutAgent`), in viewport px. Move the window off
+     * this, keeping room for the effect's caption: an outline's caption sits
+     * up to 34 px above or below it, which `findClearPosition`'s default
+     * margin (`CLEAR_MARGIN`, 40) allows for.
+     */
+    rect: ViewportBox;
+    /** The agent's UI over the target. */
+    cover: {
+        /** The outermost element matching `agentUiSelector` that was hit, when known. */
+        element: Element | null;
+        /** Box of the agent's UI over the target, in viewport px. */
+        rect: ViewportBox;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Host hook called when the agent's own UI covers all or part of a
+ * `highlight`, `point`, `scroll_to` or `select_tab` target (a docked panel
+ * over one end of a heading counts). Move (or collapse) that UI, then return
+ * (or resolve to) `true` if you did something; anything else means "did
+ * nothing". Called at most once per call, given {@link CLEAR_THE_WAY_TIMEOUT_MS}
+ * to answer; errors count as "did nothing".
+ */
+type ClearTheWayHandler = (request: ClearTheWayRequest) => boolean | void | Promise<boolean | void>;
 interface PageAgentConfig {
     /** Called by the `navigate` tool. Without it, `navigate` is refused. */
     navigate?: NavigateHandler;
@@ -168,6 +220,16 @@ interface PageAgentConfig {
     aliasAttributes?: string[];
     /** Host CSS selector for regions the agent must never see or point at (in addition to `[data-agent-ignore]`). */
     ignoreSelector?: string;
+    /**
+     * Host CSS selector for the agent's own UI: its floating chat window,
+     * dock and launcher. Never read or pointed at (like `ignoreSelector`),
+     * and a target hidden under it is reported as `covered_by_agent` instead
+     * of `covered`. Not `[data-agent-ignore]`: that also marks sensitive page
+     * regions (an MFA dialog), which are not the agent's UI.
+     */
+    agentUiSelector?: string;
+    /** Called when a target is covered by the agent's own UI; see {@link ClearTheWayHandler}. */
+    clearTheWay?: ClearTheWayHandler;
     /** Layout reader; see {@link MeasureElement}. */
     measure?: MeasureElement;
     /** Hit test used to tell whether a target is covered; see {@link HitTestPoint}. */
@@ -179,6 +241,8 @@ interface ResolvedPageAgentConfig {
     navigate: NavigateHandler | null;
     aliasAttributes: string[];
     ignoreSelector: string | null;
+    agentUiSelector: string | null;
+    clearTheWay: ClearTheWayHandler | null;
     measure: MeasureElement | null;
     hitTest: HitTestPoint | null;
     tabSettleMs: number;
@@ -295,8 +359,25 @@ interface TargetVisibility {
      */
     bounds: Box | null;
     cut: CutSides;
-    /** With `covered`: a modal dialog / inert page, or another element on top. */
-    coveredBy?: 'modal' | 'element';
+    /**
+     * With `covered`: a modal dialog / inert page, another element on top, or
+     * the agent's own UI (see {@link VisibilityInput.coverAt}): the target
+     * would be at least partly visible if the agent's UI were not there.
+     */
+    coveredBy?: 'modal' | 'element' | 'agent';
+    /**
+     * Set whenever the agent's own UI hides some of the target: all of it
+     * (`state: 'covered'`, `coveredBy: 'agent'`) or part of it (`visible` /
+     * `partial`: cut at a docked panel, or a window drawn over a corner).
+     * The box of the agent's UI over the target (the union of every agent-UI
+     * cover that overlaps it), in viewport px.
+     */
+    agentCover?: Box;
+    /**
+     * Set with `agentCover`: the part of the target the user would see
+     * without the agent's UI in the way. Keep this clear to show all of it.
+     */
+    visibleWithoutAgent?: Box;
     /**
      * 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.
@@ -313,9 +394,19 @@ interface VisibilityInput {
     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.
+     * viewport point, or null when the target itself (or nothing) is. Flag a
+     * cover that is the agent's own UI (its chat window, dock, launcher) with
+     * `agent: true`; a target covered only because of such covers is
+     * reported as `coveredBy: 'agent'`.
+     */
+    coverAt?: (x: number, y: number) => CoverHit | null;
+    /**
+     * Hit test that looks through the agent's UI: what is on top of the
+     * target at this point once agent-UI covers are skipped. Used only to
+     * decide between `coveredBy: 'agent'` and `'element'`. Without it, a
+     * point under the agent's UI counts as uncovered there.
      */
-    coverAt?: (x: number, y: number) => RectLike | null;
+    coverBelowAgentAt?: (x: number, y: number) => CoverHit | 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
@@ -323,6 +414,10 @@ interface VisibilityInput {
      */
     grid?: number;
 }
+/** A cover box from a hit test; `agent` marks the agent's own UI. */
+type CoverHit = RectLike & {
+    agent?: boolean;
+};
 /**
  * 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.
@@ -348,8 +443,54 @@ interface VisibilityInput {
  * 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.
+ *
+ * Agent UI: when the target comes out `covered` and some covers were
+ * flagged `agent`, it is measured again looking through them
+ * (`coverBelowAgentAt`). If it would then be at least partly visible, the
+ * result is `coveredBy: 'agent'` with `agentCover` and
+ * `visibleWithoutAgent`; otherwise it stays `'element'` (something else
+ * covers it too, so moving the agent's UI would not help). A visible or
+ * partial target is drawn exactly as before (an agent panel over one side
+ * cuts it like any other strip), but when agent-UI covers overlap what it
+ * would show without them, it also gets `agentCover` and
+ * `visibleWithoutAgent`, so a host can move its UI off it.
  */
 declare function computeVisibility(input: VisibilityInput): TargetVisibility;
+/**
+ * Default gap {@link findClearPosition} keeps around the rect to keep
+ * clear: an outline's 4 px padding plus its 8 px gap and 22 px caption above
+ * or below the target, rounded up.
+ */
+declare const CLEAR_MARGIN = 40;
+/**
+ * Whether two boxes overlap once `b` is grown by `margin` px on every side
+ * (touching edges do not count). For a docked panel: "would the target be
+ * clear if the panel were pinned to the other edge?" is
+ * `!overlaps(panelBoxAtOtherEdge, request.rect, CLEAR_MARGIN)`.
+ */
+declare function overlaps(a: RectLike, b: RectLike, margin?: number): boolean;
+interface ClearPositionOptions {
+    /**
+     * Gap kept between the window and `keepClear`, in px. Default
+     * {@link CLEAR_MARGIN} (40): room for an outline's padding and its
+     * caption, drawn just above (or below) the target.
+     */
+    margin?: number;
+    /** Gap kept between the window and the viewport edges, in px. Default 8. */
+    edge?: number;
+}
+/**
+ * Where to move a floating window (`windowRect`: the agent's chat window,
+ * say) so it no
+ * longer overlaps `keepClear` (the part of a target the user should see):
+ * the nearest top-left position, by straight-line distance from where the
+ * window is now, that keeps `margin` px between the two and `edge` px from
+ * the viewport edges. Returns the current position when the window already
+ * keeps clear (and fits; one that sticks out is moved back in), or null when no position fits (the window is too
+ * big for the room left beside, above and below `keepClear`). Pure; all
+ * boxes in viewport px.
+ */
+declare function findClearPosition(viewport: Size, windowRect: RectLike, keepClear: RectLike, opts?: ClearPositionOptions): Point | null;
 
 declare const EFFECT_DEFAULT_MS = 8000;
 declare const EFFECT_MIN_MS = 1000;
@@ -430,6 +571,8 @@ declare function nudgeIntoBounds(el: Element, visibility: TargetVisibility): boo
  * control characters and malformed escapes.
  */
 declare function parseAppPath(path: unknown): string | null;
+/** How long `clearTheWay` has to answer before it counts as "did nothing". */
+declare const CLEAR_THE_WAY_TIMEOUT_MS = 1000;
 /**
  * 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
@@ -616,4 +759,4 @@ 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, 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 };
+export { type AgentTarget, type AgentTargetHandle, type AgentTargetKind, type Box, CALL_LABEL_MAX, CANDIDATES_MAX, CLEAR_MARGIN, CLEAR_THE_WAY_TIMEOUT_MS, type Candidate, type ClearPositionOptions, type ClearTheWayHandler, type ClearTheWayRequest, type CoverHit, type CoveredReason, 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 ViewportBox, type ViewportSize, type VisibilityInput, type VisibilityState, attachPageAgent, clampDuration, clampToViewport, clearEffects, clippingBoxes, collapsedTabMenu, computeVisibility, configurePageAgent, executePageCall, findClearPosition, getAgentTargets, getEffects, getPageAgentConfig, highlight, inflate, intersectBoxes, intersectsViewport, isBehindModal, isFullyInViewport, isRendered, listTabs, listTargets, measureVisibility, notifyNavigated, nudgeIntoBounds, onAgentTargetsChange, onEffectsChange, overlaps, parseAppPath, placeLabel, point, pointerTarget, prefersReducedMotion, readPageText, rectOf, registerAgentTarget, resetPageAgent, resolveTarget, scanAgentAttributes, scrollIntoContainers, scrollToTarget, targetIdOf, unionRects, viewportSize, visibilityOf };

package/dist/index.js

@@ -6,6 +6,8 @@ var defaults = () => ({
   navigate: null,
   aliasAttributes: [],
   ignoreSelector: null,
+  agentUiSelector: null,
+  clearTheWay: null,
   measure: null,
   hitTest: null,
   tabSettleMs: DEFAULT_TAB_SETTLE_MS
@@ -25,6 +27,11 @@ function configurePageAgent(next) {
   if ("ignoreSelector" in next) {
     merged.ignoreSelector = validSelector(next.ignoreSelector) ? next.ignoreSelector.trim() : null;
   }
+  if ("agentUiSelector" in next) {
+    merged.agentUiSelector = validSelector(next.agentUiSelector) ? next.agentUiSelector.trim() : null;
+  }
+  if ("clearTheWay" in next)
+    merged.clearTheWay = typeof next.clearTheWay === "function" ? next.clearTheWay : 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)) {
@@ -56,15 +63,22 @@ var BUILT_IN_IGNORE = `[data-agent-ignore],.${LAYER_CLASS}`;
 var hasDom = () => typeof document !== "undefined";
 function isIgnored(el, extraSelector) {
   if (el.closest(BUILT_IN_IGNORE)) return true;
-  const host = getPageAgentConfig().ignoreSelector;
-  return safeClosest(el, host) || safeClosest(el, extraSelector ?? null);
+  const { ignoreSelector, agentUiSelector } = getPageAgentConfig();
+  return safeClosest(el, ignoreSelector) !== null || safeClosest(el, agentUiSelector) !== null || safeClosest(el, extraSelector ?? null) !== null;
+}
+function agentUiRoot(el) {
+  const selector = getPageAgentConfig().agentUiSelector;
+  let root = null;
+  for (let node = safeClosest(el, selector); node; node = safeClosest(node.parentElement, selector))
+    root = node;
+  return root;
 }
 function safeClosest(el, selector) {
-  if (!selector) return false;
+  if (!selector || !el) return null;
   try {
-    return el.closest(selector) !== null;
+    return el.closest(selector);
   } catch {
-    return false;
+    return null;
   }
 }
 function defaultMeasure(el) {
@@ -233,6 +247,38 @@ function containsBox(outer, inner) {
 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) {
+  const coverAt = input.coverAt;
+  if (!coverAt) return measureOnce(input, void 0);
+  const agentBoxes = [];
+  const first = measureOnce(input, (x, y) => {
+    const hit = coverAt(x, y);
+    if (hit?.agent) {
+      const box = toBox(hit);
+      if (containsPoint(box, x, y) && !agentBoxes.some((b) => sameBox(b, box)))
+        agentBoxes.push(box);
+    }
+    return hit;
+  });
+  const fullyCovered = first.state === "covered" && first.coveredBy === "element";
+  const onScreen2 = first.state === "visible" || first.state === "partial";
+  if (agentBoxes.length === 0 || !fullyCovered && !onScreen2) return first;
+  const below = input.coverBelowAgentAt ?? coverAt;
+  const without = measureOnce(input, (x, y) => {
+    const hit = below(x, y);
+    return hit && !hit.agent ? hit : null;
+  });
+  const clear = without.visible;
+  if (!clear) return first;
+  const over = agentBoxes.filter((b) => intersectBoxes(b, clear));
+  if (onScreen2 && over.length === 0) return first;
+  return {
+    ...first,
+    ...fullyCovered ? { coveredBy: "agent" } : {},
+    agentCover: unionRects(over.length ? over : agentBoxes),
+    visibleWithoutAgent: clear
+  };
+}
+function measureOnce(input, coverAt) {
   if (!input.rect) {
     return { state: "unrendered", rect: null, visible: null, bounds: null, cut: NO_CUT, bands: [] };
   }
@@ -259,14 +305,14 @@ function computeVisibility(input) {
     return result("clipped", null);
   }
   const bands = [];
-  if (input.coverAt) {
+  if (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 hit = coverAt(x, y);
         const cover = hit ? toBox(hit) : null;
         samples.push({ x, y, cover: cover && containsPoint(cover, x, y) ? cover : null });
       }
@@ -282,7 +328,7 @@ function computeVisibility(input) {
         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 hit = coverAt(x, y);
         const cover = hit ? toBox(hit) : null;
         addCover(cover && containsPoint(cover, x, y) ? cover : null);
       }
@@ -374,6 +420,41 @@ function trimBand(visible, cover) {
   if (spansY && cRight >= vRight - EDGE) return trim("right", cover.left);
   return null;
 }
+var CLEAR_MARGIN = 40;
+function overlaps(a, b, margin = 0) {
+  return intersectBoxes(a, inflate(b, Math.max(0, margin))) !== null;
+}
+function findClearPosition(viewport, windowRect, keepClear, opts = {}) {
+  const margin = Math.max(0, opts.margin ?? CLEAR_MARGIN);
+  const edge = Math.max(0, opts.edge ?? 8);
+  const w = windowRect.width;
+  const h = windowRect.height;
+  const minX = edge;
+  const minY = edge;
+  const maxX = viewport.width - edge - w;
+  const maxY = viewport.height - edge - h;
+  if (maxX < minX || maxY < minY) return null;
+  const keep = inflate(keepClear, margin);
+  const clampX = (x) => Math.min(Math.max(x, minX), maxX);
+  const clampY = (y) => Math.min(Math.max(y, minY), maxY);
+  const overlaps2 = (left, top) => intersectBoxes({ left, top, width: w, height: h }, keep) !== null;
+  const here = { left: windowRect.left, top: windowRect.top };
+  const keepRight = keep.left + keep.width;
+  const keepBottom = keep.top + keep.height;
+  const candidates = [
+    { left: clampX(here.left), top: clampY(here.top) },
+    { left: keep.left - w, top: clampY(here.top) },
+    { left: keepRight, top: clampY(here.top) },
+    { left: clampX(here.left), top: keep.top - h },
+    { left: clampX(here.left), top: keepBottom }
+  ].filter(
+    (c) => c.left >= minX && c.left <= maxX && c.top >= minY && c.top <= maxY && !overlaps2(c.left, c.top)
+  );
+  if (candidates.length === 0) return null;
+  const distance = (c) => Math.hypot(c.left - here.left, c.top - here.top);
+  const best = candidates.reduce((a, b) => distance(b) < distance(a) ? b : a);
+  return { top: Math.round(best.top), left: Math.round(best.left) };
+}
 
 // src/registry.ts
 var TARGET_LABEL_MAX = 80;
@@ -647,10 +728,12 @@ function quote(value) {
 // src/visibility.ts
 var CLIPS = /^(hidden|clip|auto|scroll|overlay)$/;
 var COVER_WALK_MAX = 16;
-function defaultHitTest(x, y) {
+function defaultHitTest(x, y, skipAgentUi = false) {
   if (typeof document.elementsFromPoint !== "function") return null;
   for (const el of document.elementsFromPoint(x, y)) {
-    if (!el.closest(`.${LAYER_CLASS}`)) return el;
+    if (el.closest(`.${LAYER_CLASS}`)) continue;
+    if (skipAgentUi && agentUiRoot(el)) continue;
+    return el;
   }
   return null;
 }
@@ -662,6 +745,13 @@ function hitTest(x, y) {
     return null;
   }
 }
+function hitTestBelowAgentUi(x, y) {
+  try {
+    return defaultHitTest(x, y, true);
+  } 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;
@@ -710,35 +800,56 @@ function isBehindModal(el) {
   const top = modals[modals.length - 1];
   return !!top && !top.contains(el);
 }
-function coverBox(el, x, y) {
-  const hit = hitTest(x, y);
+function coverBox(el, hit, onAgent) {
   if (!hit || hit === el || el.contains(hit) || hit.contains(el)) return null;
   let box = layoutRect(hit);
   if (!box) return null;
-  let node = hit.parentElement;
+  const agent = agentUiRoot(hit);
+  let node = hit === agent ? null : 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;
+    if (node === agent) break;
     node = node.parentElement;
   }
-  return box;
+  if (!agent) return box;
+  onAgent?.(agent);
+  return { top: box.top, left: box.left, width: box.width, height: box.height, agent: true };
 }
 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) {
+  return measureVisibilityDetail(el).visibility;
+}
+function measureVisibilityDetail(el) {
   const rect = hasDom() && el.isConnected ? layoutRect(el) : null;
   if (!rect) {
-    return computeVisibility({ rect: null, viewport: viewportSize() });
+    return {
+      visibility: computeVisibility({ rect: null, viewport: viewportSize() }),
+      agentElement: null
+    };
   }
-  return computeVisibility({
+  const agents = [];
+  const onAgent = (root) => {
+    if (!agents.includes(root)) agents.push(root);
+  };
+  const config2 = getPageAgentConfig();
+  const visibility = computeVisibility({
     rect,
     viewport: viewportSize(),
     clips: clippingBoxes(el),
     behindModal: isBehindModal(el),
-    coverAt: (x, y) => coverBox(el, x, y)
+    coverAt: (x, y) => coverBox(el, hitTest(x, y), onAgent),
+    // A custom hit test cannot look through the agent's UI: its agent hits
+    // then count as uncovered points (see computeVisibility).
+    ...config2.agentUiSelector && !config2.hitTest ? { coverBelowAgentAt: (x, y) => coverBox(el, hitTestBelowAgentUi(x, y)) } : {}
   });
+  return {
+    visibility,
+    agentElement: visibility.agentCover ? agents[0] ?? null : null
+  };
 }
 
 // src/controller.ts
@@ -1334,11 +1445,12 @@ var MENU_NOTE = "The tabs are shown as a drop-down menu here (the page is narrow
 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 = () => {
+var CLEAR_THE_WAY_TIMEOUT_MS = 1e3;
+async function settleLayout(...els) {
+  const key = () => els.map((el) => {
     const r = layoutRect(el);
     return r ? `${Math.round(r.top)},${Math.round(r.left)}` : "";
-  };
+  }).join(";");
   let last = key();
   let stable = 0;
   for (let waited = 0; waited < SCROLL_SETTLE_MAX_MS; waited += SCROLL_SETTLE_STEP_MS) {
@@ -1355,25 +1467,78 @@ async function settleLayout(el) {
 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)) {
+  let measured = measureVisibilityDetail(el);
+  if (measured.visibility.bands.length > 0 && nudgeIntoBounds(el, measured.visibility)) {
     scrolled = true;
     await settleLayout(el);
-    visibility = measureVisibility(el);
+    measured = measureVisibilityDetail(el);
+  }
+  return { scrolled, ...measured };
+}
+function within(promise, ms, fallback) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(fallback), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(fallback);
+      }
+    );
+  });
+}
+async function askToClearTheWay(tool, resolved, visibility, agentElement) {
+  const handler = getPageAgentConfig().clearTheWay;
+  const { agentCover, visibleWithoutAgent } = visibility;
+  if (!handler || !agentCover || !visibleWithoutAgent) return false;
+  const request = {
+    tool,
+    target: summary(resolved),
+    rect: { ...visibleWithoutAgent },
+    cover: { element: agentElement, rect: { ...agentCover } },
+    viewport: viewportSize()
+  };
+  let answer;
+  try {
+    answer = handler(request);
+  } catch {
+    return false;
   }
-  return { scrolled, visibility };
+  return await within(Promise.resolve(answer), CLEAR_THE_WAY_TIMEOUT_MS, false) === true;
+}
+async function revealForCall(tool, resolved, scrolledAlready) {
+  const { scrolled, visibility, agentElement } = await reveal(resolved.el, scrolledAlready);
+  if (!visibility.agentCover) return { scrolled, visibility, clearedTheWay: false };
+  if (!await askToClearTheWay(tool, resolved, visibility, agentElement)) {
+    return { scrolled, visibility, clearedTheWay: false };
+  }
+  await settleLayout(...agentElement ? [resolved.el, agentElement] : [resolved.el]);
+  return {
+    scrolled,
+    visibility: measureVisibilityDetail(resolved.el).visibility,
+    clearedTheWay: true
+  };
 }
 var onScreen = (v) => v.state === "visible" || v.state === "partial";
+var COVER_REASON = {
+  modal: "behind_dialog",
+  element: "covered",
+  agent: "covered_by_agent"
+};
 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" }
-  };
+  const reason = COVER_REASON[visibility.coveredBy ?? "element"];
+  const message = reason === "behind_dialog" ? `${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.` : reason === "covered_by_agent" ? `${what} is covered by the assistant's own window, so it cannot be shown right now. Ask the user to move or minimise the assistant window, then try again.` : `${what} is covered by another part of the page (such as a header, panel or popup), so it cannot be shown right now.`;
+  return { status: "hidden", message, output: { reason } };
 }
+var agentNotes = (clearedTheWay, visibility) => ({
+  ...clearedTheWay ? { clearedTheWay: true } : {},
+  ...visibility.agentCover && onScreen(visibility) ? { partlyCoveredByAgent: true } : {}
+});
 async function confirmSelected(el, settleMs) {
   const selected = () => el.isConnected && el.getAttribute("aria-selected") === "true";
   await Promise.resolve();
@@ -1420,7 +1585,7 @@ var handlers = {
     const durationMs2 = optionalDuration(input.durationMs);
     const resolved = resolveTarget(target2);
     if (resolved.status !== "ok") return failure(resolved);
-    const { scrolled, visibility } = await reveal(resolved.el);
+    const { scrolled, visibility, clearedTheWay } = await revealForCall("highlight", resolved);
     const covered = coveredResult(visibility, resolved.label);
     if (covered) return covered;
     if (!isRendered(resolved.el)) {
@@ -1440,6 +1605,7 @@ var handlers = {
         style,
         scrolled,
         inViewport: onScreen(visibility),
+        ...agentNotes(clearedTheWay, visibility),
         ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
       }
     };
@@ -1451,7 +1617,7 @@ var handlers = {
     const durationMs2 = optionalDuration(input.durationMs);
     const resolved = resolveTarget(target2);
     if (resolved.status !== "ok") return failure(resolved);
-    const { scrolled, visibility } = await reveal(resolved.el);
+    const { scrolled, visibility, clearedTheWay } = await revealForCall("point", resolved);
     const covered = coveredResult(visibility, resolved.label);
     if (covered) return covered;
     if (!isRendered(resolved.el)) {
@@ -1470,6 +1636,7 @@ var handlers = {
         target: summary(resolved),
         scrolled,
         inViewport: onScreen(visibility),
+        ...agentNotes(clearedTheWay, visibility),
         ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
       }
     };
@@ -1481,13 +1648,19 @@ var handlers = {
     if (resolved.status !== "ok") return failure(resolved);
     const outcome = scrollToTarget(resolved.el);
     if (outcome.status !== "ok") return failure(outcome);
-    const { scrolled, visibility } = await reveal(resolved.el, outcome.scrolled);
+    const { scrolled, visibility, clearedTheWay } = await revealForCall(
+      "scroll_to",
+      resolved,
+      outcome.scrolled
+    );
+    if (visibility.coveredBy === "agent") return coveredResult(visibility, resolved.label);
     return {
       status: "ok",
       output: {
         target: summary(resolved),
         scrolled,
         inViewport: onScreen(visibility),
+        ...agentNotes(clearedTheWay, visibility),
         ...visibility.state === "covered" ? { covered: true } : {},
         ...resolved.shownAs ? { shownAs: resolved.shownAs } : {}
       }
@@ -1526,6 +1699,8 @@ var handlers = {
     if (isBehindModal(shown)) {
       return { status: "hidden", message: "That tab is behind a dialog right now." };
     }
+    const measured = measureVisibilityDetail(shown);
+    const clearedTheWay = !!measured.visibility.agentCover && await askToClearTheWay("select_tab", resolved, measured.visibility, measured.agentElement);
     el.click();
     if (!await confirmSelected(el, getPageAgentConfig().tabSettleMs)) {
       return { status: "error", message: "The tab did not become selected." };
@@ -1533,7 +1708,12 @@ var handlers = {
     return {
       status: "ok",
       ...asMenu ? { message: `${MENU_NOTE} The menu now shows this tab.` } : {},
-      output: { target: summary(resolved), alreadySelected: false, ...extra }
+      output: {
+        target: summary(resolved),
+        alreadySelected: false,
+        ...extra,
+        ...clearedTheWay ? { clearedTheWay: true } : {}
+      }
     };
   },
   async navigate(raw) {
@@ -1574,4 +1754,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, 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 };
+export { CALL_LABEL_MAX, CANDIDATES_MAX, CLEAR_MARGIN, CLEAR_THE_WAY_TIMEOUT_MS, 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, findClearPosition, getAgentTargets, getEffects, getPageAgentConfig, highlight, inflate, intersectBoxes, intersectsViewport, isBehindModal, isFullyInViewport, isRendered, listTabs, listTargets, measureVisibility, notifyNavigated, nudgeIntoBounds, onAgentTargetsChange, onEffectsChange, overlaps, parseAppPath, placeLabel, point, pointerTarget, prefersReducedMotion, readPageText, rectOf, registerAgentTarget, resetPageAgent, resolveTarget, scanAgentAttributes, scrollIntoContainers, scrollToTarget, targetIdOf, unionRects, viewportSize, visibilityOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/page-agent-core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",