@dikshanty94/webnav 0.2.0

package/dist/explorer/patterns.d.ts

@@ -0,0 +1,49 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+export declare const ARIA_ROLES: ReadonlySet<string>;
+export declare const ARIA_ATTRS: ReadonlySet<string>;
+export declare const TRIGGER_CONTEXTS: readonly ["diff.added", "overlay", "landing"];
+export type TriggerContext = (typeof TRIGGER_CONTEXTS)[number];
+export declare const PACK_TYPES: readonly ["overlay-open", "value-domain"];
+export type PackType = (typeof PACK_TYPES)[number];
+export interface ContainsPredicate {
+    role: string;
+    min?: number;
+    attr?: string;
+}
+export interface Trigger {
+    context: TriggerContext;
+    root?: {
+        role: string;
+        attr?: string;
+    };
+    contains: ContainsPredicate[];
+}
+export interface Fixture {
+    snapshot: string;
+    expect: 'matched' | 'unmatched';
+}
+export interface PatternPack {
+    name: string;
+    version: number;
+    type: PackType;
+    trigger: Trigger;
+    fixture: Fixture;
+    evidence: string;
+    source?: string;
+}
+/** Validate ONE pack entry. Pure. Every failure is a specific, named reason (no generic "invalid").
+ *  Order: shape → forbidden-value scan (roles/attrs) → fixture execution. */
+export declare function lintPackEntry(raw: unknown): string[];
+export declare function evaluateTrigger(trigger: Trigger, nodes: SnapNode[]): boolean;
+/** Load every `*.json` pack entry from the given dirs (default = the two shipped dirs), sorted by
+ *  filename for determinism. Each file holds ONE entry (object) OR an array of entries. Throws on the
+ *  first invalid file/entry with a message listing the lint failures (loud, per the plan). */
+export declare function loadPatternPacks(dirs?: string[]): PatternPack[];
+/** Hook 1 (overlay-open): did ANY overlay-open pack trigger match these diff.added nodes? Called
+ *  ONLY when the built-in openedOverlay detection declined — a match flips detection true. */
+export declare function packDetectsOverlay(packs: PatternPack[], addedNodes: SnapNode[]): boolean;
+/** Hook 2 (value-domain): the set of NODE NAMES a value-domain pack marks as value data within the
+ *  given candidate nodes. A node joins the excluded set iff it sits inside a firing trigger's matched
+ *  subtree (the value grid), so its name never becomes an affordance / never anchors a fingerprint.
+ *  Returns names (callers filter by name, matching enumeratedNames/templateFolds.gatedNames). */
+export declare function packValueNames(packs: PatternPack[], nodes: SnapNode[]): Set<string>;

package/dist/explorer/patterns.js

