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

package/README.md

@@ -47,10 +47,14 @@ ignoreSelector })` and `executePageCall(call)`, the single entry point for
   the model's tool calls. `PAGE_TOOL_NAMES` and `PAGE_TOOLS` (plain-JSON
   input shapes) let the agent server mirror the contract exactly.
 - **Visibility**: `measureVisibility(el)` says what of a target the user can
-  see: clipped to the viewport and its scroll boxes, cut where a sticky
-  header / footer / dock covers it (hit-tested with
-  `document.elementsFromPoint`, the layer skipped), and `covered` behind a
-  modal dialog or `inert`. Bindings draw only `visible` and hide (not
+  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
@@ -158,7 +162,8 @@ target) and a live region (`.chpa-sr`). Override `--chpa-accent` (default
 `#6d28d9`) and `--chpa-z` (default `2147482000`, below the Access
 Inspector). The layer stays on top so targets inside dialogs can be pointed
 at; covers are handled by drawing only the visible part (an outline cut by
-a header carries `data-cut="top"` and is left open on that side). Dark mode follows `.dark` / `[data-theme='dark']`; reduced
+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

package/dist/index.d.ts

@@ -265,7 +265,7 @@ declare function placeLabel(rect: RectLike, size: Size, viewport: Size, opts?: {
 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 band). */
+/** Which sides of a target are cut off (by clipping, the viewport or a covering strip). */
 interface CutSides {
     top: boolean;
     right: boolean;
@@ -289,14 +289,18 @@ interface TargetVisibility {
     visible: Box | null;
     /**
      * The area the target is shown in: the viewport, narrowed by clipping
-     * ancestors and by edge bands (sticky header, footer, side dock) that
-     * cover it. Captions are kept inside it. Null when there is none.
+     * 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';
-    /** Edge bands that cover part (or all) of the target, as measured. */
+    /**
+     * 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 {
@@ -312,7 +316,11 @@ interface VisibilityInput {
      * 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). */
+    /**
+     * 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;
 }
 /**
@@ -321,13 +329,25 @@ interface VisibilityInput {
  *
  * Occlusion rules, chosen to be robust with coarse sampling:
  * - something that covers the whole visible part (a dialog backdrop) hides it;
- * - an edge band (a box spanning the visible part's full width or height and
- *   reaching past one edge, like a sticky header) is cut off exactly at the
- *   band's edge, so the effect stops where the header starts;
- * - anything else on top (a floating button, a small popover) hides the
- *   target only when it covers most of the remaining sample points, and is
- *   otherwise drawn over: clipping around arbitrary shapes is not worth the
- *   wrong guesses.
+ * - 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;
 
@@ -581,7 +601,7 @@ declare function isBehindModal(el: Element): boolean;
  * 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 (9 hit tests each).
+ * handful of effects (13 hit tests each, 4 more per cut side; reads only).
  */
 declare function measureVisibility(el: Element): TargetVisibility;
 

package/dist/index.js

@@ -211,6 +211,8 @@ function pointerTarget(rect, viewport, margin = 12) {
 }
 var EDGE = 1;
 var MIN_VISIBLE = 4;
+var PROBE_INSET = 2;
+var MAX_TRIM_ROUNDS = 6;
 var viewportBox = (viewport) => ({
   top: 0,
   left: 0,
@@ -270,11 +272,24 @@ function computeVisibility(input) {
       }
     }
     const covers = [];
-    for (const s of samples) {
-      if (s.cover && !covers.some((c) => sameBox(c, s.cover))) covers.push(s.cover);
-    }
+    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;
-    while (trimmed && visible) {
+    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;
@@ -293,6 +308,9 @@ function computeVisibility(input) {
         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 });
@@ -307,6 +325,18 @@ function computeVisibility(input) {
   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;
 }

package/package.json

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