@jitsusama/agentic-harness.core 0.1.0

package/dist/web/a11y/budget.js

@@ -0,0 +1,97 @@
+/**
+ * Keeping a page outline inside a response.
+ *
+ * The outline is the most-returned payload in the whole family:
+ * every read of a page answers with one, and so does every
+ * navigation and every action, because the page after the fact is
+ * how a caller knows what their click did. Lists have been
+ * budgeted since the beginning. The outline was not, and a page
+ * whose outline is small is only the common case, not the rule:
+ * one source file of eighteen thousand lines, each line a
+ * listitem with a button and a text node, renders two and a half
+ * megabytes of perfectly good outline. A wheel scroll returned
+ * all of it.
+ *
+ * So the same rule as everywhere else. The limit is a
+ * presentation default rather than a ceiling, whole lines survive
+ * rather than bytes, and anything cut says so and says how to go
+ * and get it. The page is not the answer's size: narrowing the
+ * view is always available, and it is cheaper than reading the
+ * whole thing and discarding it.
+ */
+import { withinLineBudget, } from "@jitsusama/agentic-harness.core/result";
+/**
+ * What an explicit read of a page spends on the outline.
+ *
+ * Generous, because somebody who asked to see the page wants the
+ * page: this fits a normal application view whole and only bites
+ * on the pathological ones.
+ */
+export const OUTLINE_BUDGET_BYTES = 16_384;
+/**
+ * What the page view after an action spends.
+ *
+ * Tighter, because this outline was not asked for. It is
+ * confirmation of what just happened, and the caller who wants
+ * the page in full can read it in full.
+ */
+export const ACTION_VIEW_BUDGET_BYTES = 4_096;
+/**
+ * The most an outline will spend, however large a budget is asked
+ * for.
+ *
+ * Every other limit here is a presentation default that a caller
+ * can raise, because nothing should cap what this package can
+ * find out. A budget is different: it is not a limit on the
+ * finding, it is a limit on what gets pasted into a context
+ * window, and the whole point of storing the remainder is that
+ * raising it is never the way to see more. Left open, one call
+ * asking for a hundred megabytes undoes the entire mechanism, and
+ * the model choosing the number is the one party with no idea
+ * what it costs. Four times the generous default, which no real
+ * page reaches.
+ */
+export const MAX_OUTLINE_BUDGET_BYTES = OUTLINE_BUDGET_BYTES * 4;
+/**
+ * The budget to actually spend, given what was asked for.
+ *
+ * Refuses nothing: a caller who asks for more than the ceiling
+ * gets the ceiling, and the citation then tells them the rest is
+ * queryable, which is what they wanted in the first place.
+ */
+export function outlineBudget(asked) {
+    if (asked === undefined)
+        return OUTLINE_BUDGET_BYTES;
+    return Math.max(1, Math.min(asked, MAX_OUTLINE_BUDGET_BYTES));
+}
+/**
+ * As much of an outline as the budget affords, and never none.
+ *
+ * The cutting is the general rule from agentic-harness.core's result
+ * module; what belongs to the page is the advice about what to do
+ * next, since narrowing a page read has its own vocabulary.
+ */
+export function withinOutlineBudget(rendered, budget) {
+    const view = withinLineBudget(rendered, budget);
+    return {
+        ...view,
+        ...(view.cut > 0
+            ? { elided: outlineElision(view.cut, view.total, budget) }
+            : {}),
+    };
+}
+/**
+ * Say what the budget cut, and how the caller reads it anyway.
+ *
+ * Every escape named here is one this tool family actually
+ * offers, because a suggestion that does not work is worse than
+ * no suggestion: it costs a call to find out.
+ */
+function outlineElision(cut, total, budget) {
+    return (`Cut ${cut.toLocaleString()} of ${total.toLocaleString()} outline ` +
+        `lines to fit the ${budget.toLocaleString()} byte budget. The page ` +
+        "is whole; this view is not. Narrow it rather than enlarging it: " +
+        "'only' reduces to landmarks, headings or interactive elements, " +
+        "'depth' keeps the top levels, 'within' reads one branch. Or raise " +
+        "'budget' to spend more of the response on it.");
+}