@@ -0,0 +1,290 @@
+// Declarative pattern packs (Phase 2 extension loop, 2026-07-11-future-proof-program.md §Phase 2 +
+// 2026-07-12-extension-loop.md). An agent extends STRUCTURE coverage by adding a JSON data entry —
+// NEVER by touching core code. Every safety property here is the whole point:
+//
+//  • The core's effect set is CLOSED. A pack maps a STRUCTURAL trigger onto exactly one of TWO
+//    existing effects: `overlay-open` (feeds the openedOverlay detection) and `value-domain` (feeds
+//    the folded/value exclusion sets). Both effects only make the engine MORE CONSERVATIVE about
+//    what it STORES — a pack can gate storage, it can NEVER mint an affordance, edge, or state.
+//  • The trigger schema is STRUCTURAL-ONLY: ARIA roles, containment (root/contains + min counts),
+//    bracket-attribute presence, and an evaluation context. It has NO field for a hostname, URL, or
+//    free text, and lint REJECTS any string value that is not a known ARIA role or attribute name.
+//    That is what makes a site-rule impossible to express — a pack cannot say "on example.com".
+//  • Zero LLM at runtime; packs are pure data; loads are deterministic (sorted filenames).
+//  • A missing/invalid pack is a LOUD failure listing the lint reasons — never silently skipped.
+//
+// This module is PURE (no fs beyond the loader) and side-effect-free so draft.ts can inject packs
+// for tests. loadPatternPacks reads the two shipped dirs by default.
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSnapshot } from '../playwright/snapshot.js';
+// ── ALLOW-LISTS (documented constants — the ENTIRE structural vocabulary a trigger may name) ──
+// A trigger string is legal iff it is one of these. Anything else (a hostname, a URL, a product
+// word, a UI label) is a NAMED lint rejection. Keep these lists as the single source of truth;
+// growing coverage = adding a role here + a pack entry, never a code branch.
+// The WAI-ARIA role vocabulary our snapshots actually surface (playwright-cli accessibility tree).
+// Superset of the roles the engine already switches on (CONTROL_ROLES, OVERLAY_ROLES,
+// REVEAL_CHILD_ROLES, columnheader/table/main/option/…) plus the common landmark/structure roles
+// from the WAI-ARIA Authoring Practices that a div-soup fixture is described in terms of. `generic`
+// is IN on purpose: a role-less div-soup portal snapshots as `generic`, and matching it is exactly
+// the coverage gap packs exist to close.
+export const ARIA_ROLES = new Set([
+    // landmarks / document structure
+    'main', 'navigation', 'banner', 'contentinfo', 'complementary', 'region', 'search', 'form',
+    'article', 'document', 'application', 'group', 'generic', 'presentation', 'none',
+    // widgets / interactive
+    'button', 'link', 'textbox', 'searchbox', 'combobox', 'spinbutton', 'checkbox', 'radio',
+    'switch', 'slider', 'option', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'tab',
+    'treeitem', 'listbox', 'menu', 'menubar', 'tablist', 'tree', 'radiogroup',
+    // overlays / dialogs / status
+    'dialog', 'alertdialog', 'tooltip', 'alert', 'status', 'progressbar',
+    // collections / tabular / grid
+    'list', 'listitem', 'table', 'row', 'rowgroup', 'cell', 'gridcell', 'columnheader',
+    'rowheader', 'grid', 'treegrid', 'heading', 'img', 'figure', 'separator',
+    'paragraph', 'blockquote', 'code', 'time', 'definition', 'term',
+]);
+// ARIA state/property attribute NAMES a trigger may test for PRESENCE of (bracket attributes in a
+// snapshot line, e.g. `[aria-sort=ascending]`). Names only — a trigger tests that the attribute is
+// PRESENT, never its value (a value could smuggle in free text). The set mirrors the WAI-ARIA
+// state/property vocabulary; `aria-sort` is the one the core already reads (sortable columnheader).
+export const ARIA_ATTRS = new Set([
+    'aria-sort', 'aria-expanded', 'aria-selected', 'aria-checked', 'aria-pressed',
+    'aria-current', 'aria-haspopup', 'aria-modal', 'aria-disabled', 'aria-hidden',
+    'aria-readonly', 'aria-required', 'aria-multiselectable', 'aria-level', 'aria-orientation',
+]);
+// Evaluation CONTEXT: which node list the engine feeds a trigger. These are the two hook sites plus
+// the interior-synthesis candidate set — closed enum, each a real hook in draft.ts.
+export const TRIGGER_CONTEXTS = ['diff.added', 'overlay', 'landing'];
+// The CLOSED effect set (mirrors program-spec §Phase 2). A pack `type` picks the effect its trigger
+// fires. Adding a third would be a deliberate CORE increment, never a pack.
+export const PACK_TYPES = ['overlay-open', 'value-domain'];
+// ── LINT ──
+// JSON-schema-style validation IN CODE (no new dep) + forbidden-value scan + fixture execution.
+// Returns [] when clean; otherwise a list of NAMED reasons (the loud-failure message).
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Validate ONE pack entry. Pure. Every failure is a specific, named reason (no generic "invalid").
+ *  Order: shape → forbidden-value scan (roles/attrs) → fixture execution. */
+export function lintPackEntry(raw) {
+    const errs = [];
+    if (!isPlainObject(raw))
+        return ['entry is not a JSON object'];
+    // ── shape ──
+    if (typeof raw.name !== 'string' || !SLUG_RE.test(raw.name))
+        errs.push(`"name" must be a kebab-case slug (got ${JSON.stringify(raw.name)})`);
+    if (typeof raw.version !== 'number' || !Number.isInteger(raw.version) || raw.version < 1)
+        errs.push(`"version" must be an integer ≥1 (got ${JSON.stringify(raw.version)})`);
+    if (typeof raw.type !== 'string' || !PACK_TYPES.includes(raw.type))
+        errs.push(`"type" must be one of ${PACK_TYPES.join(' | ')} (got ${JSON.stringify(raw.type)})`);
+    if (typeof raw.evidence !== 'string' || !raw.evidence.trim())
+        errs.push('"evidence" must be a non-empty one-line provenance string');
+    // ── trigger shape + forbidden-value scan ──
+    const trig = raw.trigger;
+    if (!isPlainObject(trig)) {
+        errs.push('"trigger" must be an object');
+    }
+    else {
+        if (typeof trig.context !== 'string' || !TRIGGER_CONTEXTS.includes(trig.context))
+            errs.push(`trigger.context must be one of ${TRIGGER_CONTEXTS.join(' | ')} (got ${JSON.stringify(trig.context)})`);
+        if (trig.root !== undefined) {
+            if (!isPlainObject(trig.root) || typeof trig.root.role !== 'string') {
+                errs.push('trigger.root, when present, must be { role, attr? }');
+            }
+            else {
+                if (!ARIA_ROLES.has(trig.root.role))
+                    errs.push(`trigger.root.role ${JSON.stringify(trig.root.role)} is not a known ARIA role — hostnames/URLs/text are forbidden; only ARIA roles are allowed`);
+                if (trig.root.attr !== undefined && (typeof trig.root.attr !== 'string' || !ARIA_ATTRS.has(trig.root.attr)))
+                    errs.push(`trigger.root.attr ${JSON.stringify(trig.root.attr)} is not a known ARIA attribute name`);
+            }
+        }
+        if (!Array.isArray(trig.contains) || trig.contains.length === 0) {
+            errs.push('trigger.contains must be a non-empty array of predicates');
+        }
+        else {
+            trig.contains.forEach((p, i) => {
+                if (!isPlainObject(p) || typeof p.role !== 'string') {
+                    errs.push(`trigger.contains[${i}] must be { role, min?, attr? }`);
+                    return;
+                }
+                if (!ARIA_ROLES.has(p.role))
+                    errs.push(`trigger.contains[${i}].role ${JSON.stringify(p.role)} is not a known ARIA role — hostnames/URLs/text are forbidden; only ARIA roles are allowed`);
+                if (p.min !== undefined && (typeof p.min !== 'number' || !Number.isInteger(p.min) || p.min < 1))
+                    errs.push(`trigger.contains[${i}].min must be an integer ≥1 (got ${JSON.stringify(p.min)})`);
+                if (p.attr !== undefined && (typeof p.attr !== 'string' || !ARIA_ATTRS.has(p.attr)))
+                    errs.push(`trigger.contains[${i}].attr ${JSON.stringify(p.attr)} is not a known ARIA attribute name`);
+            });
+        }
+    }
+    // ── fixture shape ──
+    const fx = raw.fixture;
+    if (!isPlainObject(fx)) {
+        errs.push('"fixture" is required — { snapshot, expect }');
+    }
+    else {
+        if (typeof fx.snapshot !== 'string' || !fx.snapshot.trim())
+            errs.push('fixture.snapshot must be a non-empty snapshot literal');
+        if (fx.expect !== 'matched' && fx.expect !== 'unmatched')
+            errs.push('fixture.expect must be "matched" or "unmatched"');
+    }
+    // ── fixture EXECUTION (only when shape is otherwise clean, so we don't run a malformed trigger) ──
+    if (errs.length === 0) {
+        const pack = raw;
+        const nodes = parseSnapshot(fx.snapshot);
+        const got = evaluateTrigger(pack.trigger, nodes) ? 'matched' : 'unmatched';
+        if (got !== fx.expect)
+            errs.push(`fixture failed: trigger evaluated to "${got}" but fixture.expect is "${fx.expect}"`);
+    }
+    return errs;
+}
+// ── TRIGGER EVALUATOR ──
+// Pure: given a trigger + the evidence nodes for its context, return match/no-match. Uses the SAME
+// nearest-lower-depth containment idiom as infer.ts (insideOverlay / subtreeFolds' parent walk) so a
+// `contains` predicate counts only nodes genuinely INSIDE the matched root subtree.
+const BRACKET = (raw, attr) => new RegExp(`\\[${attr}(?:[=\\]])`).test(raw);
+const attrOk = (n, attr) => attr === undefined || BRACKET(n.raw, attr);
+/** Is node `desc` a descendant of node at index `rootIdx` in the flat depth-ordered list? A node is
+ *  in the subtree iff it comes after rootIdx and every intervening depth stays > root depth (the
+ *  moment depth drops back to ≤ root's, the subtree ended). Same nearest-lower-depth reasoning as
+ *  insideOverlay, expressed forward. */
+function subtreeEnd(nodes, rootIdx) {
+    const rootDepth = nodes[rootIdx].depth;
+    let end = rootIdx + 1;
+    while (end < nodes.length && nodes[end].depth > rootDepth)
+        end++;
+    return end; // exclusive
+}
+/** Count nodes matching a predicate within [lo, hi). */
+function countMatches(nodes, lo, hi, p) {
+    let c = 0;
+    for (let i = lo; i < hi; i++)
+        if (nodes[i].role === p.role && attrOk(nodes[i], p.attr))
+            c++;
+    return c;
+}
+/** Do ALL contains-predicates hold inside [lo, hi)? */
+function allContain(nodes, lo, hi, preds) {
+    return preds.every((p) => countMatches(nodes, lo, hi, p) >= (p.min ?? 1));
+}
+export function evaluateTrigger(trigger, nodes) {
+    if (!nodes.length)
+        return false;
+    const preds = trigger.contains;
+    // No root declared → the whole list is one root subtree.
+    if (!trigger.root)
+        return allContain(nodes, 0, nodes.length, preds);
+    // Root declared → try each node that matches the root role/attr; a match on ANY root subtree fires.
+    const { role, attr } = trigger.root;
+    for (let i = 0; i < nodes.length; i++) {
+        if (nodes[i].role !== role || !attrOk(nodes[i], attr))
+            continue;
+        const end = subtreeEnd(nodes, i);
+        // predicates count DESCENDANTS (exclude the root itself → i+1).
+        if (allContain(nodes, i + 1, end, preds))
+            return true;
+    }
+    return false;
+}
+// ── LOADER ──
+// Deterministic (sorted filenames) load of the two shipped dirs. A file that isn't valid JSON, or an
+// entry that fails lint, throws a LOUD error naming the file + reasons — never silently skipped.
+// The shipped pack dirs, resolved relative to THIS module so they work from src (tsx) and dist.
+// src/explorer/patterns.ts → ../../packs/patterns/{core,proposed}; dist/explorer → same relative
+// (packs is not compiled, it ships as data). readdir tolerates a missing dir (returns []).
+//
+// TEST-HYGIENE GUARD (Task-1 review flag, Task 3): draftFromEffects's default param is
+// `loadPatternPacks()` — every one of the ~100 existing draftFromEffects call-sites across the test
+// suite that doesn't pass packs explicitly hits this default. Once a real core pack exists
+// (date-picker-divsoup below), that default would silently start loading it into every unrelated
+// fixture test, coupling them to core-pack content they were never written against. Fix centrally,
+// here, not per call-site: under vitest (`process.env.VITEST`, set by the runner itself — no config
+// needed) the default resolves to NO dirs (packs = []), so a test gets real packs ONLY when it asks
+// for them (loadPatternPacks(dirs) with an explicit dir, or draftFromEffects(effects, packs) with an
+// explicit pack array — both bypass this default entirely). Production (webnav CLI / MCP) is never
+// running under vitest, so it always sees the real shipped dirs.
+function defaultPackDirs() {
+    if (process.env.VITEST)
+        return [];
+    const here = dirname(fileURLToPath(import.meta.url));
+    const root = join(here, '..', '..'); // repo root from src/explorer OR dist/explorer
+    return [join(root, 'packs', 'patterns', 'core'), join(root, 'packs', 'patterns', 'proposed')];
+}
+/** Load every `*.json` pack entry from the given dirs (default = the two shipped dirs), sorted by
+ *  filename for determinism. Each file holds ONE entry (object) OR an array of entries. Throws on the
+ *  first invalid file/entry with a message listing the lint failures (loud, per the plan). */
+export function loadPatternPacks(dirs = defaultPackDirs()) {
+    const out = [];
+    for (const dir of dirs) {
+        let files;
+        try {
+            files = readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+        }
+        catch {
+            continue;
+        } // missing dir → nothing to load (not an error)
+        for (const file of files) {
+            const path = join(dir, file);
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch (e) {
+                throw new Error(`pattern pack ${path}: not valid JSON — ${e.message}`);
+            }
+            const entries = Array.isArray(parsed) ? parsed : [parsed];
+            entries.forEach((entry, i) => {
+                const reasons = lintPackEntry(entry);
+                if (reasons.length) {
+                    const where = Array.isArray(parsed) ? `${path}[${i}]` : path;
+                    throw new Error(`pattern pack ${where} failed lint:\n  - ${reasons.join('\n  - ')}`);
+                }
+                out.push({ ...entry, source: path });
+            });
+        }
+    }
+    return out;
+}
+// ── DRAFT-SIDE HELPERS (thin, so draft.ts wiring stays a one-liner per hook) ──
+/** Hook 1 (overlay-open): did ANY overlay-open pack trigger match these diff.added nodes? Called
+ *  ONLY when the built-in openedOverlay detection declined — a match flips detection true. */
+export function packDetectsOverlay(packs, addedNodes) {
+    return packs.some((p) => p.type === 'overlay-open' && evaluateTrigger(p.trigger, addedNodes));
+}
+/** Hook 2 (value-domain): the set of NODE NAMES a value-domain pack marks as value data within the
+ *  given candidate nodes. A node joins the excluded set iff it sits inside a firing trigger's matched
+ *  subtree (the value grid), so its name never becomes an affordance / never anchors a fingerprint.
+ *  Returns names (callers filter by name, matching enumeratedNames/templateFolds.gatedNames). */
+export function packValueNames(packs, nodes) {
+    const names = new Set();
+    for (const p of packs) {
+        if (p.type !== 'value-domain')
+            continue;
+        for (const idx of matchedSubtreeIndices(p.trigger, nodes)) {
+            const nm = nodes[idx].name;
+            if (nm && nm.trim())
+                names.add(nm);
+        }
+    }
+    return names;
+}
+/** Indices of every node inside a firing trigger's matched root subtree (empty when it doesn't
+ *  fire). Rootless trigger → the whole list. Root trigger → every matching root's subtree. */
+function matchedSubtreeIndices(trigger, nodes) {
+    if (!nodes.length || !evaluateTrigger(trigger, nodes))
+        return [];
+    if (!trigger.root)
+        return nodes.map((_, i) => i);
+    const { role, attr } = trigger.root;
+    const acc = [];
+    for (let i = 0; i < nodes.length; i++) {
+        if (nodes[i].role !== role || !attrOk(nodes[i], attr))
+            continue;
+        const end = subtreeEnd(nodes, i);
+        if (allContain(nodes, i + 1, end, trigger.contains))
+            for (let j = i + 1; j < end; j++)
+                acc.push(j);
+    }
+    return acc;
+}

