@teaflask/assistant 0.3.0 → 0.6.0

package/src/reader/snapshot-node.ts

@@ -1,158 +0,0 @@
-// One element becomes one node: role, name, state bits, and a ref when
-// the element is addressable. The ref mint is the caller's — the ref
-// registries stay single-homed in snapshot.ts.
-
-import { accessibleNameOf } from "./accessible-name.js";
-import {
-  CONTENT_REF_ROLES,
-  INTERACTIVE_REF_ROLES,
-  interactivitySignalsOf,
-  isScrollable,
-} from "./interactivity.js";
-import { textboxValueOf } from "./redaction.js";
-import {
-  ariaBooleanOf,
-  ariaLevelOf,
-  ARIA_CHECKED_ROLES,
-  ARIA_DISABLED_ROLES,
-  ARIA_SELECTED_ROLES,
-  roleOf,
-} from "./roles.js";
-import type { SnapshotNode, WalkContext } from "./snapshot.js";
-import { parentAcrossShadowBoundaryOf } from "./visibility.js";
-
-const MAX_NODE_NAME_LENGTH = 100;
-
-export function _snapshotNodeOf(
-  element: Element,
-  context: WalkContext,
-  refFor: (element: Element, role: string, name: string) => string,
-): SnapshotNode | null {
-  const { options, oracle, nameCache } = context;
-  const role = roleOf(element);
-  const roleLower = role.toLowerCase();
-  const interactivity = interactivitySignalsOf(element, options.probe);
-  const name = _normalizedNodeName(
-    accessibleNameOf(element, options.probe, nameCache),
-  );
-  const hidden = !oracle.isVisible(element);
-  const scrollable = isScrollable(element, options.probe);
-  const shouldHaveRef =
-    roleLower === "iframe" ||
-    roleLower === "canvas" ||
-    scrollable ||
-    interactivity.interactive ||
-    INTERACTIVE_REF_ROLES.has(roleLower) ||
-    (CONTENT_REF_ROLES.has(roleLower) && name.length > 0);
-
-  const refId = shouldHaveRef ? refFor(element, role, name) : null;
-  if (role === "generic" && refId === null && !hidden) {
-    return null; // an anonymous wrapper adds nothing; its children speak
-  }
-
-  const hints =
-    interactivity.interactive && !interactivity.isInteractiveTag
-      ? interactivity.hints
-      : [];
-  const value = textboxValueOf(element);
-
-  return {
-    role,
-    name,
-    level: ariaLevelOf(element, role),
-    hidden,
-    scrollable,
-    checked: _checkedStateOf(element, roleLower),
-    selected: _selectedStateOf(element, roleLower),
-    focused: element.ownerDocument.activeElement === element,
-    disabled: _disabledStateOf(element, roleLower),
-    offscreen: !hidden && oracle.isOffscreen(element),
-    refId,
-    hints,
-    placeholder: element.getAttribute("placeholder"),
-    element,
-    children: value !== null && value !== "" ? [value] : [],
-  };
-}
-
-function _checkedStateOf(element: Element, role: string): boolean {
-  if (
-    element instanceof HTMLInputElement &&
-    (element.type === "checkbox" || element.type === "radio")
-  ) {
-    return element.checked;
-  }
-  if (!ARIA_CHECKED_ROLES.has(role)) {
-    return false;
-  }
-  return ariaBooleanOf(element.getAttribute("aria-checked")) === true;
-}
-
-function _selectedStateOf(element: Element, role: string): boolean {
-  if (element instanceof HTMLOptionElement) {
-    return element.selected;
-  }
-  if (!ARIA_SELECTED_ROLES.has(role)) {
-    return false;
-  }
-  return ariaBooleanOf(element.getAttribute("aria-selected")) === true;
-}
-
-function _disabledStateOf(element: Element, role: string): boolean {
-  if (!ARIA_DISABLED_ROLES.has(role)) {
-    return false;
-  }
-  if (_isNativelyDisabled(element)) {
-    return true;
-  }
-  for (
-    let current: Element | null = element;
-    current !== null;
-    current = parentAcrossShadowBoundaryOf(current)
-  ) {
-    if (ariaBooleanOf(current.getAttribute("aria-disabled")) === true) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function _isNativelyDisabled(element: Element): boolean {
-  const tag = element.tagName.toLowerCase();
-  if (
-    !["button", "input", "select", "textarea", "option", "optgroup"].includes(
-      tag,
-    )
-  ) {
-    return false;
-  }
-  try {
-    return element.matches(":disabled");
-  } catch {
-    return false;
-  }
-}
-
-export function _normalizedNodeName(name: string): string {
-  return name.replace(/\s+/g, " ").trim().substring(0, MAX_NODE_NAME_LENGTH);
-}
-
-export function _fragmentNode(): SnapshotNode {
-  return {
-    role: "fragment",
-    name: "",
-    level: null,
-    hidden: false,
-    scrollable: false,
-    checked: false,
-    selected: false,
-    focused: false,
-    disabled: false,
-    offscreen: false,
-    refId: null,
-    hints: [],
-    placeholder: null,
-    element: null,
-    children: [],
-  };
-}

package/src/reader/snapshot-root.ts

@@ -1,125 +0,0 @@
-// Root resolution for a read: a pinned element, a remembered ref, a
-// selector match, or the body — refused when the root sits inside a
-// curated (opted-out) subtree.
-
-import { roleOf } from "./roles.js";
-import { parentAcrossShadowBoundaryOf } from "./visibility.js";
-
-export const IGNORE_ATTRIBUTE = "data-teaflask-ignore";
-
-/** The slice of SnapshotOptions that addresses a root — all root
- * resolution needs, so ref-addressed capabilities resolve without
- * inventing a probe or read knobs. */
-export interface RootAddress {
-  rootElement: Element | null;
-  refId: string | null;
-  selector: string | null;
-  ignoreSelectors: string[];
-}
-
-export function _resolvedRootOf(
-  options: RootAddress,
-  elementByRef: ReadonlyMap<string, Element>,
-): { root: Element; error: null } | { root: null; error: string } {
-  if (options.rootElement !== null) {
-    return _rootUnlessCurated(options.rootElement, options);
-  }
-  if (options.refId !== null) {
-    const remembered = elementByRef.get(options.refId);
-    if (remembered?.isConnected !== true) {
-      return {
-        root: null,
-        error:
-          `The ref "${options.refId}" is not on the current page — ` +
-          "take a fresh full read and use a ref from it.",
-      };
-    }
-    return _rootUnlessCurated(remembered, options);
-  }
-  if (options.selector !== null) {
-    const matched = _safeQuerySelector(options.selector);
-    if (matched === null) {
-      return {
-        root: null,
-        error:
-          `Nothing on the page matches the selector "${options.selector}" — ` +
-          "take a full read to see what is there.",
-      };
-    }
-    return _rootUnlessCurated(matched, options);
-  }
-  const body = document.body as HTMLElement | null;
-  if (body === null) {
-    return { root: null, error: "The page has no body to read yet." };
-  }
-  return { root: body, error: null };
-}
-
-function _rootUnlessCurated(
-  root: Element,
-  options: RootAddress,
-): { root: Element; error: null } | { root: null; error: string } {
-  // The full-page walk enforces curation top-down — a curated subtree is
-  // never entered, so nothing below it is reachable. A scoped read roots
-  // BELOW the top, so it must check its own ancestry, or a descendant
-  // selector (".private h2") would read inside an opted-out region.
-  for (
-    let current: Element | null = root;
-    current !== null;
-    current = parentAcrossShadowBoundaryOf(current)
-  ) {
-    if (_theSubtreeIsCurated(current, options.ignoreSelectors)) {
-      return {
-        root: null,
-        error:
-          "That part of the page has opted out of page reads — " +
-          "take a full read to see what is available.",
-      };
-    }
-  }
-  return { root, error: null };
-}
-
-function _safeQuerySelector(selector: string): Element | null {
-  try {
-    const direct = document.querySelector(selector);
-    if (direct !== null) {
-      return direct;
-    }
-  } catch {
-    return null;
-  }
-  return _firstElementWithImplicitRole(selector);
-}
-
-function _firstElementWithImplicitRole(selector: string): Element | null {
-  // [role="button"]-shaped selectors should also find elements whose
-  // role is implicit (a bare <button> has no role attribute to match).
-  const match = /^\[role=["'](\w+)["']\]$/.exec(selector);
-  if (match === null) {
-    return null;
-  }
-  const targetRole = match[1];
-  for (const element of Array.from(document.querySelectorAll("*"))) {
-    if (roleOf(element) === targetRole) {
-      return element;
-    }
-  }
-  return null;
-}
-
-export function _theSubtreeIsCurated(
-  element: Element,
-  ignoreSelectors: string[],
-): boolean {
-  if (element.hasAttribute(IGNORE_ATTRIBUTE)) {
-    return true;
-  }
-  return ignoreSelectors.some((selector) => {
-    try {
-      return element.matches(selector);
-    } catch {
-      return false; // an invalid selector never breaks a read
-    }
-  });
-}

package/src/reader/snapshot.ts

@@ -1,328 +0,0 @@
-// The snapshot walk: DOM + shadow DOM in, a compact semantic tree out.
-// Elements earn a place by meaning something — interactive, scrollable,
-// landmark, named, or a non-generic role — and everything else
-// contributes only its text. Curation is opt-out and enforced here, at
-// the walk: a data-teaflask-ignore attribute or a grant-configured
-// selector silently prunes the subtree, and redaction (redaction.ts)
-// guards every value read. Iframes render as leaf nodes: a same-JS
-// bundle cannot see into cross-origin frames, and same-origin recursion
-// is deliberately deferred (the f-prefix ref grammar stays reserved for
-// it — this function is the seam).
-//
-// Ref-ids are minted monotonically and remembered per element across
-// snapshots (WeakMap badge): an unchanged button keeps its ref from read
-// to read, which is what keeps repeat-read diffs small and will let a
-// future capability address elements by ref.
-
-import type { LayoutProbe } from "./layout-probe.js";
-import {
-  accessibleNameOf,
-  type AccessibleNameCache,
-} from "./accessible-name.js";
-import {
-  interactivitySignalsOf,
-  isLandmark,
-  isScrollable,
-} from "./interactivity.js";
-import { roleOf } from "./roles.js";
-import {
-  _duplicateRefOf,
-  _foldTextLeaves,
-  _mergeStringChildren,
-  _unwrapBareGenerics,
-} from "./snapshot-compaction.js";
-import {
-  _fragmentNode,
-  _normalizedNodeName,
-  _snapshotNodeOf,
-} from "./snapshot-node.js";
-import {
-  _resolvedRootOf,
-  _theSubtreeIsCurated,
-  IGNORE_ATTRIBUTE,
-  type RootAddress,
-} from "./snapshot-root.js";
-import {
-  lightAndShadowChildNodesOf,
-  visibilityOracleOf,
-  type VisibilityOracle,
-} from "./visibility.js";
-
-export { IGNORE_ATTRIBUTE };
-export const DEFAULT_MAX_DEPTH = 50;
-
-const SKIP_TAGS = new Set([
-  "script",
-  "style",
-  "meta",
-  "link",
-  "title",
-  "noscript",
-]);
-
-export interface SnapshotOptions {
-  probe: LayoutProbe;
-  /** Grant-configured opt-out selectors; invalid ones are ignored. */
-  ignoreSelectors: string[];
-  maxDepth: number;
-  /** Interactive-elements-only view (with skipped text hoisted). */
-  interactive: boolean;
-  /** Keep invisible elements, marked [hidden]. */
-  showHidden: boolean;
-  /** Root the snapshot at a selector match instead of the body. */
-  selector: string | null;
-  /** Root the snapshot at a previously-minted ref. */
-  refId: string | null;
-  /**
-   * A pre-resolved root, taking precedence over refId/selector. The
-   * size-fitting ladder re-renders one read several times, and each
-   * render rebuilds the ref registry — re-resolving a refId mid-ladder
-   * would fail if the walk just re-minted the element under a new ref,
-   * so the orchestrator resolves once and pins the element.
-   */
-  rootElement: Element | null;
-}
-
-export interface SnapshotNode {
-  role: string;
-  name: string;
-  level: number | null;
-  hidden: boolean;
-  scrollable: boolean;
-  checked: boolean;
-  selected: boolean;
-  focused: boolean;
-  disabled: boolean;
-  offscreen: boolean;
-  refId: string | null;
-  hints: string[];
-  placeholder: string | null;
-  element: Element | null;
-  children: (SnapshotNode | string)[];
-}
-
-export type SnapshotOutcome =
-  { tree: SnapshotNode; error: null } | { tree: null; error: string };
-
-// Monotonic across snapshots on purpose: a ref is never reissued to a
-// different element, and an unchanged element keeps its badge.
-let _refCounter = 0;
-const _refBadgeByElement = new WeakMap<
-  Element,
-  { role: string; name: string; ref: string }
->();
-// The last snapshot's ref → element registry, for refId-rooted reads.
-const _elementByRef = new Map<string, Element>();
-
-export interface WalkContext {
-  options: SnapshotOptions;
-  oracle: VisibilityOracle;
-  nameCache: AccessibleNameCache;
-}
-
-export function snapshotTreeOf(options: SnapshotOptions): SnapshotOutcome {
-  const context: WalkContext = {
-    options,
-    oracle: visibilityOracleOf(options.probe),
-    nameCache: new Map(),
-  };
-  const rooting = _resolvedRootOf(options, _elementByRef);
-  if (rooting.error !== null) {
-    return { tree: null, error: rooting.error };
-  }
-  const root = rooting.root;
-  _elementByRef.clear();
-  const fragment = _fragmentNode();
-  _traverse(root, 0, fragment, context);
-  _mergeStringChildren(fragment);
-  _unwrapBareGenerics(fragment, options.showHidden);
-  _foldTextLeaves(fragment);
-  const duplicate = _duplicateRefOf(fragment);
-  if (duplicate !== null) {
-    return {
-      tree: null,
-      error: `The snapshot minted the ref "${duplicate}" twice; take a fresh read.`,
-    };
-  }
-  return { tree: fragment, error: null };
-}
-
-// --- root resolution -------------------------------------------------------
-
-/** Resolve a read's root without walking — for pinning it across the
- * orchestrator's repeated renders of one read. */
-export function resolvedSnapshotRootOf(
-  options: SnapshotOptions,
-): { root: Element; error: null } | { root: null; error: string } {
-  return _resolvedRootOf(options, _elementByRef);
-}
-
-/**
- * Resolve a previously-minted ref to its live element — for a capability
- * that addresses the page by ref (highlight, prefill) instead of reading
- * it. Liveness and the in-page curation opt-out are checked the same way
- * a refId-rooted read checks them, and the error is the reader's own
- * model-actionable sentence.
- */
-export function resolvedElementOfRef(
-  refId: string,
-): { element: Element; error: null } | { element: null; error: string } {
-  const address: RootAddress = {
-    rootElement: null,
-    refId,
-    selector: null,
-    ignoreSelectors: [],
-  };
-  const rooting = _resolvedRootOf(address, _elementByRef);
-  if (rooting.error !== null) {
-    return { element: null, error: rooting.error };
-  }
-  return { element: rooting.root, error: null };
-}
-
-// --- the walk --------------------------------------------------------------
-
-function _traverse(
-  element: Element,
-  depth: number,
-  parentNode: SnapshotNode,
-  context: WalkContext,
-): void {
-  const { options, oracle } = context;
-  const includeAsRoot = options.refId === null && element === document.body;
-  const traversable = _shouldTraverse(element, context);
-  if (!traversable && !includeAsRoot) {
-    // No name hoisting here: a non-traversable subtree is hidden or
-    // curated, and curated content must not leak through its name.
-    return;
-  }
-  const hidden = !oracle.isVisible(element);
-  const include =
-    includeAsRoot ||
-    _shouldIncludeNode(element, context) ||
-    (options.showHidden && hidden);
-
-  let targetNode = parentNode;
-  if (include) {
-    const node = _snapshotNodeOf(element, context, _refFor);
-    if (node !== null) {
-      parentNode.children.push(node);
-      targetNode = node;
-    }
-  } else if (options.interactive && element.childElementCount === 0) {
-    // A hoisted content name already carries the leaf's text (and its
-    // pseudo content) — descending as well would emit the text twice.
-    if (_hoistSkippedLeafName(element, parentNode, context)) {
-      return;
-    }
-  }
-
-  const before = options.probe.pseudoContentOf(element, "::before");
-  if (before !== "") {
-    targetNode.children.push(before);
-  }
-  if (_descendsIntoChildren(element) && depth < options.maxDepth) {
-    for (const child of lightAndShadowChildNodesOf(element)) {
-      if (child.nodeType === Node.TEXT_NODE) {
-        // A textbox's value is already seeded; its text would duplicate it.
-        if (targetNode.role !== "textbox" && child.nodeValue !== null) {
-          targetNode.children.push(child.nodeValue);
-        }
-      } else if (child.nodeType === Node.ELEMENT_NODE) {
-        _traverse(child as Element, depth + 1, targetNode, context);
-      }
-    }
-  }
-  const after = options.probe.pseudoContentOf(element, "::after");
-  if (after !== "") {
-    targetNode.children.push(after);
-  }
-}
-
-function _descendsIntoChildren(element: Element): boolean {
-  // A <select> renders its own options (render.ts reads element.options
-  // directly) and an <iframe> holds a separate document — walking into
-  // either only does work whose nodes are discarded downstream, and a
-  // select would leak option text as string children the renderer never
-  // shows.
-  const tag = element.tagName.toLowerCase();
-  return tag !== "iframe" && tag !== "select";
-}
-
-function _shouldTraverse(element: Element, context: WalkContext): boolean {
-  const tag = element.tagName.toLowerCase();
-  if (SKIP_TAGS.has(tag)) {
-    return false;
-  }
-  if (_theSubtreeIsCurated(element, context.options.ignoreSelectors)) {
-    return false;
-  }
-  // No aria-hidden special case: the visibility oracle reads aria-hidden
-  // (inherited) as hidden, so default reads prune these subtrees below
-  // and show_hidden keeps them, marked — same as any other hidden thing.
-  if (!context.options.showHidden && !context.oracle.isVisible(element)) {
-    // Branded-control escape: many designs hide the real radio/checkbox
-    // and render a styled twin; the input still matters.
-    if (element instanceof HTMLInputElement) {
-      const type = element.type;
-      if (type === "radio" || type === "checkbox") {
-        return true;
-      }
-    }
-    return false;
-  }
-  return true;
-}
-
-function _shouldIncludeNode(element: Element, context: WalkContext): boolean {
-  const { options, nameCache } = context;
-  const role = roleOf(element);
-  const interactive = interactivitySignalsOf(
-    element,
-    options.probe,
-  ).interactive;
-  const scrollable = isScrollable(element, options.probe);
-  const landmark = isLandmark(element);
-  if (options.interactive) {
-    return role === "canvas" || interactive || scrollable || landmark;
-  }
-  if (interactive || scrollable || landmark) {
-    return true;
-  }
-  if (accessibleNameOf(element, options.probe, nameCache).length > 0) {
-    return true;
-  }
-  return role !== "generic" && role !== "image";
-}
-
-/** Push a skipped leaf's accessible name as loose text; true when one
- * was pushed (naming-prohibited roles contribute nothing). */
-function _hoistSkippedLeafName(
-  element: Element,
-  parentNode: SnapshotNode,
-  context: WalkContext,
-): boolean {
-  const name = _normalizedNodeName(
-    accessibleNameOf(element, context.options.probe, context.nameCache),
-  );
-  if (name === "") {
-    return false;
-  }
-  parentNode.children.push(name);
-  return true;
-}
-
-// --- the ref mint -----------------------------------------------------------
-
-function _refFor(element: Element, role: string, name: string): string {
-  const badge = _refBadgeByElement.get(element);
-  if (badge?.role === role && badge.name === name) {
-    _elementByRef.set(badge.ref, element);
-    return badge.ref;
-  }
-  _refCounter += 1;
-  const ref = `e${String(_refCounter)}`;
-  _refBadgeByElement.set(element, { role, name, ref });
-  _elementByRef.set(ref, element);
-  return ref;
-}