package/dist/web/a11y/focus.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What holds focus at this moment.
+ *
+ * Distinct from the keyboard walk, which presses Tab around the whole
+ * page and judges the journey. This answers the question asked
+ * between actions: after that click, that key, that navigation, where
+ * did focus end up? It moves nothing.
+ */
+/**
+ * Ask the page what holds focus, without moving it.
+ *
+ * Shipped as a source string because it declares helpers. The
+ * accessible name is read the cheap way, from the attributes and
+ * text that produce one, rather than from the accessibility tree:
+ * this has to answer between actions without a tree walk, and the
+ * name is only there to identify what is already known to be
+ * focused.
+ */
+export declare const FOCUS_PROBE = "(() => {\n  const active = () => {\n    // Focus inside a shadow root reads as the host from outside, so\n    // the chain is followed down to the element that really has it.\n    let el = document.activeElement;\n    let shadowed = false;\n    while (el && el.shadowRoot && el.shadowRoot.activeElement) {\n      el = el.shadowRoot.activeElement;\n      shadowed = true;\n    }\n    return { el: el, shadowed: shadowed };\n  };\n\n  const found = active();\n  const el = found.el;\n  if (!el) return undefined;\n\n  const tag = el.tagName ? el.tagName.toLowerCase() : \"unknown\";\n  const onBody = el === document.body || tag === \"html\";\n  const labelled = () => {\n    const aria = el.getAttribute && el.getAttribute(\"aria-label\");\n    if (aria) return aria.trim();\n    const by = el.getAttribute && el.getAttribute(\"aria-labelledby\");\n    if (by) {\n      const names = by.split(/\\s+/).map((id) => {\n        const target = document.getElementById(id);\n        return target ? (target.textContent || \"\").trim() : \"\";\n      });\n      const joined = names.filter(Boolean).join(\" \");\n      if (joined) return joined;\n    }\n    if (el.labels && el.labels.length > 0) {\n      return (el.labels[0].textContent || \"\").trim();\n    }\n    const own = (el.textContent || \"\").replace(/\\s+/g, \" \").trim();\n    if (own) return own.slice(0, 80);\n    const value = el.getAttribute && el.getAttribute(\"value\");\n    return value ? value.trim() : \"\";\n  };\n\n  const box = el.getBoundingClientRect ? el.getBoundingClientRect() : undefined;\n  const name = onBody ? \"\" : labelled();\n  const role = el.getAttribute && el.getAttribute(\"role\");\n  return {\n    tag: tag,\n    role: role || undefined,\n    name: name || undefined,\n    id: (el.id || undefined),\n    onBody: onBody,\n    inShadow: found.shadowed || undefined,\n    rect: box && (box.width > 0 || box.height > 0)\n      ? { x: box.x, y: box.y, width: box.width, height: box.height }\n      : undefined,\n  };\n})()";
+/** The element focus is on, as the page reports it. */
+export interface FocusHolder {
+    readonly tag: string;
+    readonly role?: string;
+    readonly name?: string;
+    readonly id?: string;
+    /** Focus is parked on the body, which means nothing holds it. */
+    readonly onBody: boolean;
+    readonly inShadow?: boolean;
+    readonly rect?: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** Say what holds focus, in the vocabulary the outline uses. */
+export declare function renderFocus(holder: FocusHolder | undefined): string;

package/dist/web/a11y/focus.js

@@ -0,0 +1,106 @@
+/**
+ * What holds focus at this moment.
+ *
+ * Distinct from the keyboard walk, which presses Tab around the whole
+ * page and judges the journey. This answers the question asked
+ * between actions: after that click, that key, that navigation, where
+ * did focus end up? It moves nothing.
+ */
+/**
+ * Ask the page what holds focus, without moving it.
+ *
+ * Shipped as a source string because it declares helpers. The
+ * accessible name is read the cheap way, from the attributes and
+ * text that produce one, rather than from the accessibility tree:
+ * this has to answer between actions without a tree walk, and the
+ * name is only there to identify what is already known to be
+ * focused.
+ */
+export const FOCUS_PROBE = `(() => {
+  const active = () => {
+    // Focus inside a shadow root reads as the host from outside, so
+    // the chain is followed down to the element that really has it.
+    let el = document.activeElement;
+    let shadowed = false;
+    while (el && el.shadowRoot && el.shadowRoot.activeElement) {
+      el = el.shadowRoot.activeElement;
+      shadowed = true;
+    }
+    return { el: el, shadowed: shadowed };
+  };
+
+  const found = active();
+  const el = found.el;
+  if (!el) return undefined;
+
+  const tag = el.tagName ? el.tagName.toLowerCase() : "unknown";
+  const onBody = el === document.body || tag === "html";
+  const labelled = () => {
+    const aria = el.getAttribute && el.getAttribute("aria-label");
+    if (aria) return aria.trim();
+    const by = el.getAttribute && el.getAttribute("aria-labelledby");
+    if (by) {
+      const names = by.split(/\\s+/).map((id) => {
+        const target = document.getElementById(id);
+        return target ? (target.textContent || "").trim() : "";
+      });
+      const joined = names.filter(Boolean).join(" ");
+      if (joined) return joined;
+    }
+    if (el.labels && el.labels.length > 0) {
+      return (el.labels[0].textContent || "").trim();
+    }
+    const own = (el.textContent || "").replace(/\\s+/g, " ").trim();
+    if (own) return own.slice(0, 80);
+    const value = el.getAttribute && el.getAttribute("value");
+    return value ? value.trim() : "";
+  };
+
+  const box = el.getBoundingClientRect ? el.getBoundingClientRect() : undefined;
+  const name = onBody ? "" : labelled();
+  const role = el.getAttribute && el.getAttribute("role");
+  return {
+    tag: tag,
+    role: role || undefined,
+    name: name || undefined,
+    id: (el.id || undefined),
+    onBody: onBody,
+    inShadow: found.shadowed || undefined,
+    rect: box && (box.width > 0 || box.height > 0)
+      ? { x: box.x, y: box.y, width: box.width, height: box.height }
+      : undefined,
+  };
+})()`;
+/** Say what holds focus, in the vocabulary the outline uses. */
+export function renderFocus(holder) {
+    if (!holder) {
+        return ("WARN what holds focus could not be read\n\n" +
+            "The page did not answer, which happens when nothing is " +
+            "loaded yet. Navigate, then ask again.");
+    }
+    if (holder.onBody) {
+        // Naming the body as the holder would read as a real control and
+        // hide the useful finding, which is that a key press went
+        // nowhere.
+        return ("Nothing holds focus.\n\n" +
+            "Focus is parked on the document, which is where the browser " +
+            "leaves it when no control has been given it. A tab from here " +
+            "starts at the top of the page.");
+    }
+    // The role and name pair is how every other surface here addresses
+    // an element, so the answer can be pasted straight into a target.
+    const called = holder.role ?? holder.tag;
+    const named = holder.name ? ` "${holder.name}"` : "";
+    const notes = [
+        holder.role && holder.role !== holder.tag ? `<${holder.tag}>` : "",
+        holder.id ? `#${holder.id}` : "",
+        holder.inShadow ? "inside a shadow root" : "",
+        holder.rect ? `at ${place(holder.rect)}` : "",
+    ].filter(Boolean);
+    const tail = notes.length > 0 ? `\n\n${notes.join(", ")}` : "";
+    return `${called}${named} holds focus.${tail}`;
+}
+function place(rect) {
+    return (`${Math.round(rect.x)},${Math.round(rect.y)} ` +
+        `${Math.round(rect.width)}x${Math.round(rect.height)}`);
+}

package/dist/web/a11y/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The accessibility domain: the page as assistive technology
+ * perceives it.
+ *
+ * Analysis here is capture-agnostic. Everything takes plain
+ * serializable data, so a tree captured by CDP, by Playwright
+ * or read back from a fixture is analyzed by the same code.
+ */
+export { ANNOUNCE_BINDING, ANNOUNCEMENT_OBSERVER, type Announcement, type AnnouncementCandidate, CANDIDATE_REGISTRY, renderAnnouncements, } from "./announcements.js";
+export { ACTION_VIEW_BUDGET_BYTES, type BudgetedOutline, MAX_OUTLINE_BUDGET_BYTES, OUTLINE_BUDGET_BYTES, outlineBudget, withinOutlineBudget, } from "./budget.js";
+export { FOCUS_PROBE, type FocusHolder, renderFocus, } from "./focus.js";
+export { isWeakName, type NameSource, nameSource } from "./naming.js";
+export { renderAxOutline } from "./outline.js";
+export { renderReading } from "./reading.js";
+export { type Skeleton, scopeTree, subtreeAt, type TreeScope, } from "./scope.js";
+export { describeStates, type StateOptions } from "./states.js";
+export { type AxNode, type AxProperties, type FrameAxTree, isMeaningful, normalizeAxTree, type RawAxNameSource, type RawAxNode, type RawAxProperty, spliceFrames, } from "./tree.js";
+export { analyseWalk, type FocusStyle, type Indicator, indicatorOf, MAX_LISTED_FINDINGS, renderWalk, type Trap, type Unreachable, type WalkCandidate, type WalkCapture, type WalkFindings, type WalkStop, } from "./walk.js";
+export { WALK_COLLECT, WALK_READ, WALK_REMEMBER, WALK_RESTORE, } from "./walkprobe.js";

package/dist/web/a11y/index.js

@@ -0,0 +1,25 @@
+/**
+ * The accessibility domain: the page as assistive technology
+ * perceives it.
+ *
+ * Analysis here is capture-agnostic. Everything takes plain
+ * serializable data, so a tree captured by CDP, by Playwright
+ * or read back from a fixture is analyzed by the same code.
+ */
+export { ANNOUNCE_BINDING, ANNOUNCEMENT_OBSERVER, CANDIDATE_REGISTRY, renderAnnouncements, } from "./announcements.js";
+export { ACTION_VIEW_BUDGET_BYTES, MAX_OUTLINE_BUDGET_BYTES, OUTLINE_BUDGET_BYTES, outlineBudget, withinOutlineBudget, } from "./budget.js";
+export { FOCUS_PROBE, renderFocus, } from "./focus.js";
+export { isWeakName, nameSource } from "./naming.js";
+export { renderAxOutline } from "./outline.js";
+export { renderReading } from "./reading.js";
+export { scopeTree, subtreeAt, } from "./scope.js";
+// Exported because a stored page has to carry the same states the
+// rendered outline shows. Two vocabularies for one set of facts
+// would make a payload that disagrees with the view it came from.
+export { describeStates } from "./states.js";
+export { isMeaningful, normalizeAxTree, spliceFrames, } from "./tree.js";
+export { analyseWalk, indicatorOf, MAX_LISTED_FINDINGS, renderWalk, } from "./walk.js";
+// The page-side halves of the keyboard walk, in the order they
+// run: collect what can hold focus, remember where the caller
+// left things, read each stop, then put the page back.
+export { WALK_COLLECT, WALK_READ, WALK_REMEMBER, WALK_RESTORE, } from "./walkprobe.js";

package/dist/web/a11y/naming.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where an accessible name came from.
+ *
+ * Two controls can read identically in an outline and be very
+ * different to use. A field named by its label is announced
+ * whenever it takes focus; one named only by its placeholder
+ * loses its name the moment someone types. Knowing the
+ * mechanism is what lets a review tell those apart.
+ */
+import type { RawAxNode } from "./tree.js";
+/** The mechanism that produced an element's accessible name. */
+export type NameSource = "labelledby" | "label" | "nativeLabel" | "content" | "title" | "placeholder" | "alt" | "value" | "unnamed";
+/**
+ * Which mechanism produced this node's name.
+ *
+ * Chrome reports every mechanism it tried, in priority order,
+ * marking the ones it passed over. The one that named the
+ * element is the one that yielded text and was neither
+ * superseded nor pointed at something absent.
+ */
+export declare function nameSource(node: RawAxNode): NameSource;
+/** Whether a name is one that disappears when it is needed most. */
+export declare function isWeakName(source: NameSource): boolean;

package/dist/web/a11y/naming.js

@@ -0,0 +1,55 @@
+/**
+ * Where an accessible name came from.
+ *
+ * Two controls can read identically in an outline and be very
+ * different to use. A field named by its label is announced
+ * whenever it takes focus; one named only by its placeholder
+ * loses its name the moment someone types. Knowing the
+ * mechanism is what lets a review tell those apart.
+ */
+/** Names that vanish exactly when a user needs them. */
+const WEAK_SOURCES = new Set(["title", "placeholder"]);
+/**
+ * Which mechanism produced this node's name.
+ *
+ * Chrome reports every mechanism it tried, in priority order,
+ * marking the ones it passed over. The one that named the
+ * element is the one that yielded text and was neither
+ * superseded nor pointed at something absent.
+ */
+export function nameSource(node) {
+    const winner = (node.name?.sources ?? []).find(produced);
+    if (!winner)
+        return "unnamed";
+    if (winner.nativeSource)
+        return "nativeLabel";
+    if (winner.type === "contents")
+        return "content";
+    if (winner.type === "placeholder")
+        return "placeholder";
+    switch (winner.attribute) {
+        case "aria-labelledby":
+            return "labelledby";
+        case "aria-label":
+            return "label";
+        case "title":
+            return "title";
+        case "alt":
+            return "alt";
+        case "value":
+            return "value";
+        default:
+            return winner.type === "relatedElement" ? "labelledby" : "unnamed";
+    }
+}
+/** Whether this source actually supplied the name. */
+function produced(source) {
+    if (source.superseded || source.invalid)
+        return false;
+    const text = source.value?.value;
+    return text !== undefined && text !== "";
+}
+/** Whether a name is one that disappears when it is needed most. */
+export function isWeakName(source) {
+    return WEAK_SOURCES.has(source);
+}

package/dist/web/a11y/outline.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Rendering the accessibility tree as an outline.
+ *
+ * The outline is the model's default view of a page: a nested
+ * role-and-name listing that reads like a description, with the
+ * states that change what a caller can do shown inline. It is
+ * the surface act refusals, audits and page reads all quote.
+ */
+import { type AxNode } from "./tree.js";
+/**
+ * Render the tree as a nested role-and-name outline, with the
+ * states that change what a caller can do shown inline. A node
+ * that is not meaningful (a noise role with no name) is folded
+ * away: its children rise to its own indentation, so wrappers
+ * never add depth while their named descendants survive.
+ *
+ * A node that has no name is written as its role alone. Structure
+ * is most of a real page, a third of the nodes in a long article
+ * carry no name at all, and empty quotes against every one of
+ * them cost more than a whole action-view budget while telling a
+ * reader nothing they did not already have from the role.
+ */
+export declare function renderAxOutline(root: AxNode): string;

package/dist/web/a11y/outline.js

@@ -0,0 +1,42 @@
+/**
+ * Rendering the accessibility tree as an outline.
+ *
+ * The outline is the model's default view of a page: a nested
+ * role-and-name listing that reads like a description, with the
+ * states that change what a caller can do shown inline. It is
+ * the surface act refusals, audits and page reads all quote.
+ */
+import { describeStates } from "./states.js";
+import { isMeaningful } from "./tree.js";
+/**
+ * Render the tree as a nested role-and-name outline, with the
+ * states that change what a caller can do shown inline. A node
+ * that is not meaningful (a noise role with no name) is folded
+ * away: its children rise to its own indentation, so wrappers
+ * never add depth while their named descendants survive.
+ *
+ * A node that has no name is written as its role alone. Structure
+ * is most of a real page, a third of the nodes in a long article
+ * carry no name at all, and empty quotes against every one of
+ * them cost more than a whole action-view budget while telling a
+ * reader nothing they did not already have from the role.
+ */
+export function renderAxOutline(root) {
+    const lines = [];
+    const walk = (node, depth) => {
+        const shown = isMeaningful(node);
+        if (shown) {
+            const states = describeStates(node);
+            const suffix = states.length ? ` ${states.join(" ")}` : "";
+            const named = node.name ? ` "${node.name}"` : "";
+            lines.push(`${"  ".repeat(depth)}${node.role}${named}${suffix}`);
+        }
+        const childDepth = shown ? depth + 1 : depth;
+        for (const child of node.children)
+            walk(child, childDepth);
+    };
+    // The root itself is the page container; render its children.
+    for (const child of root.children)
+        walk(child, 0);
+    return lines.join("\n");
+}

package/dist/web/a11y/reading.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The page as a screen reader narrates it.
+ *
+ * The outline shows how a page is built; a reading shows what
+ * it is like to use without sight. Landmarks are announced on
+ * entry and exit, headings carry their level, controls carry
+ * the states that change how they behave, and text is read as
+ * prose rather than as elements.
+ */
+import type { AxNode } from "./tree.js";
+/** Narrate a tree in reading order. */
+export declare function renderReading(root: AxNode): string;

package/dist/web/a11y/reading.js

@@ -0,0 +1,101 @@
+/**
+ * The page as a screen reader narrates it.
+ *
+ * The outline shows how a page is built; a reading shows what
+ * it is like to use without sight. Landmarks are announced on
+ * entry and exit, headings carry their level, controls carry
+ * the states that change how they behave, and text is read as
+ * prose rather than as elements.
+ */
+import { describeStates } from "./states.js";
+/**
+ * Roles a reader passes through without a word. They exist to
+ * group or to carry text, and announcing them would put
+ * scaffolding between the listener and the page.
+ */
+const SILENT_ROLES = new Set([
+    "generic",
+    "none",
+    "presentation",
+    "document",
+    "RootWebArea",
+    "paragraph",
+    "LabelText",
+    "listitem",
+    "MenuListPopup",
+]);
+/** Roles that carry text and nothing else. */
+const TEXT_ROLES = new Set(["StaticText", "InlineTextBox", "text"]);
+/** Landmarks a reader announces entering and leaving. */
+const LANDMARK_ROLES = new Set([
+    "banner",
+    "complementary",
+    "contentinfo",
+    "form",
+    "main",
+    "navigation",
+    "region",
+    "search",
+]);
+/** Whether entering this node is worth announcing. */
+function isRegion(node) {
+    if (LANDMARK_ROLES.has(node.role))
+        return true;
+    if (node.role === "list")
+        return true;
+    const live = node.properties.live;
+    return typeof live === "string" && live !== "" && live !== "off";
+}
+/** Narrate a tree in reading order. */
+export function renderReading(root) {
+    const lines = [];
+    const read = (node, depth) => {
+        const pad = "  ".repeat(depth);
+        if (TEXT_ROLES.has(node.role)) {
+            if (node.name.trim())
+                lines.push(`${pad}${node.name}`);
+            return;
+        }
+        if (SILENT_ROLES.has(node.role) && !node.name.trim()) {
+            for (const child of node.children)
+                read(child, depth);
+            return;
+        }
+        if (isRegion(node)) {
+            lines.push(`${pad}${announce(node)}`);
+            for (const child of node.children)
+                read(child, depth + 1);
+            lines.push(`${pad}end of ${node.role}${node.name ? `, ${node.name}` : ""}`);
+            return;
+        }
+        lines.push(`${pad}${announce(node)}`);
+        for (const child of node.children)
+            read(child, depth);
+    };
+    for (const child of root.children)
+        read(child, 0);
+    return lines.join("\n");
+}
+/** What a reader says on reaching this element. */
+function announce(node) {
+    const parts = [roleLabel(node)];
+    if (node.name.trim())
+        parts.push(node.name);
+    if (node.role === "list")
+        parts.push(itemCount(node));
+    parts.push(...describeStates(node, { skipLevel: true }));
+    return parts.join(", ");
+}
+/** How many items a list holds, said the way it is heard. */
+function itemCount(list) {
+    const items = list.children.filter((child) => child.role === "listitem").length;
+    return items === 1 ? "1 item" : `${items} items`;
+}
+/** The role as spoken, with a heading's level folded in. */
+function roleLabel(node) {
+    const level = node.properties.level;
+    if (node.role === "heading" && level !== undefined) {
+        return `heading level ${level}`;
+    }
+    return node.role;
+}

package/dist/web/a11y/scope.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Scoping the accessibility tree before it is read.
+ *
+ * A whole tree is the wrong answer to most questions. A caller
+ * asking "how is this page laid out" wants landmarks, not every
+ * span inside them; a caller asking "what can I press" wants
+ * controls. Scoping narrows the tree first, so the view that
+ * gets rendered is the view that was asked for.
+ */
+import { type AxNode } from "./tree.js";
+/** A reduced view of the page, keeping one kind of thing. */
+export type Skeleton = "landmarks" | "headings" | "interactive";
+/** How much of the tree to keep. */
+export interface TreeScope {
+    /** Levels of the outline to keep, counted as the outline reads. */
+    readonly depth?: number;
+    /** Keep only one kind of element, with the rest folded away. */
+    readonly only?: Skeleton;
+}
+/** Narrow a tree to the view the caller asked for. */
+export declare function scopeTree(root: AxNode, scope: TreeScope): AxNode;
+/** The branch rooted at the element carrying this backend id. */
+export declare function subtreeAt(root: AxNode, backendDomId: number): AxNode | undefined;

package/dist/web/a11y/scope.js

@@ -0,0 +1,99 @@
+/**
+ * Scoping the accessibility tree before it is read.
+ *
+ * A whole tree is the wrong answer to most questions. A caller
+ * asking "how is this page laid out" wants landmarks, not every
+ * span inside them; a caller asking "what can I press" wants
+ * controls. Scoping narrows the tree first, so the view that
+ * gets rendered is the view that was asked for.
+ */
+import { isMeaningful } from "./tree.js";
+/** The regions that carve a page into its major parts. */
+const LANDMARK_ROLES = new Set([
+    "banner",
+    "complementary",
+    "contentinfo",
+    "form",
+    "main",
+    "navigation",
+    "region",
+    "search",
+]);
+/** The roles a caller can operate. */
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "checkbox",
+    "combobox",
+    "link",
+    "listbox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "tab",
+    "textbox",
+    "treeitem",
+]);
+/** Whether a node belongs to the skeleton being asked for. */
+function keeps(node, only) {
+    if (only === "landmarks")
+        return LANDMARK_ROLES.has(node.role);
+    if (only === "headings")
+        return node.role === "heading";
+    return INTERACTIVE_ROLES.has(node.role);
+}
+/** Narrow a tree to the view the caller asked for. */
+export function scopeTree(root, scope) {
+    let tree = root;
+    if (scope.only)
+        tree = keepOnly(tree, scope.only);
+    if (scope.depth !== undefined)
+        tree = cutToDepth(tree, scope.depth);
+    return tree;
+}
+/**
+ * Keep the nodes of one kind, folding the rest away. A kept
+ * node stays under a kept ancestor, so a navigation inside a
+ * banner still reads as nested.
+ */
+function keepOnly(root, only) {
+    const prune = (node) => {
+        const children = node.children.flatMap(prune);
+        if (!keeps(node, only))
+            return children;
+        return [{ ...node, children }];
+    };
+    return { ...root, children: root.children.flatMap(prune) };
+}
+/**
+ * Cut the tree to a number of levels, counting the way the
+ * outline reads: a node that renders as a line costs a level,
+ * and a wrapper that folds away costs nothing.
+ */
+function cutToDepth(root, depth) {
+    const cut = (node, remaining) => {
+        const shown = isMeaningful(node);
+        const left = shown ? remaining - 1 : remaining;
+        if (shown && remaining <= 0)
+            return [];
+        const children = left > 0 ? node.children.flatMap((c) => cut(c, left)) : [];
+        return [{ ...node, children }];
+    };
+    return { ...root, children: root.children.flatMap((c) => cut(c, depth)) };
+}
+/** The branch rooted at the element carrying this backend id. */
+export function subtreeAt(root, backendDomId) {
+    if (root.backendDomId === backendDomId)
+        return root;
+    for (const child of root.children) {
+        const found = subtreeAt(child, backendDomId);
+        if (found)
+            return found;
+    }
+    return undefined;
+}