package/dist/explorer/shadow.d.ts

@@ -0,0 +1,3 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+import type { DeclaredShadow } from '../mapstore/types.js';
+export declare function extractShadow(nodes: SnapNode[]): DeclaredShadow;

package/dist/explorer/shadow.js

@@ -0,0 +1,95 @@
+import { insideOverlay } from './infer.js';
+// Layer 2 — extract a page's DECLARED domain shadow as EVIDENCE (#5a: webnav records what the
+// page declares, it NEVER interprets). Everything here is a verbatim string read from the
+// snapshot; webnav does not name an entity, assert a relationship, or guess a field's meaning.
+// The calling agent reads the shadow and reconstructs the domain model itself.
+//
+// Discipline (the hard line, review-bounded): we extract ONLY durable STRUCTURE with a real ARIA
+// role — `columnheader` for table columns, `heading` for a section title, real `textbox`/
+// `combobox`/`checkbox`/`searchbox` for filters — and never a DATA value (a record count, an
+// enumerated overlay option). We deliberately do NOT infer filters from a `generic`
+// label paired with a `generic [cursor=pointer]` div (a common custom-dropdown pseudo-select
+// pattern) — that would be LAYOUT inference, which #5a forbids. Skipping honest-but-unobservable
+// structure beats guessing.
+// Design: docs/superpowers/specs/2026-06-13-learning-the-core-design.md (Layer 2).
+const FILTER_ROLE = {
+    textbox: 'text', searchbox: 'text', combobox: 'select', checkbox: 'checkbox',
+};
+/** Strip decorative icon-font glyphs (Unicode Private Use Areas) and collapse whitespace from a
+ *  declared name. These are rendering artifacts (Font Awesome sort/icon codepoints some apps
+ *  append to headers/buttons), NOT semantic text — removing them is the same class of cleanup as
+ *  trimming a trailing space, never interpretation (#5a). Returns '' for a glyph-only name (e.g.
+ *  the select-all checkbox column). */
+const cleanText = (s) => (s ?? '').replace(/[\u{E000}-\u{F8FF}\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]/gu, '').replace(/\s+/g, ' ').trim();
+/** The nearest preceding `heading` node before index `idx` (cleaned name), or null. */
+function precedingHeading(nodes, idx) {
+    for (let i = idx - 1; i >= 0; i--) {
+        if (nodes[i].role === 'heading') {
+            const h = cleanText(nodes[i].name);
+            if (h)
+                return h;
+        }
+    }
+    return null;
+}
+// Read the shadow from a page's CORE nodes (Task 10) — the durable, data-separated structure.
+// A record COUNT is NOT extracted: it is a DATA value (changes with the rows), not structure
+// (rule 2, 2026-07-10). `recordCount` stays on DeclaredShadow only for legacy stored data; nothing
+// populates it here. There is also NO sub-tab option: naming a site's topbar region by a literal
+// container name was a site-specific heuristic (deleted 2026-07-10) — sub-tabs surface as ordinary
+// declared links/tabs, never a hard-coded container lookup.
+export function extractShadow(nodes) {
+    const shadow = {};
+    // ── collections: each `table` → its columnheaders (cleaned) + nearest heading ──
+    const collections = [];
+    nodes.forEach((n, i) => {
+        if (n.role !== 'table')
+            return;
+        const tableDepth = n.depth;
+        const columns = [];
+        // columnheaders are descendants of this table (until the next node at <= table depth).
+        for (let j = i + 1; j < nodes.length; j++) {
+            if (nodes[j].depth <= tableDepth)
+                break;
+            if (nodes[j].role !== 'columnheader')
+                continue;
+            const col = cleanText(nodes[j].name);
+            if (col)
+                columns.push(col); // drop the empty select-all/checkbox column
+        }
+        if (!columns.length)
+            return; // a table with no named headers carries no shadow
+        // recordCount is DATA (rule 2) — left null; the field survives only for legacy stored maps.
+        collections.push({ heading: precedingHeading(nodes, i), columns, recordCount: null });
+    });
+    if (collections.length)
+        shadow.collections = collections;
+    // ── filters: ONLY real-ARIA controls with an accessible name (no div-soup inference), and
+    // NEVER one INSIDE an overlay — a filter control nested under a dialog/listbox is the overlay's
+    // own control (a value-picker search box) or an enumerated value, i.e. DATA, not the page's
+    // declared filter surface (rule 2). insideOverlay gates it out.
+    const filters = [];
+    const seenField = new Set();
+    nodes.forEach((n, i) => {
+        const control = FILTER_ROLE[n.role];
+        if (!control)
+            return;
+        if (insideOverlay(nodes, i))
+            return; // overlay control / enumerated value → data
+        const field = cleanText(n.name);
+        if (!field || seenField.has(field))
+            return;
+        seenField.add(field);
+        filters.push({ field, control });
+    });
+    if (filters.length)
+        shadow.filters = filters;
+    // ── createsEntity: the `Add` button's nearest enclosing heading (the owned entity panel) ──
+    const addIdx = nodes.findIndex((n) => n.role === 'button' && /\badd\b/i.test(cleanText(n.name)));
+    if (addIdx >= 0) {
+        const h = precedingHeading(nodes, addIdx);
+        if (h)
+            shadow.createsEntity = h;
+    }
+    return shadow;
+}

