@ia-qa/self-healing 1.7.11 → 1.7.14

package/README.md

@@ -130,6 +130,7 @@ env/SSM — see **Configuration**) or capture-during-run, where your own suite l
 | day one, no baseline — is my suite still valid? | `audit` (advisory; never gate on it) |
 | is the app itself sound? | `check` — dead links, unnamed elements, name collisions, orphan pages |
 | which pages am I *not* testing? | `discover` (`--sitemap`, or `--crawl` behind the login) |
+| **my menus, tabs and modals aren't in the contract** | **`map --deep`** — opens them and puts what they reveal in the same contract |
 | what do my tests actually use? | `ingest` |
 | show me the app's structure | `graph --format mermaid\|svg\|json\|markdown` |
 | is this getting better or worse? | `history` |
@@ -208,6 +209,33 @@ extensions and the code paths are exercised, but the test suite's rewrite cases
 against `.js`/`.ts` files. Treat non-JS rewriting as working-but-less-travelled: run
 `fix --dry-run` first, which you should be doing anyway.
 
+### One more axis: how much of the page is under contract at all
+
+`map` records the state a page **loads in**. Everything behind a dropdown, a tab, an accordion
+or a modal is in no contract — so when it drifts, nothing says so. It is a coverage hole and
+never a false alarm, which is what makes it survive: the gate stays green over a surface it
+never looked at.
+
+```bash
+ia-qa-heal map --deep     # open them, and contract what appears
+```
+
+Measured on ia-qa.com: one page 105 → 133 elements, another 126 → 264. Across eight unrelated
+sites (MDN, Bootstrap, Material UI, GOV.UK, Wikipedia, Docusaurus…), seven gained elements —
+the gain is largest on component-framework apps and near zero on content sites, so it is worth
+saying which one you have before reaching for it.
+
+- **It cannot mutate your app.** Every non-GET request is aborted for the walk, and controls
+  named like actions (*log out*, *delete*, *pay*…) are never clicked — a logout handler that
+  only clears local storage sends no request for the network guard to catch.
+- **What it reaches but cannot contract is reported**, not hidden (`↩ N left out`): a selector
+  must name exactly one element, and a positional one captured inside a menu can collide with
+  the page behind it.
+- **A deep baseline is only comparable to a deep capture.** Mixing the two reports everything
+  behind a menu as `lost`; `diff` and the MCP both warn before the verdict.
+- **~1 minute per page** against seconds for a plain `map`. It is for building a baseline, not
+  for a per-commit gate.
+
 ## The verdict
 
 ```

package/TUTORIAL.md

@@ -11,7 +11,7 @@
 2. [The 30-second mental model](#2-the-30-second-mental-model)
 3. [Before you start](#3-before-you-start)
 4. [Path A — I use an AI agent (easiest)](#4-path-a--i-use-an-ai-agent-easiest)
-5. [Path B — I use a terminal](#5-path-b--i-use-a-terminal)
+5. [Path B — I use a terminal](#5-path-b--i-use-a-terminal) — including [menus, tabs and modals: `map --deep`](#step-53b--what-about-my-menus-tabs-and-modals-map---deep)
 6. [Your first real workflow](#6-your-first-real-workflow-the-whole-point) — including [a test just failed, is it drift?](#step-64b--you-didnt-run-diff-you-got-a-red-build--explain) · [the console, if you don't want a terminal](#step-68--no-terminal-open-the-console)
 7. [Reading the verdict](#7-reading-the-verdict)
 8. [Putting it in CI](#8-putting-it-in-ci) — [JUnit trends](#82-trend-charts-for-free--junit) · [the run history](#83-the-trend--ia-qa-heal-history)
@@ -344,6 +344,48 @@ Plus, for the whole app:
 
 Commit them.
 
+### Step 5.3b — What about my menus, tabs and modals? `map --deep`
+
+A page has more than one state, and `map` records the one it loads in. Everything behind a
+dropdown, a tab, an accordion or a dialog is simply not there — so if it drifts, nothing tells
+you. It is a **coverage** hole rather than a false alarm, which is what makes it easy to miss:
+the gate stays green over a surface it never looked at.
+
+```bash
+npx ia-qa-heal map --deep
+```
+
+It opens what can be opened and contracts what appears. On ia-qa.com: `/method` 105 → 133
+elements, the home page 126 → 264.
+
+```
+✔ 264 interactive elements → .ia-qa/mapping/home.json + .ia-qa/mapping/home.md
+  🔍 deep: +140 behind interaction (124 on load) · 37 states · 54 clicks, 9 reloads
+  ↩ 133 revealed elements left out — selector already names another element
+  🛡  34 non-GET requests blocked during exploration (nothing mutating left the browser)
+```
+
+Four things worth knowing before you use it:
+
+**It cannot break your app.** Every non-GET request is aborted for the whole walk, so a click
+that would have deleted, paid or submitted anything never reaches your server — and controls
+whose name reads like an action (*log out*, *delete*, *pay*…) are not clicked at all, because a
+logout handler that just clears local storage sends no request for the guard to stop.
+
+**Elements it reaches but cannot contract are reported, not hidden** (`↩ 133 left out`). A
+selector must name exactly one element; a positional one captured inside a menu can collide with
+an element on the page behind it, and a contract holding the same selector twice makes the diff
+pair rows at random. Those are dropped and counted.
+
+**A deep baseline may only be diffed against a deep capture.** Mixing them reports everything
+behind a menu as `lost` — the tool warns you before the verdict, in the CLI and over MCP alike.
+Decide once, per baseline.
+
+**It costs about a minute per page** where a plain `map` costs seconds. Use it to build or
+refresh a baseline, not on every commit. `--depth 2` goes one click deeper; it was measured at
+three times the time for a contract that never finishes, so leave it alone unless you have a
+reason.
+
 ### Step 5.4 — Day one, before any drift: `audit`
 
 Everything after this point pays off at the *next* UI change. `audit` pays off now: it asks **does my test suite still name things that exist?**
@@ -858,6 +900,7 @@ npx ia-qa-heal init                       # one-time setup
 npx ia-qa-heal discover [--crawl] [--apply]  # optional: propose pages for config.json (sitemap or safe crawl)
 npx ia-qa-heal map                        # scan → *.json + *.md + _overview.md + _navigation.md/.svg
 npx ia-qa-heal map --screenshots          # + one JPEG per page, shown in the --report HTML (gitignore _shots/)
+npx ia-qa-heal map --deep                 # + open menus/tabs/dialogs and contract what they reveal (see below)
 npx ia-qa-heal baseline                   # promote mapping/ → baseline/ (commit it)
 #   …change the app, then `map` again…
 npx ia-qa-heal diff                       # verdict: PASS / FIX / BLOCK (baseline/ vs mapping/)

package/dist/aom.d.ts

@@ -34,6 +34,20 @@ export interface MappedElement {
      */
     rawName?: string;
     nameMasked?: boolean;
+    /**
+     * How to reach this element, when reaching it takes clicks: the accessible names of the
+     * controls opened on the way (`["☰", "RAG & Agents"]`). Written by `map --deep` only, and
+     * omitted on everything visible at load — so a contract captured without exploration stays
+     * byte-identical to one captured before `via` existed.
+     *
+     * Never part of identity. `diffMappings` matches on role + name + selector and must keep
+     * doing so: an element that moved from behind a menu into the open is the *same* element,
+     * and a diff that called that drift would report a UX improvement as a regression.
+     *
+     * Its reader is a person or an agent asking "how do I even get to this button" — which is
+     * the question a deep contract creates and owes an answer to.
+     */
+    via?: string[];
 }
 export interface PageMapping {
     page: string;
@@ -52,6 +66,17 @@ export interface PageMapping {
      * means *unknown*, never *matching*.
      */
     captureState?: CaptureState;
+    /**
+     * How many clicks deep this contract was explored (`map --deep`). Absent means the loaded
+     * state only — every contract written before exploration existed, which is why absent must
+     * never be read as `0`-and-therefore-comparable-to-a-deep-one on purpose.
+     *
+     * It is recorded for the same reason `source` is: a deep baseline diffed against a shallow
+     * capture reports every explored element as `lost`, which is drift manufactured out of the
+     * capture method rather than out of the app. Depth is a property of a *baseline*, and a
+     * mismatch has to be nameable.
+     */
+    exploredDepth?: number;
 }
 /**
  * Did these two mappings come out of the same `map` run?
@@ -77,6 +102,35 @@ export declare function isSameCapture(baseline: {
 } | null | undefined, current: {
     capturedAt?: string;
 } | null | undefined): boolean;
+/**
+ * Were these two contracts explored to the same depth?
+ *
+ * A deep contract holds the elements behind menus, tabs and dialogs; a shallow one cannot, so
+ * diffing one against the other reports every one of them as `lost`. That is not a handful of
+ * noisy rows — most of a page's surface can sit behind interaction, so the mismatch manufactures
+ * the whole BLOCK out of how the two captures were taken.
+ *
+ * Absent means depth 0 — the loaded state only. That is a *known* value, not an unknown one:
+ * every contract written before `--deep` existed describes exactly one state. (`captureState` is
+ * the opposite case, where absent genuinely means "cannot tell", and must never read as a match.)
+ *
+ * Lives here, beside `isSameCapture`, for the same reason: both doors into a diff — the CLI and
+ * the MCP server — have to agree on what is not a comparison. One warning and the other silent
+ * would just move the phantom verdict to whichever door the user knocked on.
+ */
+export declare function depthMismatch(baseline: {
+    exploredDepth?: number;
+} | null | undefined, current: {
+    exploredDepth?: number;
+} | null | undefined): {
+    baseline: number;
+    current: number;
+} | null;
+/** The sentence every door prints or attaches when `depthMismatch` returns non-null. */
+export declare function depthMismatchMessage(m: {
+    baseline: number;
+    current: number;
+}): string;
 export declare function extractInteractiveElements(page: Page): Promise<MappedElement[]>;
 export declare function saveMapping(mapping: PageMapping, dir?: string): string;
 export declare function loadMapping(pageName: string, dir?: string): PageMapping;

package/dist/aom.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSameCapture = isSameCapture;
+exports.depthMismatch = depthMismatch;
+exports.depthMismatchMessage = depthMismatchMessage;
 exports.extractInteractiveElements = extractInteractiveElements;
 exports.saveMapping = saveMapping;
 exports.loadMapping = loadMapping;
@@ -63,6 +65,36 @@ const extract_1 = require("./browser/extract");
 function isSameCapture(baseline, current) {
     return Boolean(baseline?.capturedAt) && baseline.capturedAt === current?.capturedAt;
 }
+/**
+ * Were these two contracts explored to the same depth?
+ *
+ * A deep contract holds the elements behind menus, tabs and dialogs; a shallow one cannot, so
+ * diffing one against the other reports every one of them as `lost`. That is not a handful of
+ * noisy rows — most of a page's surface can sit behind interaction, so the mismatch manufactures
+ * the whole BLOCK out of how the two captures were taken.
+ *
+ * Absent means depth 0 — the loaded state only. That is a *known* value, not an unknown one:
+ * every contract written before `--deep` existed describes exactly one state. (`captureState` is
+ * the opposite case, where absent genuinely means "cannot tell", and must never read as a match.)
+ *
+ * Lives here, beside `isSameCapture`, for the same reason: both doors into a diff — the CLI and
+ * the MCP server — have to agree on what is not a comparison. One warning and the other silent
+ * would just move the phantom verdict to whichever door the user knocked on.
+ */
+function depthMismatch(baseline, current) {
+    const b = baseline?.exploredDepth ?? 0;
+    const c = current?.exploredDepth ?? 0;
+    return b === c ? null : { baseline: b, current: c };
+}
+/** The sentence every door prints or attaches when `depthMismatch` returns non-null. */
+function depthMismatchMessage(m) {
+    const deeper = m.baseline > m.current ? 'baseline' : 'current capture';
+    const shallower = deeper === 'baseline' ? 'current capture' : 'baseline';
+    return (`Exploration depth mismatch — the ${deeper} was captured with \`map --deep\`, the ${shallower} ` +
+        `was not (depth ${m.baseline} vs ${m.current}). A deep contract holds the elements behind ` +
+        `menus, tabs and dialogs; a shallow one cannot, so those elements read as \`lost\` here. Most ` +
+        `of this verdict is probably that, not drift in your app. Capture both sides the same way.`);
+}
 async function extractInteractiveElements(page) {
     return page.evaluate(extract_1.extractInPage);
 }

