@dikshanty94/webnav 0.2.0

package/dist/explorer/fingerprint-page.d.ts

@@ -0,0 +1,11 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+import type { DeclaredLink } from '../mapstore/record.js';
+/**
+ * The structural signature of a page: the sorted, deduped set of element ROLES
+ * present. Two pages of the same TYPE (a repo-detail vs another repo-detail)
+ * share a fingerprint; instances collapse. Purely mechanical — no judgment.
+ */
+export declare function fingerprintPage(nodes: SnapNode[]): string[];
+/** The navigable links a page declares: role 'link' WITH a url. `via` mirrors
+ *  deriveEdges' phrasing so analysed edges read consistently with the rest. */
+export declare function declaredLinks(nodes: SnapNode[]): DeclaredLink[];

package/dist/explorer/fingerprint-page.js

@@ -0,0 +1,19 @@
+/**
+ * The structural signature of a page: the sorted, deduped set of element ROLES
+ * present. Two pages of the same TYPE (a repo-detail vs another repo-detail)
+ * share a fingerprint; instances collapse. Purely mechanical — no judgment.
+ */
+export function fingerprintPage(nodes) {
+    return [...new Set(nodes.map((n) => n.role))].sort();
+}
+/** The navigable links a page declares: role 'link' WITH a url. `via` mirrors
+ *  deriveEdges' phrasing so analysed edges read consistently with the rest. */
+export function declaredLinks(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        if (n.role !== 'link' || !n.url)
+            continue;
+        out.push({ to: n.url, via: `follow link "${n.name ?? n.url}"` });
+    }
+    return out;
+}

package/dist/explorer/fingerprint.d.ts

@@ -0,0 +1,14 @@
+import type { State } from '../mapstore/types.js';
+import type { SnapNode } from '../playwright/snapshot.js';
+export type MatchResult = {
+    status: 'matched';
+    state: State;
+} | {
+    status: 'none';
+} | {
+    status: 'ambiguous';
+    states: State[];
+};
+/** A fingerprint token is "role" or "role:name". All tokens must be present. */
+export declare function hasToken(nodes: SnapNode[], token: string): boolean;
+export declare function matchState(nodes: SnapNode[], states: State[]): MatchResult;

package/dist/explorer/fingerprint.js

@@ -0,0 +1,18 @@
+/** A fingerprint token is "role" or "role:name". All tokens must be present. */
+export function hasToken(nodes, token) {
+    const [role, name] = token.split(':');
+    return nodes.some((n) => n.role === role && (name === undefined || n.name === name));
+}
+export function matchState(nodes, states) {
+    // An EMPTY fingerprint identifies nothing — `[].every()` is vacuously true, so it would match
+    // EVERY page and make every landing `ambiguous`. `_shell` (site chrome, no identity) and any
+    // degenerate/held-out stub carry `[]`; they are routing sources, never match candidates. Excise
+    // them here so no caller has to remember to (live finding: `_shell` in the walk's state set made
+    // a walk to a real report escalate `ambiguous` forever — [report, _shell]).
+    const hits = states.filter((s) => s.fingerprint.length > 0 && s.fingerprint.every((t) => hasToken(nodes, t)));
+    if (hits.length === 1)
+        return { status: 'matched', state: hits[0] };
+    if (hits.length === 0)
+        return { status: 'none' };
+    return { status: 'ambiguous', states: hits };
+}

package/dist/explorer/infer.d.ts

