explorbot 0.1.12 → 0.1.15

package/dist/src/utils/aria.js

@@ -1,3 +1,7 @@
+import { parse as parseYaml } from 'yaml';
+// ─────────────────────────────────────────────────────────────────
+// Roles
+// ─────────────────────────────────────────────────────────────────
 const INTERACTIVE_ROLES = new Set([
     'button',
     'link',
@@ -34,304 +38,329 @@ const INTERACTIVE_ROLES = new Set([
     'comboboxbutton',
     'gridcellbutton',
 ].map((role) => role.toLowerCase()));
-const IGNORED_CONTAINER_ROLES = new Set(['navigation']);
-const serializeChildContent = (node) => {
-    const children = node.rawChildren || node.children;
-    const parts = [];
-    for (const child of children) {
-        let part = child.role;
-        if (child.name)
-            part += ` "${child.name}"`;
-        const nested = serializeChildContent(child);
-        if (nested)
-            part += ` > ${nested}`;
-        parts.push(part);
-    }
-    return parts.join(', ');
-};
-const buildInteractiveEntry = (node) => {
-    if (!INTERACTIVE_ROLES.has(node.role)) {
-        return null;
-    }
-    const entry = { role: node.role };
-    if (node.name && node.name.trim() !== '') {
-        entry.name = node.name.trim();
-    }
-    if (node.value !== undefined && node.value !== null) {
-        const valueText = `${node.value}`.trim();
-        if (valueText !== '') {
-            entry.value = node.value;
-        }
-    }
-    for (const [key, value] of Object.entries(node.attributes)) {
-        if (value === undefined || value === null) {
-            continue;
-        }
-        if (value === '') {
-            continue;
-        }
-        entry[key] = value;
-    }
-    const hasData = Object.keys(entry).some((key) => key !== 'role');
-    const entryName = typeof entry.name === 'string' ? entry.name : '';
-    const hasValue = Object.prototype.hasOwnProperty.call(entry, 'value');
-    const isButtonOrLink = node.role === 'button' || node.role === 'link';
-    let shouldInclude = hasData;
-    if (!shouldInclude && hasValue) {
-        shouldInclude = true;
-    }
-    if (isButtonOrLink && !entryName && !hasValue) {
-        const resolved = resolveDisplayName(node);
-        if (resolved) {
-            entry.name = resolved;
-        }
-        else {
-            entry.unnamed = true;
-        }
-        shouldInclude = true;
-    }
-    if (!shouldInclude) {
-        return null;
-    }
-    return entry;
-};
+const IGNORED_ROLES = new Set(['navigation']);
+// ─────────────────────────────────────────────────────────────────
+// Tunables (knobs that change pipeline behavior)
+// ─────────────────────────────────────────────────────────────────
+const SIBLING_COLLAPSE_THRESHOLD = 50;
+const SIBLING_COLLAPSE_KEEP_EACH_SIDE = 5;
+// ─────────────────────────────────────────────────────────────────
+// STEP 1 · Parse: YAML text → AriaNode[]
+// ─────────────────────────────────────────────────────────────────
 const normalizeScalar = (input) => {
     let value = input.trim();
     if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
         value = value.slice(1, -1);
     }
     const lower = value.toLowerCase();
-    if (lower === 'true') {
+    if (lower === 'true')
         return true;
-    }
-    if (lower === 'false') {
+    if (lower === 'false')
         return false;
-    }
-    if (lower === 'null') {
+    if (lower === 'null')
         return null;
-    }
     return value;
 };
-const tokenizeAttributes = (input) => {
-    const tokens = [];
-    let current = '';
-    let inQuotes = false;
-    let quoteChar = '';
-    for (let i = 0; i < input.length; i += 1) {
-        const char = input[i];
-        if ((char === '"' || char === "'") && input[i - 1] !== '\\') {
-            if (inQuotes && quoteChar === char) {
-                inQuotes = false;
-                quoteChar = '';
-            }
-            else if (!inQuotes) {
-                inQuotes = true;
-                quoteChar = char;
-            }
-            current += char;
-            continue;
-        }
-        if (!inQuotes && (char === ' ' || char === ',')) {
-            if (current.trim() !== '') {
-                tokens.push(current.trim());
-            }
-            current = '';
-            continue;
-        }
-        current += char;
-    }
-    if (current.trim() !== '') {
-        tokens.push(current.trim());
+// Parse one YAML node label like:  `button "Save"`,  `textbox "Email" [focused]`,  `heading "Title" [level=2]`
+const parseLabel = (label) => {
+    if (!label)
+        return null;
+    const trimmed = label.trim();
+    const roleMatch = trimmed.match(/^(\w+)/);
+    if (!roleMatch)
+        return null;
+    const role = roleMatch[1].toLowerCase();
+    let rest = trimmed.slice(roleMatch[0].length);
+    let name;
+    const nameMatch = rest.match(/^\s*"((?:[^"\\]|\\.)*)"/) || rest.match(/^\s*'((?:[^'\\]|\\.)*)'/);
+    if (nameMatch) {
+        name = nameMatch[1];
+        rest = rest.slice(nameMatch[0].length);
     }
-    return tokens;
-};
-const parseAttributes = (input) => {
     const attributes = {};
-    const tokens = tokenizeAttributes(input);
-    for (const token of tokens) {
-        if (token === '') {
-            continue;
-        }
-        const separatorIndex = token.indexOf('=');
-        if (separatorIndex === -1) {
-            attributes[token.toLowerCase()] = true;
-            continue;
+    const attrMatch = rest.match(/\[([^\]]*)\]/);
+    if (attrMatch) {
+        for (const tok of attrMatch[1].split(/[\s,]+/).filter(Boolean)) {
+            const eq = tok.indexOf('=');
+            if (eq === -1) {
+                attributes[tok.toLowerCase()] = true;
+                continue;
+            }
+            attributes[tok.slice(0, eq).trim().toLowerCase()] = normalizeScalar(tok.slice(eq + 1));
         }
-        const key = token.slice(0, separatorIndex).trim().toLowerCase();
-        const valueRaw = token.slice(separatorIndex + 1).trim();
-        attributes[key] = normalizeScalar(valueRaw);
     }
-    return attributes;
+    return { role, name, attributes };
 };
-const parseHeader = (header) => {
-    if (!header) {
+const yamlItemToNode = (item) => {
+    if (typeof item === 'string') {
+        const label = parseLabel(item);
+        if (!label)
+            return null;
+        const node = { role: label.role, attributes: label.attributes, children: [] };
+        if (label.name && label.name.trim() !== '')
+            node.name = label.name.trim();
+        return node;
+    }
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return null;
+    const entries = Object.entries(item);
+    if (entries.length === 0)
         return null;
+    const [key, value] = entries[0];
+    const label = parseLabel(key);
+    if (!label)
+        return null;
+    const node = { role: label.role, attributes: label.attributes, children: [] };
+    if (label.name && label.name.trim() !== '')
+        node.name = label.name.trim();
+    if (Array.isArray(value)) {
+        node.children = value.map(yamlItemToNode).filter((n) => n !== null);
+        return node;
+    }
+    if (value === null || value === undefined)
+        return node;
+    const normalized = normalizeScalar(String(value));
+    if (normalized !== '' && normalized !== undefined)
+        node.value = normalized;
+    return node;
+};
+const parseSnapshot = (snapshot) => {
+    if (!snapshot)
+        return [];
+    let parsed;
+    try {
+        parsed = parseYaml(snapshot);
     }
-    let index = 0;
-    const length = header.length;
-    while (index < length && header[index] === ' ') {
-        index += 1;
+    catch {
+        return [];
     }
-    let roleEnd = index;
-    while (roleEnd < length) {
-        const char = header[roleEnd];
-        if (char === ' ' || char === '[' || char === '"' || char === "'") {
-            break;
-        }
-        roleEnd += 1;
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.map(yamlItemToNode).filter((n) => n !== null);
+};
+// ─────────────────────────────────────────────────────────────────
+// STEP 2 · Transforms: AriaNode[] → AriaNode[]
+//   Each is a pure function. Compose by stacking calls in the public API.
+// ─────────────────────────────────────────────────────────────────
+// Dissolve <navigation> wrappers into their children.
+const unwrapIgnored = (nodes) => nodes.flatMap((node) => {
+    const children = unwrapIgnored(node.children);
+    if (IGNORED_ROLES.has(node.role))
+        return children;
+    return [{ ...node, children }];
+});
+// Walk children to produce a synthetic label for naming icon-only buttons.
+const summarizeChildren = (children) => children
+    .map((child) => {
+    let part = child.role;
+    if (child.name)
+        part += ` "${child.name}"`;
+    const nested = summarizeChildren(child.children);
+    if (nested)
+        part += ` > ${nested}`;
+    return part;
+})
+    .join(', ');
+// Set node.name = "{img "icon"}" for buttons/links that have no name but do have children.
+// Recurses so nested buttons get named too. Uses ORIGINAL children for the summary, before pruning.
+const nameIconButtons = (nodes) => nodes.map((node) => {
+    const namedChildren = nameIconButtons(node.children);
+    if (node.name)
+        return { ...node, children: namedChildren };
+    if (node.role !== 'button' && node.role !== 'link')
+        return { ...node, children: namedChildren };
+    if (node.children.length === 0)
+        return { ...node, children: namedChildren };
+    return { ...node, name: `{${summarizeChildren(node.children)}}`, children: namedChildren };
+});
+// Drop containers that contribute nothing.
+//   keepNamed=true → also keep named non-interactive nodes (e.g. headings, named text).
+const dropEmpty = (nodes, opts = {}) => nodes.flatMap((node) => {
+    const children = dropEmpty(node.children, opts);
+    if (INTERACTIVE_ROLES.has(node.role))
+        return [{ ...node, children }];
+    if (children.length > 0)
+        return [{ ...node, children }];
+    if (opts.keepNamed && (node.name || node.value !== undefined))
+        return [{ ...node, children }];
+    return [];
+});
+// ─────────────────────────────────────────────────────────────────
+// STEP 3 · Render: AriaNode[] → text or flat entries
+// ─────────────────────────────────────────────────────────────────
+// One-line representation of a node. Stable attr order so diff comparisons are deterministic.
+const formatNode = (node) => {
+    let line = node.role;
+    if (node.name?.trim())
+        line += ` "${node.name.trim()}"`;
+    const attrStr = Object.keys(node.attributes)
+        .sort()
+        .map((k) => {
+        const v = node.attributes[k];
+        if (v === undefined || v === null || v === '')
+            return '';
+        if (v === true)
+            return k;
+        return `${k}=${v}`;
+    })
+        .filter(Boolean)
+        .join(' ');
+    if (attrStr)
+        line += ` [${attrStr}]`;
+    if (node.value !== undefined && node.value !== null) {
+        const text = String(node.value).trim();
+        if (text)
+            line += `: ${text}`;
     }
-    const role = header.slice(index, roleEnd).trim().toLowerCase();
-    if (!role) {
+    return line;
+};
+// Group consecutive same-role siblings.  [a,a,b,a,a,a] → [[a,a],[b],[a,a,a]]
+const groupByConsecutiveRole = (nodes) => nodes.reduce((groups, node) => {
+    const last = groups[groups.length - 1];
+    if (last && last[0].role === node.role) {
+        last.push(node);
+        return groups;
+    }
+    groups.push([node]);
+    return groups;
+}, []);
+// Large group of same-role siblings → first N + "...M omitted..." marker + last N.
+const collapseGroup = (group, depth) => {
+    if (group.length <= SIBLING_COLLAPSE_THRESHOLD) {
+        return group.map((node) => ({ node }));
+    }
+    const keep = SIBLING_COLLAPSE_KEEP_EACH_SIDE;
+    const omitted = group.length - keep * 2;
+    const indent = '  '.repeat(depth);
+    return [...group.slice(0, keep).map((node) => ({ node })), { placeholder: `${indent}- ...${omitted} similar "${group[0].role}" items omitted...` }, ...group.slice(-keep).map((node) => ({ node }))];
+};
+const collapseSiblingGroups = (nodes, depth) => groupByConsecutiveRole(nodes).flatMap((group) => collapseGroup(group, depth));
+// Tree → indented YAML text.
+const renderTree = (nodes, depth = 0) => collapseSiblingGroups(nodes, depth)
+    .map((entry) => {
+    if ('placeholder' in entry)
+        return entry.placeholder;
+    const { node } = entry;
+    const indent = '  '.repeat(depth);
+    const head = `${indent}- ${formatNode(node)}`;
+    if (node.children.length === 0)
+        return head;
+    return `${head}:\n${renderTree(node.children, depth + 1)}`;
+})
+    .join('\n');
+// Build the structured "entry" object for an interactive node, or null if not worth keeping.
+const nodeToEntry = (node) => {
+    if (!INTERACTIVE_ROLES.has(node.role))
         return null;
+    const entry = { role: node.role };
+    if (node.name?.trim())
+        entry.name = node.name.trim();
+    if (node.value !== undefined && node.value !== null) {
+        const text = String(node.value).trim();
+        if (text)
+            entry.value = node.value;
     }
-    let name;
-    const attributes = {};
-    index = roleEnd;
-    while (index < length) {
-        const char = header[index];
-        if (char === ' ') {
-            index += 1;
-            continue;
-        }
-        if (char === '"' || char === "'") {
-            const quoteChar = char;
-            index += 1;
-            let value = '';
-            while (index < length) {
-                const currentChar = header[index];
-                if (currentChar === quoteChar && header[index - 1] !== '\\') {
-                    index += 1;
-                    break;
-                }
-                value += currentChar;
-                index += 1;
-            }
-            if (!name) {
-                name = value;
-            }
-            continue;
-        }
-        if (char === '[') {
-            const end = header.indexOf(']', index);
-            const content = end === -1 ? header.slice(index + 1) : header.slice(index + 1, end);
-            const parsed = parseAttributes(content);
-            for (const [key, value] of Object.entries(parsed)) {
-                attributes[key] = value;
-            }
-            index = end === -1 ? length : end + 1;
+    for (const [key, value] of Object.entries(node.attributes)) {
+        if (value === undefined || value === null || value === '')
             continue;
-        }
-        break;
+        entry[key] = value;
     }
-    return { role, name, attributes };
-};
-const splitHeaderValue = (content) => {
-    let activeQuote = null;
-    let bracketDepth = 0;
-    for (let i = 0; i < content.length; i += 1) {
-        const char = content[i];
-        if ((char === '"' || char === "'") && content[i - 1] !== '\\') {
-            if (activeQuote === char) {
-                activeQuote = null;
-            }
-            else if (!activeQuote) {
-                activeQuote = char;
-            }
-            continue;
-        }
-        if (!activeQuote) {
-            if (char === '[') {
-                bracketDepth += 1;
-                continue;
-            }
-            if (char === ']') {
-                if (bracketDepth > 0) {
-                    bracketDepth -= 1;
-                }
-                continue;
-            }
-            if (char === ':') {
-                if (bracketDepth === 0) {
-                    const header = content.slice(0, i).trimEnd();
-                    const value = content.slice(i + 1).trimStart();
-                    return { header, value: value === '' ? null : value };
-                }
-            }
-        }
+    const isButtonOrLink = node.role === 'button' || node.role === 'link';
+    const hasContent = Object.keys(entry).length > 1;
+    if (isButtonOrLink && !hasContent) {
+        entry.unnamed = true;
+        return entry;
     }
-    return { header: content.trim(), value: null };
+    if (!hasContent)
+        return null;
+    return entry;
 };
-const pruneNodes = (nodes, keepNamed = false) => {
-    const result = [];
-    for (const node of nodes) {
-        const children = pruneNodes(node.children, keepNamed);
-        if (IGNORED_CONTAINER_ROLES.has(node.role)) {
-            result.push(...children);
-            continue;
-        }
-        const interactive = INTERACTIVE_ROLES.has(node.role);
-        if (!interactive && children.length === 0) {
-            if (!keepNamed || (!node.name && node.value === undefined)) {
-                continue;
-            }
-        }
-        result.push({ ...node, children, rawChildren: node.children });
-    }
-    return result;
+// Walk tree, emit one FlatEntry per interactive node. Path is dotted index from root.
+const flatten = (nodes) => {
+    const collect = (node, path) => {
+        const entry = nodeToEntry(node);
+        const here = entry ? [{ path, summary: formatNode(node), entry }] : [];
+        const fromChildren = node.children.flatMap((child, i) => collect(child, `${path}.${i}`));
+        return [...here, ...fromChildren];
+    };
+    return nodes.flatMap((node, i) => collect(node, String(i)));
 };
-const parseAriaSnapshot = (snapshot, keepNamed = false) => {
-    if (!snapshot) {
-        return [];
-    }
-    const roots = [];
-    const stack = [];
-    const lines = snapshot.split(/\r?\n/);
-    for (const line of lines) {
-        if (!line.trim()) {
-            continue;
-        }
-        const indentMatch = line.match(/^\s*/);
-        const indent = indentMatch ? indentMatch[0].length : 0;
-        const trimmed = line.slice(indent);
-        if (!trimmed.startsWith('-')) {
+// ─────────────────────────────────────────────────────────────────
+// STEP 4 · Diff: FlatEntry[] × FlatEntry[] → text
+// ─────────────────────────────────────────────────────────────────
+const countBy = (items) => items.reduce((map, item) => {
+    if (item === '')
+        return map;
+    map.set(item, (map.get(item) ?? 0) + 1);
+    return map;
+}, new Map());
+// Bag-style diff: any summary appearing more in one bag than the other becomes added/removed.
+const diffByCount = (before, after) => {
+    const added = [];
+    const removed = [];
+    const all = new Set([...before.keys(), ...after.keys()]);
+    for (const summary of all) {
+        const b = before.get(summary) ?? 0;
+        const a = after.get(summary) ?? 0;
+        for (let i = 0; i < a - b; i += 1)
+            added.push(summary);
+        for (let i = 0; i < b - a; i += 1)
+            removed.push(summary);
+    }
+    return { added, removed };
+};
+// When the same path has a different summary AND the per-summary totals haven't shifted,
+// treat it as a rename (one add + one remove). Catches "button text changed" cases that
+// the count-based diff would miss.
+const detectRenames = (prev, curr, prevTotals, currTotals) => {
+    const added = [];
+    const removed = [];
+    const prevByPath = new Map(prev.map((e) => [e.path, e.summary]));
+    const currByPath = new Map(curr.map((e) => [e.path, e.summary]));
+    for (const [path, beforeSummary] of prevByPath) {
+        const afterSummary = currByPath.get(path);
+        if (!afterSummary || afterSummary === beforeSummary)
             continue;
-        }
-        const content = trimmed.slice(1).trim();
-        if (content === '') {
+        const totalsAfter = (currTotals.get(afterSummary) ?? 0) === (prevTotals.get(afterSummary) ?? 0);
+        const totalsBefore = (currTotals.get(beforeSummary) ?? 0) === (prevTotals.get(beforeSummary) ?? 0);
+        if (!totalsAfter || !totalsBefore)
             continue;
-        }
-        const { header, value } = splitHeaderValue(content);
-        const parsedHeader = parseHeader(header);
-        if (!parsedHeader) {
+        const beforeElsewhere = curr.some((e) => e.path !== path && e.summary === beforeSummary);
+        const afterElsewhere = prev.some((e) => e.path !== path && e.summary === afterSummary);
+        if (beforeElsewhere && afterElsewhere)
             continue;
-        }
-        const node = {
-            role: parsedHeader.role,
-            attributes: { ...parsedHeader.attributes },
-            children: [],
-        };
-        if (parsedHeader.name && parsedHeader.name.trim() !== '') {
-            node.name = parsedHeader.name.trim();
-        }
-        if (value !== null) {
-            const normalizedValue = normalizeScalar(value);
-            if (normalizedValue !== '' && normalizedValue !== undefined) {
-                node.value = normalizedValue;
-            }
-        }
-        const depth = Math.floor(indent / 2);
-        while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
-            stack.pop();
-        }
-        if (stack.length === 0) {
-            roots.push(node);
-        }
-        else {
-            stack[stack.length - 1].node.children.push(node);
-        }
-        stack.push({ depth, node });
+        added.push(afterSummary);
+        removed.push(beforeSummary);
     }
-    return pruneNodes(roots, keepNamed);
+    return { added, removed };
+};
+const TOP_DIFF_ITEMS = 10;
+const formatDiffSection = (label, items) => {
+    const summary = countBy(items);
+    if (summary.size === 0)
+        return [`  ${label}: []`];
+    const sorted = Array.from(summary.entries()).sort(([aItem, aCount], [bItem, bCount]) => bCount - aCount || aItem.localeCompare(bItem));
+    const top = sorted.slice(0, TOP_DIFF_ITEMS);
+    const rest = sorted.slice(TOP_DIFF_ITEMS);
+    const lines = [`  ${label}:`];
+    for (const [item, count] of top) {
+        let suffix = '';
+        if (count > 1)
+            suffix = ` (x${count})`;
+        lines.push(`    - ${item}${suffix}`);
+    }
+    if (rest.length > 0) {
+        let restTotal = 0;
+        for (const [, count] of rest)
+            restTotal += count;
+        lines.push(`    + ${restTotal} more interactive elements`);
+    }
+    return lines;
+};
+const formatDiff = (added, removed) => {
+    if (added.length === 0 && removed.length === 0)
+        return null;
+    return ['ariaDiff:', ...formatDiffSection('added', added), ...formatDiffSection('removed', removed)].join('\n');
 };
 const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
 const findOverlayByCloseButton = (nodeList) => {
@@ -352,11 +381,7 @@ const findOverlayByCloseButton = (nodeList) => {
                 }
             }
         }
-        return {
-            detected: true,
-            type: 'dialog',
-            name: heading?.name || null,
-        };
+        return { detected: true, type: 'dialog', name: heading?.name || null };
     }
     for (const node of nodeList) {
         const inner = findOverlayByCloseButton(node.children);
@@ -365,126 +390,66 @@ const findOverlayByCloseButton = (nodeList) => {
     }
     return null;
 };
-export const detectFocusArea = (snapshot) => {
-    const nodes = parseAriaSnapshot(snapshot, true);
-    const findFocusArea = (nodeList) => {
-        for (const node of nodeList) {
-            if (node.role === 'dialog' || node.role === 'alertdialog') {
-                return {
-                    detected: true,
-                    type: 'dialog',
-                    name: node.name || null,
-                };
-            }
-            if (node.attributes.modal === true || node.attributes.modal === 'true') {
-                return {
-                    detected: true,
-                    type: 'modal',
-                    name: node.name || null,
-                };
-            }
-            const childResult = findFocusArea(node.children);
-            if (childResult) {
-                return childResult;
-            }
-        }
-        return null;
-    };
-    const result = findFocusArea(nodes);
-    if (result)
-        return result;
-    const fallback = findOverlayByCloseButton(nodes);
-    if (fallback?.name)
-        return fallback;
-    return { detected: false, type: null, name: null };
-};
-export const collectInteractiveNodes = (snapshot) => {
-    const nodes = parseAriaSnapshot(snapshot);
-    const result = [];
-    const visit = (node) => {
-        if (IGNORED_CONTAINER_ROLES.has(node.role)) {
-            node.children.forEach(visit);
-            return;
+const findDialogOrModal = (nodes) => {
+    for (const node of nodes) {
+        if (node.role === 'dialog' || node.role === 'alertdialog') {
+            return { detected: true, type: 'dialog', name: node.name || null };
         }
-        const entry = buildInteractiveEntry(node);
-        if (entry) {
-            result.push(entry);
+        if (node.attributes.modal === true || node.attributes.modal === 'true') {
+            return { detected: true, type: 'modal', name: node.name || null };
         }
-        node.children.forEach(visit);
-    };
-    nodes.forEach(visit);
-    return result;
-};
-const renderNodeLine = (role, name, attrs, value) => {
-    let line = role;
-    const displayName = name?.trim();
-    if (displayName)
-        line += ` "${displayName}"`;
-    const attrStr = Object.entries(attrs)
-        .filter(([, v]) => v !== undefined && v !== null && v !== '')
-        .map(([k, v]) => (v === true ? k : `${k}=${v}`))
-        .join(' ');
-    if (attrStr)
-        line += ` [${attrStr}]`;
-    if (value !== undefined && value !== null) {
-        const text = `${value}`.trim();
-        if (text)
-            line += `: ${text}`;
+        const child = findDialogOrModal(node.children);
+        if (child)
+            return child;
     }
-    return line;
+    return null;
 };
-const formatSummary = (node) => {
-    const role = typeof node.role === 'string' ? node.role : '';
-    if (!role)
+// ─────────────────────────────────────────────────────────────────
+// Public API — pipelines composed visibly, top-to-bottom
+// ─────────────────────────────────────────────────────────────────
+export const compactAriaSnapshot = (snapshot, keepNamed = false) => {
+    if (!snapshot)
         return '';
-    const name = typeof node.name === 'string' ? node.name : undefined;
-    const attrs = {};
-    for (const key of Object.keys(node)
-        .filter((k) => k !== 'role' && k !== 'name' && k !== 'value')
-        .sort()) {
-        attrs[key] = node[key];
-    }
-    const value = Object.prototype.hasOwnProperty.call(node, 'value') ? node.value : undefined;
-    return renderNodeLine(role, name, attrs, value);
+    let tree = parseSnapshot(snapshot);
+    tree = unwrapIgnored(tree);
+    tree = nameIconButtons(tree);
+    tree = dropEmpty(tree, { keepNamed });
+    return renderTree(tree);
 };
-const flattenInteractiveNodes = (snapshot) => {
-    const nodes = parseAriaSnapshot(snapshot);
-    const result = [];
-    const visit = (node, path) => {
-        if (!IGNORED_CONTAINER_ROLES.has(node.role)) {
-            const entry = buildInteractiveEntry(node);
-            if (entry) {
-                const summary = formatSummary(entry);
-                if (summary !== '') {
-                    result.push({ path, summary });
-                }
-            }
-        }
-        node.children.forEach((child, index) => {
-            const childPath = path === '' ? `${index}` : `${path}.${index}`;
-            visit(child, childPath);
-        });
+export const diffAriaSnapshots = (previous, current) => {
+    const flat = (snap) => {
+        let tree = parseSnapshot(snap);
+        tree = unwrapIgnored(tree);
+        tree = nameIconButtons(tree);
+        tree = dropEmpty(tree);
+        return flatten(tree);
     };
-    nodes.forEach((node, index) => {
-        visit(node, `${index}`);
-    });
-    return result;
+    const prev = flat(previous);
+    const curr = flat(current);
+    const prevTotals = countBy(prev.map((e) => e.summary));
+    const currTotals = countBy(curr.map((e) => e.summary));
+    const byCount = diffByCount(prevTotals, currTotals);
+    const renames = detectRenames(prev, curr, prevTotals, currTotals);
+    return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed]);
 };
-const buildCountMap = (items) => {
-    const map = new Map();
-    for (const item of items) {
-        if (item === '') {
-            continue;
-        }
-        map.set(item, (map.get(item) ?? 0) + 1);
-    }
-    return map;
+export const detectFocusArea = (snapshot) => {
+    let tree = parseSnapshot(snapshot);
+    tree = unwrapIgnored(tree);
+    tree = dropEmpty(tree, { keepNamed: true });
+    const direct = findDialogOrModal(tree);
+    if (direct)
+        return direct;
+    const fallback = findOverlayByCloseButton(tree);
+    if (fallback?.name)
+        return fallback;
+    return { detected: false, type: null, name: null };
 };
-const formatDiffItem = (item, count) => {
-    if (count > 1) {
-        return `${item} (x${count})`;
-    }
-    return item;
+export const collectInteractiveNodes = (snapshot) => {
+    let tree = parseSnapshot(snapshot);
+    tree = unwrapIgnored(tree);
+    tree = nameIconButtons(tree);
+    tree = dropEmpty(tree);
+    return flatten(tree).map((e) => e.entry);
 };
 export function extractFocusedElement(ariaSnapshot) {
     if (!ariaSnapshot)
@@ -502,12 +467,12 @@ export function extractFocusedElement(ariaSnapshot) {
             }
         }
     }
-    return {
-        role,
-        name,
-        ...(value && { value: value.trim() }),
-        ...(attributes.length > 0 && { attributes }),
-    };
+    const result = { role, name };
+    if (value)
+        result.value = value.trim();
+    if (attributes.length > 0)
+        result.attributes = attributes;
+    return result;
 }
 export function parseAriaLocator(ariaStr) {
     const trimmed = ariaStr.trim();
@@ -518,143 +483,3 @@ export function parseAriaLocator(ariaStr) {
         return null;
     return { role: match[1], text: match[2] };
 }
-export const diffAriaSnapshots = (previous, current) => {
-    const previousEntries = flattenInteractiveNodes(previous);
-    const currentEntries = flattenInteractiveNodes(current);
-    const previousTotals = buildCountMap(previousEntries.map((entry) => entry.summary));
-    const currentTotals = buildCountMap(currentEntries.map((entry) => entry.summary));
-    const added = [];
-    const removed = [];
-    const allSummaries = new Set([...previousTotals.keys(), ...currentTotals.keys()]);
-    for (const summary of allSummaries) {
-        const before = previousTotals.get(summary) ?? 0;
-        const after = currentTotals.get(summary) ?? 0;
-        if (after > before) {
-            for (let i = 0; i < after - before; i += 1) {
-                added.push(summary);
-            }
-        }
-        if (before > after) {
-            for (let i = 0; i < before - after; i += 1) {
-                removed.push(summary);
-            }
-        }
-    }
-    const previousByPath = new Map();
-    for (const entry of previousEntries) {
-        previousByPath.set(entry.path, entry.summary);
-    }
-    const currentByPath = new Map();
-    for (const entry of currentEntries) {
-        currentByPath.set(entry.path, entry.summary);
-    }
-    for (const [path, beforeSummary] of previousByPath.entries()) {
-        const afterSummary = currentByPath.get(path);
-        if (!afterSummary || afterSummary === beforeSummary) {
-            continue;
-        }
-        const totalsEqualAfter = (currentTotals.get(afterSummary) ?? 0) === (previousTotals.get(afterSummary) ?? 0);
-        const totalsEqualBefore = (currentTotals.get(beforeSummary) ?? 0) === (previousTotals.get(beforeSummary) ?? 0);
-        if (!totalsEqualAfter || !totalsEqualBefore) {
-            continue;
-        }
-        const beforeExistsElsewhere = currentEntries.some((entry) => entry.path !== path && entry.summary === beforeSummary);
-        const afterExistsElsewhere = previousEntries.some((entry) => entry.path !== path && entry.summary === afterSummary);
-        if (beforeExistsElsewhere && afterExistsElsewhere) {
-            continue;
-        }
-        added.push(afterSummary);
-        removed.push(beforeSummary);
-    }
-    if (added.length === 0 && removed.length === 0) {
-        return null;
-    }
-    const lines = ['ariaDiff:'];
-    const addedSummary = buildCountMap(added);
-    if (addedSummary.size === 0) {
-        lines.push('  added: []');
-    }
-    else {
-        lines.push('  added:');
-        Array.from(addedSummary.entries())
-            .sort(([a], [b]) => a.localeCompare(b))
-            .forEach(([item, count]) => {
-            lines.push(`    - ${formatDiffItem(item, count)}`);
-        });
-    }
-    if (removed.length === 0) {
-        lines.push('  removed: []');
-    }
-    else {
-        lines.push(`  removed: ${removed.length} interactive elements`);
-    }
-    return lines.join('\n');
-};
-const resolveDisplayName = (node) => {
-    if (node.name)
-        return node.name;
-    const isButtonOrLink = node.role === 'button' || node.role === 'link';
-    if (!isButtonOrLink)
-        return undefined;
-    const childContent = serializeChildContent(node);
-    if (childContent)
-        return `{${childContent}}`;
-    return undefined;
-};
-const SIBLING_COLLAPSE_THRESHOLD = 50;
-const SIBLING_COLLAPSE_KEEP_EACH_SIDE = 5;
-const serializeAriaNodes = (nodes, depth = 0) => {
-    const lines = [];
-    const collapsed = collapseSimilarSiblingRuns(nodes, depth);
-    for (const entry of collapsed) {
-        if (entry.placeholder) {
-            lines.push(entry.placeholder);
-            continue;
-        }
-        const node = entry.node;
-        const indent = '  '.repeat(depth);
-        let line = `${indent}- ${renderNodeLine(node.role, resolveDisplayName(node), node.attributes, node.value)}`;
-        if (node.children.length > 0) {
-            line += ':';
-        }
-        lines.push(line);
-        if (node.children.length > 0) {
-            lines.push(serializeAriaNodes(node.children, depth + 1));
-        }
-    }
-    return lines.join('\n');
-};
-const collapseSimilarSiblingRuns = (nodes, depth) => {
-    const result = [];
-    let i = 0;
-    while (i < nodes.length) {
-        const role = nodes[i].role;
-        let j = i;
-        while (j < nodes.length && nodes[j].role === role)
-            j++;
-        const runLength = j - i;
-        if (runLength > SIBLING_COLLAPSE_THRESHOLD) {
-            for (let k = i; k < i + SIBLING_COLLAPSE_KEEP_EACH_SIDE; k++) {
-                result.push({ node: nodes[k] });
-            }
-            const omitted = runLength - SIBLING_COLLAPSE_KEEP_EACH_SIDE * 2;
-            const indent = '  '.repeat(depth);
-            result.push({ placeholder: `${indent}- ...${omitted} similar "${role}" items omitted...` });
-            for (let k = j - SIBLING_COLLAPSE_KEEP_EACH_SIDE; k < j; k++) {
-                result.push({ node: nodes[k] });
-            }
-        }
-        else {
-            for (let k = i; k < j; k++)
-                result.push({ node: nodes[k] });
-        }
-        i = j;
-    }
-    return result;
-};
-export const compactAriaSnapshot = (snapshot, keepNamed = false) => {
-    if (!snapshot)
-        return '';
-    const nodes = parseAriaSnapshot(snapshot, keepNamed);
-    return serializeAriaNodes(nodes);
-};