package/dist/aom.js.map

@@ -1 +1 @@
-{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkFA,sCAKC;AAED,gEAEC;AAED,kCAwBC;AAED,kCAQC;AA/HD,uCAAyB;AACzB,2CAA6B;AAE7B,qCAAmD;AACnD,+CAAkD;AA2DlD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAC3B,QAAoD,EACpD,OAAmD;IAEnD,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,QAAS,CAAC,UAAU,KAAK,OAAO,EAAE,UAAU,CAAC;AACvF,CAAC;AAEM,KAAK,UAAU,0BAA0B,CAAC,IAAU;IACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,uBAAa,CAA6B,CAAC;AAClE,CAAC;AAED,SAAgB,WAAW,CAAC,OAAoB,EAAE,MAAc,IAAA,mBAAU,GAAE;IAC1E,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACtE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,8BAA8B,IAAI,CAAC,UAAU,iBAAiB,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACxD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAExC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,IAAI,KAAK,KAAK,GAAG,OAAO,CAAC,IAAI,OAAO;YAAE,SAAS;QAC/C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAChE,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC3C,OAAO,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,wBAAwB,KAAK,oCAAoC,CAAC,CAAC;YACpG,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,WAAW,CAAC,QAAgB,EAAE,MAAc,IAAA,mBAAU,GAAE;IACtE,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,MAAM,IAAI,2BAA2B,QAAQ,WAAW,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;AAClE,CAAC"}
+{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":"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"}

package/dist/browser/openables.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-page finder for controls that *reveal* elements — the widened half of discovery.
+ *
+ * Self-contained by the same rule as `browser/extract.js` and `browser/discover.js`:
+ * Playwright serialises it with `toString()` into `page.evaluate()`, so no imports, no
+ * closures, no TypeScript. Unlike those two it is **npm-only** — the web tool imports
+ * `match.js`, `contract.js` and `extract.js` and nothing else, so a change here owes one
+ * publish, not two.
+ *
+ * ## Why this exists next to `discover.js` rather than replacing it
+ *
+ * `findRevealTargets` answers "what is safe to open **while crawling for links**". It is
+ * deliberately ARIA-only: a crawler that clicks a bare `<button>` on someone's app to find
+ * an `href` is trading a large risk for a small reward. That restraint is correct there and
+ * must not be loosened — `crawl.ts` keeps using it.
+ *
+ * This function answers a different question: "what is safe to open **to complete the
+ * contract of this page**". The reward is the whole feature — a contract that describes one
+ * state of a page describes an application the way a screenshot describes a film. Measured
+ * on a React site with no ARIA disclosure attributes at all, the closed state held 105
+ * elements and the reachable surface held 303. `findRevealTargets` returns 0 there, because
+ * `aria-expanded` is documentation the app never wrote.
+ *
+ * So the candidate set is widened to bare `<button>`, `[role=tab]` and `[onclick]`, and the
+ * safety is moved from *what we are willing to click* to *what a click is allowed to do*:
+ * `explore.ts` blocks every non-GET request for the duration. That is a stronger guarantee
+ * than an attribute allowlist, because it holds against the app rather than against its
+ * markup, and it is the reason widening here is defensible.
+ *
+ * What is still refused, and why each one:
+ *   - a navigating `<a href>` — that is navigation, and the page it reaches has a contract
+ *     of its own. Following it here would fold two pages into one.
+ *   - `type="submit"` / `type="reset"`, and a bare `<button>` inside a `<form>` (which
+ *     submits by default) — a blocked POST still leaves the app showing an error state, and
+ *     a contract captured over an error banner is a lie about the page.
+ *   - an accessible name that reads like an action (log out, delete, pay…). The network
+ *     guard already stops the server-side effect; this stops the *client-side* one — a
+ *     `logout` handler that clears localStorage and re-renders needs no request at all.
+ *   - `aria-expanded="true"` — already open. Clicking that collapses, which removes elements
+ *     instead of revealing them.
+ */
+export function findOpenables(): {
+    handle: string;
+    name: any;
+}[];

package/dist/browser/openables.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findOpenables = findOpenables;
+/**
+ * In-page finder for controls that *reveal* elements — the widened half of discovery.
+ *
+ * Self-contained by the same rule as `browser/extract.js` and `browser/discover.js`:
+ * Playwright serialises it with `toString()` into `page.evaluate()`, so no imports, no
+ * closures, no TypeScript. Unlike those two it is **npm-only** — the web tool imports
+ * `match.js`, `contract.js` and `extract.js` and nothing else, so a change here owes one
+ * publish, not two.
+ *
+ * ## Why this exists next to `discover.js` rather than replacing it
+ *
+ * `findRevealTargets` answers "what is safe to open **while crawling for links**". It is
+ * deliberately ARIA-only: a crawler that clicks a bare `<button>` on someone's app to find
+ * an `href` is trading a large risk for a small reward. That restraint is correct there and
+ * must not be loosened — `crawl.ts` keeps using it.
+ *
+ * This function answers a different question: "what is safe to open **to complete the
+ * contract of this page**". The reward is the whole feature — a contract that describes one
+ * state of a page describes an application the way a screenshot describes a film. Measured
+ * on a React site with no ARIA disclosure attributes at all, the closed state held 105
+ * elements and the reachable surface held 303. `findRevealTargets` returns 0 there, because
+ * `aria-expanded` is documentation the app never wrote.
+ *
+ * So the candidate set is widened to bare `<button>`, `[role=tab]` and `[onclick]`, and the
+ * safety is moved from *what we are willing to click* to *what a click is allowed to do*:
+ * `explore.ts` blocks every non-GET request for the duration. That is a stronger guarantee
+ * than an attribute allowlist, because it holds against the app rather than against its
+ * markup, and it is the reason widening here is defensible.
+ *
+ * What is still refused, and why each one:
+ *   - a navigating `<a href>` — that is navigation, and the page it reaches has a contract
+ *     of its own. Following it here would fold two pages into one.
+ *   - `type="submit"` / `type="reset"`, and a bare `<button>` inside a `<form>` (which
+ *     submits by default) — a blocked POST still leaves the app showing an error state, and
+ *     a contract captured over an error banner is a lie about the page.
+ *   - an accessible name that reads like an action (log out, delete, pay…). The network
+ *     guard already stops the server-side effect; this stops the *client-side* one — a
+ *     `logout` handler that clears localStorage and re-renders needs no request at all.
+ *   - `aria-expanded="true"` — already open. Clicking that collapses, which removes elements
+ *     instead of revealing them.
+ */
+function findOpenables() {
+    // Matched against the accessible name, English + French. Word-bounded so "cancellation
+    // policy" is not read as "cancel" — but `\b` does not fire on accented letters in some
+    // engines, so the French verbs are also matched bare.
+    var ACTION_RE = new RegExp('\\b(log\\s?out|sign\\s?out|logout|signout|delete|remove|destroy|discard|deactivate' +
+        '|disable|unsubscribe|revoke|buy|pay|payment|checkout|purchase|order|submit|send' +
+        '|confirm|approve|reject|save|reset|publish|cancel|upgrade|subscribe|renew)\\b' +
+        '|supprimer|effacer|payer|acheter|commander|envoyer|valider|confirmer|annuler' +
+        '|d[ée]connexion|se d[ée]connecter|d[ée]sabonner|r[ée]initialiser|enregistrer', 'i');
+    var OPENABLE_SELECTOR = [
+        'button',
+        '[role="button"]',
+        '[role="tab"]',
+        '[role="menuitem"]',
+        'summary',
+        '[aria-haspopup]',
+        '[aria-expanded]',
+        '[aria-controls]',
+        '[onclick]',
+    ].join(', ');
+    function isVisible(el) {
+        var rect = el.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0)
+            return false;
+        var style = window.getComputedStyle(el);
+        return style.visibility !== 'hidden' && style.display !== 'none' && style.opacity !== '0';
+    }
+    function accName(el) {
+        var label = el.getAttribute('aria-label');
+        if (label)
+            return label.trim().replace(/\s+/g, ' ');
+        var labelledBy = el.getAttribute('aria-labelledby');
+        if (labelledBy) {
+            var joined = labelledBy
+                .split(/\s+/)
+                .map(function (id) {
+                var n = document.getElementById(id);
+                return n ? n.textContent : '';
+            })
+                .join(' ')
+                .trim();
+            if (joined)
+                return joined.replace(/\s+/g, ' ');
+        }
+        var text = (el.textContent || '').trim().replace(/\s+/g, ' ');
+        return text || (el.getAttribute('title') || '').trim();
+    }
+    var found = document.querySelectorAll(OPENABLE_SELECTOR);
+    var out = [];
+    var i = 0;
+    for (var k = 0; k < found.length; k++) {
+        var el = found[k];
+        var tag = el.tagName.toLowerCase();
+        if (!isVisible(el))
+            continue;
+        if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true')
+            continue;
+        if (tag === 'a') {
+            var href = el.getAttribute('href');
+            if (href && href !== '#' && href.indexOf('javascript:') !== 0)
+                continue;
+        }
+        if (tag === 'input')
+            continue;
+        var type = (el.getAttribute('type') || '').toLowerCase();
+        if (type === 'submit' || type === 'reset')
+            continue;
+        if (tag === 'button' && el.closest('form') && type !== 'button')
+            continue;
+        if (el.getAttribute('aria-expanded') === 'true')
+            continue;
+        var name = accName(el);
+        if (ACTION_RE.test(name))
+            continue;
+        // A stamped attribute is the one selector guaranteed to re-find this exact element,
+        // and adding a data attribute changes nothing the app reacts to. The stamp does not
+        // survive a reload, which is why `explore.ts` re-stamps after every reset.
+        el.setAttribute('data-iaqa-open', String(i));
+        out.push({ handle: '[data-iaqa-open="' + i + '"]', name: name.slice(0, 80) });
+        i++;
+    }
+    return out;
+}
+//# sourceMappingURL=openables.js.map

package/dist/browser/openables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openables.js","sourceRoot":"","sources":["../../src/browser/openables.js"],"names":[],"mappings":"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"}

package/dist/cli/args.js

@@ -18,7 +18,7 @@ exports.KNOWN_FLAGS = {
     init: ['--yes', '--base-url', '--pages', '--discover', '--tests', '--test-command', '--bootstrap'],
     discover: ['--sitemap', '--crawl', '--no-reveal', '--strict-host', '--apply', '--max', '--depth', '--session'],
     login: ['--url', '--session'],
-    map: ['--screenshots', '--session'],
+    map: ['--screenshots', '--session', '--deep', '--depth', '--deep-budget'],
     baseline: ['--dry-run'],
     diff: ['--strict', '--json', '--junit', '--dir', '--report', '--open'],
     fix: ['--dry-run', '--locators', '--dir', '--json'],

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AAgCA,gDAeC;AA/CD;;;;;;;;;;;GAWG;AACU,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,aAAa,CAAC;IAClG,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9G,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAC7B,GAAG,EAAE,CAAC,eAAe,EAAE,WAAW,CAAC;IACnC,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IACtE,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC;IACnD,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC;IACvD,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC;IAC3D,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACtF,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IAC7D,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC9B,YAAY,EAAE,CAAC,QAAQ,CAAC;IACxB,EAAE,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC;CACnF,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,0FAA0F;gBAC9G,4GAA4G;gBAC5G,8FAA8F,CACjG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,qBAAqB,OAAO,8CAA8C,CAAC,CAAC;IAChH,CAAC;AACH,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AAgCA,gDAeC;AA/CD;;;;;;;;;;;GAWG;AACU,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,aAAa,CAAC;IAClG,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9G,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAC7B,GAAG,EAAE,CAAC,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,CAAC;IACzE,QAAQ,EAAE,CAAC,WAAW,CAAC;IACvB,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IACtE,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC;IACnD,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,CAAC;IACvD,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC;IAC3D,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACtF,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IAC7D,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC9B,YAAY,EAAE,CAAC,QAAQ,CAAC;IACxB,EAAE,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC;CACnF,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,0FAA0F;gBAC9G,4GAA4G;gBAC5G,8FAA8F,CACjG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,qBAAqB,OAAO,8CAA8C,CAAC,CAAC;IAChH,CAAC;AACH,CAAC"}

package/dist/cli/diff.d.ts

@@ -122,6 +122,21 @@ export interface DirDiffCollection {
      * qualifies, which is the ordinary case and costs nothing.
      */
     systemic: SystemicOutcome;
+    /**
+     * The two sides were explored to different depths (`map --deep`), when either declares one.
+     *
+     * A deep baseline diffed against a shallow capture reports every element behind a menu as
+     * `lost` — a BLOCK over an app where nothing changed, manufactured entirely by how the two
+     * contracts were captured. It is the same class as `run`'s source mismatch, and it is worse:
+     * a deep contract can hold more elements behind interaction than in front of it, so the
+     * false verdict is not a handful of rows but most of the page.
+     *
+     * `null` when both sides agree (including both absent — two shallow contracts).
+     */
+    depthMismatch: {
+        baseline: number;
+        current: number;
+    } | null;
 }
 /**
  * A broken binding whose element survived is repairable — FIX. Everything else is a
@@ -152,6 +167,16 @@ export interface DirReport {
     totals: Report['counts'];
     /** Pairs left out of the verdict: same capture on both sides, so incapable of showing drift. */
     staleExcluded?: string[];
+    /**
+     * The two sides were explored to different depths (`map --deep`) — so much of this verdict is
+     * probably an artefact of how the contracts were captured rather than drift in the app.
+     * Carried on the aggregate so `--json` and the report state it, not only the terminal.
+     */
+    depthMismatch?: {
+        baseline: number;
+        current: number;
+        why: string;
+    };
     /**
      * Renamed labels the suite locates by name, de-duped across pages — a shared
      * header renames once, not once per page that carries it.

package/dist/cli/diff.js

@@ -365,6 +365,11 @@ async function runDiff(args) {
         refuseToCompare('same-capture', sameCaptureMessage(baseline.capturedAt), 'Change the app and run `ia-qa-heal map` again, so the two sides are different moments.', json);
         return;
     }
+    // Before the verdict, never after: a depth mismatch does not colour a few rows, it can invent
+    // the entire BLOCK. Same check as `diff --dir` and the MCP — one shared function, three doors.
+    const depths = (0, aom_1.depthMismatch)(baseline, current);
+    if (depths && !json)
+        console.error(`\n⚠️  ${(0, aom_1.depthMismatchMessage)(depths)}`);
     const usage = (0, ingest_1.loadUsage)();
     const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, (0, nameMask_1.loadNameMasks)(), usage), baseline);
     // Same rule as the directory walk: the resolutions sit next to the mappings they
@@ -547,7 +552,7 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         console.error(`❌ "${currentDir}" is not a directory.`);
         process.exit(2);
     }
-    const { reports, stale, systemic } = collectDirDiff(baselineDir, currentDir);
+    const { reports, stale, systemic, depthMismatch: depths } = collectDirDiff(baselineDir, currentDir);
     if (reports.length === 0 && stale.length > 0) {
         refuseToCompare('same-capture', `❌ Nothing to compare: ${stale.length === 1 ? 'the only pair is' : `all ${stale.length} pairs are`} ` +
             `the same capture on both sides.\n\n` +
@@ -562,10 +567,23 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         refuseToCompare('no-pairs', `❌ No matching mapping pairs found between ${rel(baselineDir)} and ${rel(currentDir)}.`, 'Mapping files are paired by filename — run `ia-qa-heal map` so both directories hold the same pages.', opts.json);
         return;
     }
+    // Printed BEFORE the verdict, not after it. A depth mismatch does not colour a few rows —
+    // it can invent the entire BLOCK, because everything the deep side found behind a menu is
+    // simply absent from the shallow side and reads as `lost`. Someone who meets the verdict
+    // first will start hand-repairing drift that never happened.
+    if (depths) {
+        console.error(`\n⚠️  ${(0, aom_1.depthMismatchMessage)(depths)}\n` +
+            `   \`ia-qa-heal map --deep\` before diffing, or re-baseline without it.`);
+    }
     // Aggregate verdict
     const aggregate = aggregateReports(reports);
     if (stale.length > 0)
         aggregate.staleExcluded = stale;
+    // Onto the aggregate, not only the terminal: `--json` is what a pipeline reads, and a CI that
+    // sees BLOCK without knowing the two sides were captured differently is the same blind spot
+    // the MCP had. Every consumer of a verdict gets the caveat attached to it.
+    if (depths)
+        aggregate.depthMismatch = { ...depths, why: (0, aom_1.depthMismatchMessage)(depths) };
     if (systemic.groups.length > 0)
         aggregate.systemic = systemic;
     Object.assign(aggregate, (0, nextStep_1.nextStepFor)(aggregate.verdict, {
@@ -665,6 +683,10 @@ function collectDirDiff(baselineDir, currentDir) {
     // never as a match.
     let baselineState;
     let currentState;
+    // Exploration depth, settled the same way and for the same reason. Absent means the loaded
+    // state only, which is depth 0 — a real value here, not unknown: every contract written
+    // before `--deep` existed describes exactly one state, and that is knowable.
+    let deepest = null;
     // Kept out of the verdict rather than counted as `ok` — N ok that were never
     // compared is exactly the false green this guard exists to stop.
     const stale = [];
@@ -675,6 +697,7 @@ function collectDirDiff(baselineDir, currentDir) {
     const assess = (baseline, current, baselineFile, currentFile, page) => {
         baselineState ??= baseline.captureState;
         currentState ??= current.captureState;
+        deepest ??= (0, aom_1.depthMismatch)(baseline, current);
         const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, masks, usage), baseline);
         report.nameDrift = (0, nameDrift_1.assessNameDrift)(report.rows, current.elements, usage);
         report.verdict = (0, nameDrift_1.escalateVerdict)(report.verdict, report.nameDrift);
@@ -734,7 +757,12 @@ function collectDirDiff(baselineDir, currentDir) {
     // gets exactly the reports it got before.
     const systemic = (0, systemicDelta_1.assessSystemic)(reports, baselineState, currentState);
     reports = (0, systemicDelta_1.applySystemic)(reports, systemic);
-    return { reports, stale, systemic };
+    return {
+        reports,
+        stale,
+        systemic,
+        depthMismatch: deepest,
+    };
 }
 function aggregateReports(reports) {
     const layoutReports = reports.filter((r) => r.isLayout);