@@ -0,0 +1,85 @@
+import type { SnapNode } from '../playwright/snapshot.js';
+export interface UrlModel {
+    base: string[];
+    keyOf(url: string): string;
+}
+export declare const isOpaqueSeg: (s: string) => boolean;
+/** Site base = greedy leading segments shared by ≥80% of observed paths (e.g. version+tenant
+ *  `v3/9999`). keyOf strips query/hash + the base segments IN ORDER WHERE PRESENT, so a
+ *  pre-redirect URL missing the tenant still lands on the same key (the ghost merges).
+ *
+ *  A base POSITION whose value VARIES across observed URLs is a PARAM, not a locked literal: when
+ *  the position's dominant value is an opaque id AND ≥2 DISTINCT opaque ids appear there (a tenant
+ *  slot `{9999,8888}`), the whole position becomes a `{param}` base entry so BOTH tenants' identical
+ *  pages key to the SAME key (account-portable identity). Guard (reuses isOpaqueSeg): a position
+ *  whose varying values are MODULE WORDS (report/shop) is a genuinely different path, NOT a param —
+ *  it must stay distinct. `keyOf` emits `{param}` at a param position only when the actual segment
+ *  is opaque; a non-opaque segment there (a pre-redirect ghost missing the tenant) is left in place. */
+export declare function inferUrlModel(urls: string[]): UrlModel;
+export interface TemplateGroup {
+    template: string;
+    keys: string[];
+    paramPos: number;
+}
+/** PROPOSE param templates: keys of equal length differing at exactly one position (≥2 keys).
+ *  Purely positional — no digit/hex shape guessing. The caller DISPOSES structurally. */
+export declare function proposeTemplates(keys: string[]): TemplateGroup[];
+export type Face = Set<string>;
+export declare function faceOf(nodes: SnapNode[]): Face;
+export declare function jaccard(a: Face, b: Face): number;
+/** Containment |A∩B| / min(|A|,|B|): 1 when the smaller face is a subset of the larger. A
+ *  PARTIAL RENDER (a page captured before its data grid arrived) reads as contained-in the full
+ *  face even when jaccard is tiny (real case: 33-token subset of a 199-token list page → jaccard
+ *  0.17, containment 1.0), while a genuinely different page is not. Thresholds live at call sites. */
+export declare function containment(a: Face, b: Face): number;
+export declare const CONTROL_ROLES: ReadonlySet<string>;
+/** The sub-face of interactive-control tokens ('role:name' filtered to CONTROL_ROLES). */
+export declare function controlFace(f: Face): Face;
+export declare const OVERLAY_ROLES: ReadonlySet<string>;
+/** Walk ancestors by indent depth (same containment logic shadow.ts uses): the nearest
+ *  lower-depth predecessor chain; true if any ancestor's role declares an overlay. */
+export declare function insideOverlay(nodes: SnapNode[], idx: number): boolean;
+export declare function nodeIndexByName(nodes: SnapNode[], name: string): number;
+/** IDENTITY SCOPING (X3, OQ1): when a landing DECLARES a `main` landmark, a state's identity is
+ *  what's inside `main` — ancillary `complementary` rails / secondary nav that sit OUTSIDE `main`
+ *  are chrome, not identity, and must not pollute the face (a per-page-varying rail is neither
+ *  shell nor page-distinguishing). Same nearest-lower-depth containment idiom as `insideOverlay`:
+ *  keep a node iff its ancestor chain passes through a `main` (or it IS the `main`). NO `main`
+ *  declared → return nodes unchanged (declared-evidence-gated, never inferred). */
+export declare function mainScope(nodes: SnapNode[]): SnapNode[];
+/** Shell = tokens present on ≥minFrac of DISTINCT pages. Needs ≥4 pages to claim anything —
+ *  on tiny evidence a "shell" would just be coincidence. */
+export declare function extractShell(faces: Face[], minFrac?: number): Face;
+export interface SubtreeFold {
+    sig: string;
+    level: 'named' | 'abstracted';
+    count: number;
+    memberIndices: number[];
+    label: string;
+    unitSize: number;
+}
+/** Repeated sibling subtrees under a shared parent fold into typed sub-templates. Two signature
+ *  levels, bottom-up:
+ *    L1 (named)      role (+ "name" if role ∈ CONTROL_ROLES — control labels are the strongest
+ *                    template evidence) + '(' + sorted children L1 sigs + ')'.
+ *    L2 (abstracted) same, ALL names dropped — pure shape.
+ *  Fold rules PER PARENT (thresholds evidence-scaled, documented here):
+ *    (a) named ≥2      — ≥2 children sharing an L1 sig (identical repeated units; 'Expand drilldown' ×25).
+ *    (b) abstracted ≥3 — among the still-unfolded children, ≥3 sharing an L2 sig across ≥2 DISTINCT
+ *                        L1 sigs (the varying-name 'OS Remove'/'Revenue Remove' class). Higher bar:
+ *                        an abstract match is weaker evidence than an exact-label repeat.
+ *  A candidate unit must carry SOMETHING (a name or a control role somewhere in its subtree) — pure
+ *  unnamed `generic` wrappers fold to nothing and are skipped. A node already inside a named fold is
+ *  never reconsidered for abstracted folding. Pure + deterministic; no draft changes. */
+export declare function subtreeFolds(nodes: SnapNode[]): {
+    folds: SubtreeFold[];
+    foldedIndices: Set<number>;
+};
+export interface CoreResult {
+    tokens: Face;
+    provisional: string | null;
+}
+/** A state's durable face = tokens repeating across its settled landings (majority k-of-n,
+ *  0.6 — tolerates one A/B-noisy visit in three). ONE landing = no variance signal: keep all,
+ *  mark provisional; analyse surfaces the note as a record-next request. */
+export declare function templateCore(landingFaces: Face[]): CoreResult;