package/dist/graph/coverage.d.ts

@@ -0,0 +1,33 @@
+import type { State } from '../mapstore/types.js';
+export interface StateCoverage {
+    id: string;
+    counts: Record<AffKind, number>;
+    outgoing: number;
+    unexplored: string[];
+    deadEnd: boolean;
+}
+type AffKind = 'navigate' | 'reveal' | 'mutate' | 'input';
+export interface Coverage {
+    node: string;
+    entry: string | null;
+    states: StateCoverage[];
+    totals: Record<AffKind, number> & {
+        states: number;
+        edges: number;
+        unexplored: number;
+    };
+    orphans: string[];
+    deadEnds: string[];
+}
+/** Analyse a node's interior for completeness — counts, unexplored exits,
+ *  dead-ends, orphans. Pure: takes the states, returns a report. */
+export declare function analyseCoverage(node: string, states: State[]): Coverage;
+/** A flat indented outline of the whole interior. Read top-to-bottom and check
+ *  each state + its affordances against the real site. Unexplored exits get a
+ *  trailing "?", dead-ends/orphans are flagged, and a coverage summary leads. */
+export declare function toOutline(node: string, states: State[]): string;
+/** A Mermaid `stateDiagram-v2` of the interior. Paste into GitHub markdown,
+ *  mermaid.live, or any markdown viewer to render. Unexplored exits go to a
+ *  shared `unexplored` sink; the entry state gets the `[*]` start marker. */
+export declare function toMermaid(node: string, states: State[]): string;
+export {};