package/dist/explorer/infer.js

@@ -0,0 +1,370 @@
+// Observation-based inference primitives (settled 2026-07-10, structure-inference design).
+// Pure + deterministic; ZERO site knowledge (#5a). Thresholds are documented tunables.
+// Path segments of a URL. Accepts BOTH absolute (`https://h/v3/9999/x`) and RELATIVE
+// (`/v3/9999/x`) forms — snapshot link hrefs are usually relative, and keying them must
+// land on the same key as the absolute toUrl (else every sidebar link keys to `/` and no
+// from-anywhere shell edge ever resolves). A dummy base makes the relative parse succeed
+// without affecting the pathname.
+const segsOf = (url) => {
+    try {
+        return new URL(url, 'http://_').pathname.split('/').filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+};
+// A path segment that is an opaque INSTANCE id — all-digits or a long hex/uuid-ish token — vs a
+// meaningful MODULE word (report/dashboard/list). The design's sanctioned URL-SHAPE prior; site-
+// AGNOSTIC (no product tokens). `{param}` (an already-abstracted template slot) counts as opaque.
+// Lives here with the URL model (the canonical home for the word-vs-opaque distinction); draft.ts
+// imports it so both the base-inference param detection and the template dispose share one rule.
+export const isOpaqueSeg = (s) => s === PARAM || /^\d+$/.test(s) || /^[0-9a-f]{16,}$/i.test(s);
+const PARAM = '{param}';
+/** Site base = greedy leading segments shared by ≥80% of observed paths (e.g. version+tenant
+ *  `v3/9999`). keyOf strips query/hash + the base segments IN ORDER WHERE PRESENT, so a
+ *  pre-redirect URL missing the tenant still lands on the same key (the ghost merges).
+ *
+ *  A base POSITION whose value VARIES across observed URLs is a PARAM, not a locked literal: when
+ *  the position's dominant value is an opaque id AND ≥2 DISTINCT opaque ids appear there (a tenant
+ *  slot `{9999,8888}`), the whole position becomes a `{param}` base entry so BOTH tenants' identical
+ *  pages key to the SAME key (account-portable identity). Guard (reuses isOpaqueSeg): a position
+ *  whose varying values are MODULE WORDS (report/shop) is a genuinely different path, NOT a param —
+ *  it must stay distinct. `keyOf` emits `{param}` at a param position only when the actual segment
+ *  is opaque; a non-opaque segment there (a pre-redirect ghost missing the tenant) is left in place. */
+export function inferUrlModel(urls) {
+    let work = urls.map(segsOf);
+    const base = [];
+    for (;;) {
+        const nonEmpty = work.filter((p) => p.length);
+        if (!nonEmpty.length)
+            break;
+        const heads = new Map();
+        for (const p of nonEmpty)
+            heads.set(p[0], (heads.get(p[0]) ?? 0) + 1);
+        const [top, cnt] = [...heads.entries()].sort((a, b) => b[1] - a[1])[0];
+        // A VARYING opaque-id position → `{param}` base entry (≥2 distinct opaque values seen here).
+        // The dominant value must itself be opaque, else a mostly-constant word position with a couple
+        // of stray opaque ids would wrongly abstract. Consume the position from every path either way.
+        const distinctOpaque = new Set([...heads.keys()].filter(isOpaqueSeg));
+        if (isOpaqueSeg(top) && distinctOpaque.size >= 2) {
+            base.push(PARAM);
+            work = work.map((p) => (isOpaqueSeg(p[0]) ? p.slice(1) : p));
+            continue;
+        }
+        if (cnt < 0.8 * nonEmpty.length)
+            break;
+        base.push(top);
+        work = work.map((p) => (p[0] === top ? p.slice(1) : p));
+    }
+    const keyOf = (url) => {
+        let p = segsOf(url);
+        for (const b of base) {
+            if (b === PARAM) {
+                if (isOpaqueSeg(p[0]))
+                    p = [PARAM, ...p.slice(1)];
+            } // opaque seg → {param}
+            else if (p[0] === b)
+                p = p.slice(1); // literal base → strip
+        }
+        return '/' + p.join('/');
+    };
+    return { base, keyOf };
+}
+/** PROPOSE param templates: keys of equal length differing at exactly one position (≥2 keys).
+ *  Purely positional — no digit/hex shape guessing. The caller DISPOSES structurally. */
+export function proposeTemplates(keys) {
+    const bySig = new Map();
+    const parts = keys.map((k) => k.split('/').filter(Boolean));
+    for (let i = 0; i < parts.length; i++) {
+        for (let pos = 0; pos < parts[i].length; pos++) {
+            const sig = parts[i].length + ':' + pos + ':' + parts[i].map((s, j) => (j === pos ? '{param}' : s)).join('/');
+            const g = bySig.get(sig) ?? { keys: [], paramPos: pos, parts: parts[i] };
+            g.keys.push(keys[i]);
+            bySig.set(sig, g);
+        }
+    }
+    return [...bySig.values()].filter((g) => g.keys.length >= 2).map((g) => ({
+        template: '/' + g.parts.map((s, j) => (j === g.paramPos ? '{param}' : s)).join('/'),
+        keys: g.keys, paramPos: g.paramPos,
+    }));
+}
+export function faceOf(nodes) {
+    const f = new Set();
+    for (const n of nodes)
+        if (n.name && n.name.trim())
+            f.add(`${n.role}:${n.name}`);
+    return f;
+}
+export function jaccard(a, b) {
+    if (!a.size && !b.size)
+        return 1;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+/** Containment |A∩B| / min(|A|,|B|): 1 when the smaller face is a subset of the larger. A
+ *  PARTIAL RENDER (a page captured before its data grid arrived) reads as contained-in the full
+ *  face even when jaccard is tiny (real case: 33-token subset of a 199-token list page → jaccard
+ *  0.17, containment 1.0), while a genuinely different page is not. Thresholds live at call sites. */
+export function containment(a, b) {
+    if (!a.size || !b.size)
+        return a.size === b.size ? 1 : 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / Math.min(a.size, b.size);
+}
+// Interactive CONTROL roles — a template's SKELETON. Two instances of one page template share
+// what you can DO (buttons/fields/tabs) even when their text/link tokens are all instance data
+// (product names, prices, related items). Observational, no site tokens.
+export const CONTROL_ROLES = new Set(['button', 'textbox', 'combobox', 'searchbox', 'spinbutton', 'checkbox', 'tab']);
+/** The sub-face of interactive-control tokens ('role:name' filtered to CONTROL_ROLES). */
+export function controlFace(f) {
+    const out = new Set();
+    for (const t of f)
+        if (CONTROL_ROLES.has(t.slice(0, t.indexOf(':'))))
+            out.add(t);
+    return out;
+}
+// Roles that DECLARE a transient overlay container (WAI-ARIA). A node nested under one is
+// overlay content (a value being chosen, or the overlay's own controls) — never page structure.
+export const OVERLAY_ROLES = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tooltip']);
+/** Walk ancestors by indent depth (same containment logic shadow.ts uses): the nearest
+ *  lower-depth predecessor chain; true if any ancestor's role declares an overlay. */
+export function insideOverlay(nodes, idx) {
+    if (idx < 0 || idx >= nodes.length)
+        return false;
+    let cur = nodes[idx].depth;
+    for (let i = idx - 1; i >= 0; i--) {
+        if (nodes[i].depth < cur) {
+            if (OVERLAY_ROLES.has(nodes[i].role))
+                return true;
+            cur = nodes[i].depth;
+        }
+    }
+    return false;
+}
+export function nodeIndexByName(nodes, name) {
+    return nodes.findIndex((n) => n.name === name);
+}
+/** IDENTITY SCOPING (X3, OQ1): when a landing DECLARES a `main` landmark, a state's identity is
+ *  what's inside `main` — ancillary `complementary` rails / secondary nav that sit OUTSIDE `main`
+ *  are chrome, not identity, and must not pollute the face (a per-page-varying rail is neither
+ *  shell nor page-distinguishing). Same nearest-lower-depth containment idiom as `insideOverlay`:
+ *  keep a node iff its ancestor chain passes through a `main` (or it IS the `main`). NO `main`
+ *  declared → return nodes unchanged (declared-evidence-gated, never inferred). */
+export function mainScope(nodes) {
+    if (!nodes.some((n) => n.role === 'main'))
+        return nodes;
+    const out = [];
+    for (let idx = 0; idx < nodes.length; idx++) {
+        if (nodes[idx].role === 'main') {
+            out.push(nodes[idx]);
+            continue;
+        }
+        let cur = nodes[idx].depth, inMain = false;
+        for (let i = idx - 1; i >= 0 && !inMain; i--) {
+            if (nodes[i].depth < cur) {
+                if (nodes[i].role === 'main')
+                    inMain = true;
+                cur = nodes[i].depth;
+            }
+        }
+        if (inMain)
+            out.push(nodes[idx]);
+    }
+    return out;
+}
+/** Shell = tokens present on ≥minFrac of DISTINCT pages. Needs ≥4 pages to claim anything —
+ *  on tiny evidence a "shell" would just be coincidence. */
+export function extractShell(faces, minFrac = 0.8) {
+    if (faces.length < 4)
+        return new Set();
+    const count = new Map();
+    for (const f of faces)
+        for (const t of f)
+            count.set(t, (count.get(t) ?? 0) + 1);
+    const shell = new Set();
+    for (const [t, c] of count)
+        if (c >= minFrac * faces.length)
+            shell.add(t);
+    return shell;
+}
+// Tiny deterministic string hash (djb2 → 8 hex). No crypto import — sigs need only be stable
+// across runs and collision-resistant enough to key groups; they are not security material.
+function sigHash(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
+    return h.toString(16).padStart(8, '0');
+}
+// Longest common trailing word(s) across names. Returns '' when the names share no trailing word.
+// Anchors an abstracted fold's label ('OS Remove'/'Revenue Remove' → 'Remove').
+function commonTrailingWords(names) {
+    const wordLists = names.map((n) => n.trim().split(/\s+/));
+    const out = [];
+    for (let back = 1;; back++) {
+        const words = wordLists.map((w) => (w.length >= back ? w[w.length - back] : undefined));
+        if (words.some((w) => w === undefined) || new Set(words).size !== 1)
+            break;
+        out.unshift(words[0]);
+    }
+    return out.join(' ');
+}
+/** Repeated sibling subtrees under a shared parent fold into typed sub-templates. Two signature
+ *  levels, bottom-up:
+ *    L1 (named)      role (+ "name" if role ∈ CONTROL_ROLES — control labels are the strongest
+ *                    template evidence) + '(' + sorted children L1 sigs + ')'.
+ *    L2 (abstracted) same, ALL names dropped — pure shape.
+ *  Fold rules PER PARENT (thresholds evidence-scaled, documented here):
+ *    (a) named ≥2      — ≥2 children sharing an L1 sig (identical repeated units; 'Expand drilldown' ×25).
+ *    (b) abstracted ≥3 — among the still-unfolded children, ≥3 sharing an L2 sig across ≥2 DISTINCT
+ *                        L1 sigs (the varying-name 'OS Remove'/'Revenue Remove' class). Higher bar:
+ *                        an abstract match is weaker evidence than an exact-label repeat.
+ *  A candidate unit must carry SOMETHING (a name or a control role somewhere in its subtree) — pure
+ *  unnamed `generic` wrappers fold to nothing and are skipped. A node already inside a named fold is
+ *  never reconsidered for abstracted folding. Pure + deterministic; no draft changes. */
+export function subtreeFolds(nodes) {
+    const n = nodes.length;
+    // Tree via depth stack: parent of node i = nearest preceding node with lower depth (the
+    // containment idiom used everywhere). Root nodes (no lower-depth predecessor) get parent -1.
+    const parent = new Array(n).fill(-1);
+    const children = Array.from({ length: n }, () => []);
+    const roots = [];
+    const stack = [];
+    for (let i = 0; i < n; i++) {
+        while (stack.length && nodes[stack[stack.length - 1]].depth >= nodes[i].depth)
+            stack.pop();
+        if (stack.length) {
+            parent[i] = stack[stack.length - 1];
+            children[parent[i]].push(i);
+        }
+        else
+            roots.push(i);
+        stack.push(i);
+    }
+    // Bottom-up signatures + subtree size + content flag. Children always follow their parent at
+    // greater depth, so reverse index order is a valid post-order (child computed before parent).
+    const l1 = new Array(n), l2 = new Array(n);
+    const size = new Array(n).fill(1);
+    const hasContent = new Array(n).fill(false);
+    for (let i = n - 1; i >= 0; i--) {
+        const isControl = CONTROL_ROLES.has(nodes[i].role);
+        const self = hasContent[i] || (nodes[i].name != null && nodes[i].name.trim() !== '') || isControl;
+        hasContent[i] = self;
+        const kids = children[i];
+        const k1 = [], k2 = [];
+        for (const c of kids) {
+            k1.push(l1[c]);
+            k2.push(l2[c]);
+            size[i] += size[c];
+            if (hasContent[c])
+                hasContent[i] = true;
+        }
+        k1.sort();
+        k2.sort();
+        const label1 = nodes[i].role + (isControl && nodes[i].name ? '"' + nodes[i].name + '"' : '');
+        l1[i] = label1 + '(' + k1.join(',') + ')';
+        l2[i] = nodes[i].role + '(' + k2.join(',') + ')';
+    }
+    // All indices inside a subtree (root + descendants), document order.
+    const subtreeIndices = (root) => {
+        const acc = [];
+        const walk = (i) => { acc.push(i); for (const c of children[i])
+            walk(c); };
+        walk(root);
+        return acc;
+    };
+    // First control-role node WITH a name in a unit's subtree (document order) → its stable label.
+    const firstControlName = (root) => {
+        for (const i of subtreeIndices(root)) {
+            if (CONTROL_ROLES.has(nodes[i].role) && nodes[i].name && nodes[i].name.trim())
+                return nodes[i].name.trim();
+        }
+        return null;
+    };
+    const folds = [];
+    const foldedIndices = new Set();
+    const foldUnderParent = (kids) => {
+        const eligible = kids.filter((c) => hasContent[c]); // skip pure unnamed wrappers
+        // (a) NAMED: group by L1, groups ≥2.
+        const byL1 = new Map();
+        for (const c of eligible)
+            (byL1.get(l1[c]) ?? byL1.set(l1[c], []).get(l1[c])).push(c);
+        const claimed = new Set();
+        for (const [sig, members] of byL1) {
+            if (members.length < 2)
+                continue;
+            for (const m of members)
+                claimed.add(m);
+            const mi = [];
+            for (const m of members)
+                for (const idx of subtreeIndices(m)) {
+                    mi.push(idx);
+                    foldedIndices.add(idx);
+                }
+            folds.push({
+                sig: sigHash(sig), level: 'named', count: members.length, memberIndices: mi,
+                label: firstControlName(members[0]) ?? nodes[members[0]].role, unitSize: size[members[0]],
+            });
+        }
+        // (b) ABSTRACTED: among children NOT claimed by a named fold, group by L2; groups ≥3 with ≥2
+        //     distinct L1 sigs (varying names are the param slots).
+        const byL2 = new Map();
+        for (const c of eligible) {
+            if (claimed.has(c))
+                continue;
+            (byL2.get(l2[c]) ?? byL2.set(l2[c], []).get(l2[c])).push(c);
+        }
+        for (const [sig, members] of byL2) {
+            if (members.length < 3)
+                continue;
+            if (new Set(members.map((m) => l1[m])).size < 2)
+                continue; // identical units belong to named, not here
+            const mi = [];
+            for (const m of members)
+                for (const idx of subtreeIndices(m)) {
+                    mi.push(idx);
+                    foldedIndices.add(idx);
+                }
+            // Label = longest common trailing word of the members' distinguishing names, else unit role.
+            const names = [];
+            for (const m of members) {
+                const nm = firstControlName(m) ?? nodes[m].name;
+                if (nm && nm.trim())
+                    names.push(nm.trim());
+            }
+            const trailing = names.length === members.length ? commonTrailingWords(names) : '';
+            folds.push({
+                sig: sigHash(sig), level: 'abstracted', count: members.length, memberIndices: mi,
+                label: trailing || nodes[members[0]].role, unitSize: size[members[0]],
+            });
+        }
+    };
+    foldUnderParent(roots);
+    for (let i = 0; i < n; i++)
+        if (children[i].length)
+            foldUnderParent(children[i]);
+    return { folds, foldedIndices };
+}
+/** A state's durable face = tokens repeating across its settled landings (majority k-of-n,
+ *  0.6 — tolerates one A/B-noisy visit in three). ONE landing = no variance signal: keep all,
+ *  mark provisional; analyse surfaces the note as a record-next request. */
+export function templateCore(landingFaces) {
+    if (landingFaces.length === 1) {
+        return { tokens: new Set(landingFaces[0]), provisional: 'seen once — record another visit to separate structure from data' };
+    }
+    const need = Math.ceil(landingFaces.length * 0.6);
+    const count = new Map();
+    for (const f of landingFaces)
+        for (const t of f)
+            count.set(t, (count.get(t) ?? 0) + 1);
+    const tokens = new Set();
+    for (const [t, c] of count)
+        if (c >= need)
+            tokens.add(t);
+    return { tokens, provisional: null };
+}

package/dist/explorer/pattern-propose.d.ts

@@ -0,0 +1,27 @@
+import type { PatternPack } from './patterns.js';
+export interface UnknownLike {
+    kind: string;
+    evidence: string;
+    context: string;
+    extensionPoint: 'overlay-open' | 'value-domain' | 'core-design';
+}
+export interface ProposeResult {
+    pack: PatternPack | null;
+    lintReasons: string[];
+    coreDesignBoundary?: string;
+}
+/** Scaffold a PatternPack from one unknown. Pure — never touches disk. The returned pack's trigger
+ *  is a deliberate TODO (empty `contains`) so lintPackEntry FAILS on it (loud, expected) until the
+ *  agent fills in real predicates from the evidence. `core-design` unknowns get no pack at all —
+ *  the honest boundary: file a core-design issue with the fixture instead (docs/EXTENDING.md). */
+export declare function proposeFromUnknown(unknown: UnknownLike, name: string): ProposeResult;
+/** Parse `--from-unknown <path>#<index>` into its two parts. Throws a plain Error with a usage
+ *  hint on malformed input (cli.ts turns that into the standard {status:'error'} envelope). */
+export declare function parseFromUnknownArg(raw: string): {
+    path: string;
+    index: number;
+};
+/** Generate the `gh pr create` command an agent runs once the pack lints clean, re-analyse
+ *  resolves the unknown, and a grammar fixture test is added. Cites the unknown's evidence in the
+ *  PR body per the plan ("a generated body citing the evidence"). Prints only — NEVER auto-run. */
+export declare function ghPrCommand(pack: PatternPack, unknown: UnknownLike): string;

package/dist/explorer/pattern-propose.js

@@ -0,0 +1,81 @@
+import { lintPackEntry } from './patterns.js';
+// `evidence` is a flat, un-indented list of raw snapshot lines (draft.ts's evidenceOf — readable,
+// not necessarily a valid nesting). Wrapped as a rootless depth-0 fixture: every line becomes a
+// top-level `- <line>` so parseSnapshot accepts it; the agent adjusts nesting/root by hand if the
+// real trigger needs to scope containment (documented in the printed checklist).
+function evidenceToFixtureSnapshot(evidence) {
+    return evidence.split('\n').filter((l) => l.trim()).map((l) => `- ${l.trim()}`).join('\n');
+}
+// The context a pack's trigger should evaluate in, inferred from the unknown kind. Only the two
+// pack-scaffoldable extensionPoints reach here (core-design returns before this is called).
+const CONTEXT_BY_EXTENSION_POINT = {
+    'overlay-open': 'diff.added',
+    'value-domain': 'overlay',
+};
+/** Scaffold a PatternPack from one unknown. Pure — never touches disk. The returned pack's trigger
+ *  is a deliberate TODO (empty `contains`) so lintPackEntry FAILS on it (loud, expected) until the
+ *  agent fills in real predicates from the evidence. `core-design` unknowns get no pack at all —
+ *  the honest boundary: file a core-design issue with the fixture instead (docs/EXTENDING.md). */
+export function proposeFromUnknown(unknown, name) {
+    if (unknown.extensionPoint === 'core-design') {
+        return {
+            pack: null, lintReasons: [],
+            coreDesignBoundary: `this unknown (kind: ${unknown.kind}) is NOT expressible as a pattern pack — `
+                + `its extensionPoint is "core-design", meaning no existing pack TYPE (overlay-open | value-domain) can fix it. `
+                + `File a core-design issue upstream with this unknown's evidence + context attached as the reproducing fixture; `
+                + `do not hand-patch the engine.`,
+        };
+    }
+    const type = unknown.extensionPoint;
+    const pack = {
+        name,
+        version: 1,
+        type,
+        trigger: {
+            context: CONTEXT_BY_EXTENSION_POINT[unknown.extensionPoint],
+            // TODO(agent): narrow this — e.g. { role: 'generic' } for a role-less div-soup portal/grid.
+            contains: [], // TODO(agent): add >=1 { role, min?, attr? } predicate from the evidence below.
+        },
+        fixture: {
+            snapshot: evidenceToFixtureSnapshot(unknown.evidence),
+            expect: 'matched',
+        },
+        evidence: `${unknown.context} (scaffolded by dev pattern-propose from a graph-analyse unknown, kind=${unknown.kind})`,
+    };
+    return { pack, lintReasons: lintPackEntry(pack) };
+}
+/** Parse `--from-unknown <path>#<index>` into its two parts. Throws a plain Error with a usage
+ *  hint on malformed input (cli.ts turns that into the standard {status:'error'} envelope). */
+export function parseFromUnknownArg(raw) {
+    const hashIdx = raw.lastIndexOf('#');
+    if (hashIdx < 0)
+        throw new Error(`--from-unknown must be "<analyse-json-path>#<index>" (got ${JSON.stringify(raw)})`);
+    const path = raw.slice(0, hashIdx);
+    const index = Number(raw.slice(hashIdx + 1));
+    if (!path || !Number.isInteger(index) || index < 0)
+        throw new Error(`--from-unknown must be "<analyse-json-path>#<index>" with a non-negative integer index (got ${JSON.stringify(raw)})`);
+    return { path, index };
+}
+/** Generate the `gh pr create` command an agent runs once the pack lints clean, re-analyse
+ *  resolves the unknown, and a grammar fixture test is added. Cites the unknown's evidence in the
+ *  PR body per the plan ("a generated body citing the evidence"). Prints only — NEVER auto-run. */
+export function ghPrCommand(pack, unknown) {
+    const title = `pattern pack: ${pack.name}`;
+    const body = [
+        `## Pattern pack: \`${pack.name}\` (${pack.type})`,
+        '',
+        `Resolves an extension-loop unknown (kind: \`${unknown.kind}\`) that the core's structural inference could not classify:`,
+        '',
+        '```',
+        unknown.context,
+        '```',
+        '',
+        '### Evidence',
+        '```',
+        unknown.evidence,
+        '```',
+        '',
+        `Pack file: \`packs/patterns/core/${pack.name}.json\` (moved from \`proposed/\` after review). Lints clean, fixture passes, and a grammar test proves the resolved shape.`,
+    ].join('\n');
+    return `gh pr create --title ${JSON.stringify(title)} --body ${JSON.stringify(body)}`;
+}