package/dist/graph/coverage.js

@@ -0,0 +1,155 @@
+// Human-scannable views of a site's interior, for answering "did we capture
+// everything?" WITHOUT the React Flow canvas. Two formats over the SAME stored
+// data (states + their typed affordance repertoire):
+//   • outline  — a flat indented dump you read top-to-bottom and eyeball against
+//                the real site.
+//   • mermaid  — a `stateDiagram-v2` you paste into GitHub / a markdown viewer /
+//                mermaid.live to get a rendered diagram with zero tooling.
+// Both surface COMPLETENESS cues: unexplored exits (→ ?), dead-ends, orphans, and
+// per-state coverage counts, so gaps in the capture are obvious.
+// ── shared traversal ────────────────────────────────────────────────────────
+// Flatten a state's affordance tree (recursing into reveal children) into a list
+// of [affordance, depth] so reveal overlays render indented under their opener.
+function flatten(affs, depth = 0) {
+    const out = [];
+    for (const a of affs) {
+        out.push({ aff: a, depth });
+        if (a.children && a.children.length)
+            out.push(...flatten(a.children, depth + 1));
+    }
+    return out;
+}
+// A navigate (or a childless reveal) that routes somewhere; reveals WITH children
+// don't route themselves (the children do).
+function routesSomewhere(a) {
+    if (a.kind === 'navigate')
+        return true;
+    if (a.kind === 'reveal')
+        return !(a.children && a.children.length);
+    return false;
+}
+/** Analyse a node's interior for completeness — counts, unexplored exits,
+ *  dead-ends, orphans. Pure: takes the states, returns a report. */
+export function analyseCoverage(node, states) {
+    const ids = new Set(states.map((s) => s.id));
+    const targeted = new Set(); // states something navigates to
+    const totals = { navigate: 0, reveal: 0, mutate: 0, input: 0, states: states.length, edges: 0, unexplored: 0 };
+    const perState = states.map((s) => {
+        const counts = { navigate: 0, reveal: 0, mutate: 0, input: 0 };
+        const unexplored = [];
+        let outgoing = 0;
+        for (const { aff } of flatten(s.affordances ?? [])) {
+            counts[aff.kind]++;
+            totals[aff.kind]++;
+            if (routesSomewhere(aff)) {
+                if (aff.toState) {
+                    outgoing++;
+                    totals.edges++;
+                    targeted.add(aff.toState);
+                }
+                else {
+                    // routes, but the destination isn't mapped → an unexplored exit.
+                    unexplored.push(aff.label);
+                    totals.unexplored++;
+                }
+            }
+        }
+        return { id: s.id, counts, outgoing, unexplored, deadEnd: outgoing === 0 };
+    });
+    // Entry = where the flow starts. Prefer a state literally named *login*/*home*/
+    // *search*/*index*/*start* (the conceptual entry, even if a back-edge like Logout
+    // targets it); else a state nothing navigates TO (a structural root); else the
+    // first state. This keeps the entry sensible on cyclic graphs.
+    const named = states.find((s) => /login|home|search|index|start/i.test(s.id));
+    const untargeted = states.filter((s) => !targeted.has(s.id));
+    const entry = (named ?? untargeted[0] ?? states[0])?.id ?? null;
+    // Orphans: a non-entry state nothing points to (a real structural gap).
+    const orphans = states
+        .filter((s) => s.id !== entry && !targeted.has(s.id))
+        .map((s) => s.id);
+    const deadEnds = perState.filter((s) => s.deadEnd).map((s) => s.id);
+    return { node, entry, states: perState, totals, orphans, deadEnds };
+}
+// ── outline (plain text, top-to-bottom) ──────────────────────────────────────
+const KIND_GLYPH = { navigate: '→', reveal: '▸', mutate: '·', input: '·' };
+/** A flat indented outline of the whole interior. Read top-to-bottom and check
+ *  each state + its affordances against the real site. Unexplored exits get a
+ *  trailing "?", dead-ends/orphans are flagged, and a coverage summary leads. */
+export function toOutline(node, states) {
+    const cov = analyseCoverage(node, states);
+    const lines = [];
+    const short = (id) => id.includes(':') ? id.slice(id.indexOf(':') + 1) : id;
+    lines.push(`# ${node} — interior coverage`);
+    lines.push(`${cov.totals.states} states · ${cov.totals.edges} mapped navigations · ` +
+        `${cov.totals.unexplored} unexplored exits · ` +
+        `${cov.totals.navigate} navigate / ${cov.totals.reveal} reveal / ` +
+        `${cov.totals.mutate} mutate / ${cov.totals.input} input`);
+    if (cov.deadEnds.length)
+        lines.push(`dead-ends (no outgoing nav): ${cov.deadEnds.map(short).join(', ')}`);
+    if (cov.orphans.length)
+        lines.push(`orphans (nothing navigates here): ${cov.orphans.map(short).join(', ')}`);
+    lines.push('');
+    for (const s of states) {
+        const sc = cov.states.find((x) => x.id === s.id);
+        const flags = [sc.deadEnd ? 'DEAD-END' : '', cov.orphans.includes(s.id) ? 'ORPHAN' : '']
+            .filter(Boolean).join(' ');
+        lines.push(`${short(s.id)}${flags ? '   [' + flags + ']' : ''}`);
+        for (const { aff, depth } of flatten(s.affordances ?? [])) {
+            const pad = '  '.repeat(depth + 1);
+            const glyph = KIND_GLYPH[aff.kind];
+            let line = `${pad}${glyph} ${aff.kind}: ${aff.label}`;
+            if (aff.kind === 'navigate' || (aff.kind === 'reveal' && routesSomewhere(aff))) {
+                line += aff.toState ? `  → ${short(aff.toState)}` : `  → ?  (UNEXPLORED)`;
+            }
+            else if (aff.kind === 'reveal') {
+                line += '  (opens overlay)';
+            }
+            if (aff.commit)
+                line += '  [commit · never auto-fired]';
+            lines.push(line);
+        }
+        if (!(s.affordances ?? []).length)
+            lines.push('  (no affordances captured)');
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+// ── mermaid (stateDiagram-v2) ─────────────────────────────────────────────────
+// Mermaid ids must be alnum/underscore. Map a state id to a safe token.
+function mid(id) {
+    const s = id.includes(':') ? id.slice(id.indexOf(':') + 1) : id;
+    return s.replace(/[^A-Za-z0-9_]/g, '_');
+}
+/** A Mermaid `stateDiagram-v2` of the interior. Paste into GitHub markdown,
+ *  mermaid.live, or any markdown viewer to render. Unexplored exits go to a
+ *  shared `unexplored` sink; the entry state gets the `[*]` start marker. */
+export function toMermaid(node, states) {
+    const cov = analyseCoverage(node, states);
+    const lines = ['stateDiagram-v2', `  %% ${node} interior`];
+    if (cov.entry)
+        lines.push(`  [*] --> ${mid(cov.entry)}`);
+    let usedUnexplored = false;
+    for (const s of states) {
+        // a readable label for the state node
+        const label = s.id.includes(':') ? s.id.slice(s.id.indexOf(':') + 1) : s.id;
+        lines.push(`  ${mid(s.id)} : ${label}`);
+        for (const { aff } of flatten(s.affordances ?? [])) {
+            if (!routesSomewhere(aff))
+                continue;
+            const lbl = aff.label.replace(/"/g, "'").replace(/:/g, ' ');
+            if (aff.toState) {
+                lines.push(`  ${mid(s.id)} --> ${mid(aff.toState)} : ${lbl}${aff.commit ? ' [commit]' : ''}`);
+            }
+            else {
+                usedUnexplored = true;
+                lines.push(`  ${mid(s.id)} --> unexplored : ${lbl} ?`);
+            }
+        }
+    }
+    if (usedUnexplored)
+        lines.push('  unexplored : ❓ unexplored');
+    // mark dead-ends as terminal so they read as flow ends
+    for (const id of cov.deadEnds)
+        lines.push(`  ${mid(id)} --> [*]`);
+    return lines.join('\n');
+}