@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/lib/page-snapshot/capture/__tests__/walk.test.ts

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { walkDOM } from '../walk';
+import type { CSTInteractiveNode } from '../../cst/types';
+import { isContainerNode, isInteractiveNode } from '../../cst/types';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+/** Flatten a CST subtree to all interactive nodes. */
+function allInteractive(root: HTMLElement) {
+  const { children } = walkDOM(root);
+  const out: CSTInteractiveNode[] = [];
+  const visit = (nodes: ReturnType<typeof walkDOM>['children']) => {
+    for (const n of nodes) {
+      if (isInteractiveNode(n)) out.push(n);
+      else if (isContainerNode(n) || n.type === 'root') visit(n.children);
+    }
+  };
+  visit(children);
+  return out;
+}
+
+describe('walkDOM', () => {
+  it('captures interactive elements with refs', () => {
+    document.body.innerHTML = `
+      <form>
+        <label for="c">Company</label>
+        <input id="c" type="text" value="Acme" />
+        <button type="submit">Save</button>
+      </form>`;
+    const result = walkDOM(document.body);
+
+    const interactive = allInteractive(document.body);
+    expect(interactive).toHaveLength(2);
+    expect(interactive[0].ref).toBe('@e1');
+    expect(interactive[1].ref).toBe('@e2');
+    expect(result.refMap.size).toBe(2);
+  });
+
+  it('resolves accessible name from a <label for>', () => {
+    document.body.innerHTML = `
+      <label for="c">Company Name</label>
+      <input id="c" type="text" />`;
+    const [input] = allInteractive(document.body);
+    expect(input.name).toBe('Company Name');
+  });
+
+  it('captures input value and role', () => {
+    document.body.innerHTML = `<input type="search" value="hello" />`;
+    const [input] = allInteractive(document.body);
+    expect(input.role).toBe('searchbox');
+    expect(input.value).toBe('hello');
+  });
+
+  it('captures checkbox checked state, not value', () => {
+    document.body.innerHTML = `<input type="checkbox" checked />`;
+    const [cb] = allInteractive(document.body);
+    expect(cb.role).toBe('checkbox');
+    expect(cb.checked).toBe(true);
+    expect(cb.value).toBeUndefined();
+  });
+
+  it('captures disabled and required state', () => {
+    document.body.innerHTML = `
+      <input type="text" disabled required />`;
+    const [input] = allInteractive(document.body);
+    expect(input.disabled).toBe(true);
+    expect(input.required).toBe(true);
+  });
+
+  it('excludes chrome (nav) from the walk', () => {
+    document.body.innerHTML = `
+      <nav><a href="/x">Nav Link</a></nav>
+      <main><button>Real Button</button></main>`;
+    const interactive = allInteractive(document.body);
+    expect(interactive).toHaveLength(1);
+    expect(interactive[0].name).toBe('Real Button');
+  });
+
+  it('skips script/style tags', () => {
+    document.body.innerHTML = `
+      <div>
+        <script>var x = 1;</script>
+        <style>.a{}</style>
+        <p>Visible text</p>
+      </div>`;
+    const { children } = walkDOM(document.body);
+    const json = JSON.stringify(children);
+    expect(json).not.toContain('var x');
+    expect(json).not.toContain('.a{}');
+    expect(json).toContain('Visible text');
+  });
+
+  it('emits a placeholder for canvas/svg instead of descending', () => {
+    document.body.innerHTML = `
+      <canvas aria-label="Sales chart"></canvas>`;
+    const { children } = walkDOM(document.body);
+    expect(JSON.stringify(children)).toContain('[Sales chart]');
+  });
+
+  it('applies the redaction hook to values and text', () => {
+    document.body.innerHTML = `
+      <input type="text" value="secret-value" />
+      <p>plain paragraph</p>`;
+    const { children } = walkDOM(document.body, {
+      redactValue: (v, ctx) => (ctx.kind === 'value' ? '‹redacted›' : v),
+    });
+    const json = JSON.stringify(children);
+    expect(json).toContain('‹redacted›');
+    expect(json).not.toContain('secret-value');
+    expect(json).toContain('plain paragraph');
+  });
+
+  it('builds a container node for a form', () => {
+    document.body.innerHTML = `<form><button>Go</button></form>`;
+    const { children } = walkDOM(document.body);
+    const form = children.find(isContainerNode);
+    expect(form?.role).toBe('form');
+  });
+
+  it('honors maxNodes as a safety valve', () => {
+    document.body.innerHTML = `<div><div><div><button>x</button></div></div></div>`;
+    const result = walkDOM(document.body, { maxNodes: 2 });
+    expect(result.nodesVisited).toBeLessThanOrEqual(2);
+  });
+});

package/src/lib/page-snapshot/capture/accessible-name.ts

@@ -0,0 +1,73 @@
+/**
+ * Accessible-name resolution.
+ *
+ * A pragmatic subset of the ARIA accessible-name algorithm — enough to
+ * give the AI a meaningful label for interactive elements. Adapted from
+ * cmdop_browser/perception/axtree.py.
+ */
+
+import { tagName } from './dom-utils';
+
+/** Trim and collapse whitespace; cap length. */
+function clean(text: string, max = 120): string {
+  const t = text.replace(/\s+/g, ' ').trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}
+
+/** Escape a string for use in a CSS selector (CSS.escape fallback). */
+function escapeId(id: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(id);
+  }
+  // Minimal fallback: escape characters not valid in an unescaped ident.
+  return id.replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`);
+}
+
+/** Resolve the accessible name of an element. */
+export function accessibleName(el: Element): string {
+  // aria-label wins.
+  const ariaLabel = el.getAttribute('aria-label');
+  if (ariaLabel) return clean(ariaLabel);
+
+  // aria-labelledby → referenced element text.
+  const labelledBy = el.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    const parts = labelledBy
+      .split(/\s+/)
+      .map((id) => document.getElementById(id)?.textContent ?? '')
+      .filter(Boolean);
+    if (parts.length) return clean(parts.join(' '));
+  }
+
+  const tag = tagName(el);
+
+  // Form controls — associated <label>.
+  if (tag === 'input' || tag === 'select' || tag === 'textarea') {
+    const id = el.getAttribute('id');
+    if (id) {
+      const label = document.querySelector(`label[for="${escapeId(id)}"]`);
+      if (label?.textContent) return clean(label.textContent);
+    }
+    const wrapping = el.closest('label');
+    if (wrapping?.textContent) return clean(wrapping.textContent);
+    const placeholder = el.getAttribute('placeholder');
+    if (placeholder) return clean(placeholder);
+    const name = el.getAttribute('name');
+    if (name) return clean(name);
+  }
+
+  // Image — alt text.
+  if (tag === 'img') {
+    const alt = el.getAttribute('alt');
+    if (alt) return clean(alt);
+  }
+
+  // title attribute fallback.
+  const title = el.getAttribute('title');
+  if (title) return clean(title);
+
+  // Otherwise the element's own visible text (links, buttons).
+  if (el.textContent) return clean(el.textContent);
+
+  return '';
+}

package/src/lib/page-snapshot/capture/budget.ts

@@ -0,0 +1,95 @@
+/**
+ * Token-budget enforcement — degradation ladder.
+ *
+ * Sibling folding (fold.ts) runs first and always. If the snapshot is
+ * still over budget, this applies progressive degradation:
+ *   1. truncate long text nodes
+ *   2. drop static text, keep only interactive skeleton
+ *
+ */
+
+import type { CSTNode } from '../cst/types';
+import { hasChildren, isTextNode } from '../cst/types';
+import { serializeCST } from '../cst/serialize';
+import { estimateTokens } from '../tokens';
+
+/** Max characters a text node keeps under truncation. */
+const TEXT_TRUNCATE_CHARS = 150;
+
+/** What degradation, if any, was applied. */
+export type DegradationLevel = 'none' | 'truncated' | 'interactive-only';
+
+/** Result of budget enforcement. */
+export interface BudgetResult {
+  children: CSTNode[];
+  tokenEstimate: number;
+  degradation: DegradationLevel;
+}
+
+/** Estimate the token cost of a node list. */
+function costOf(children: CSTNode[]): number {
+  let total = 0;
+  for (const node of children) total += estimateTokens(serializeCST(node));
+  return total;
+}
+
+/** Truncate long text nodes recursively. */
+function truncateText(node: CSTNode): CSTNode {
+  if (isTextNode(node)) {
+    if (node.content.length <= TEXT_TRUNCATE_CHARS) return node;
+    return {
+      type: 'text',
+      content: `${node.content.slice(0, TEXT_TRUNCATE_CHARS)}… (truncated)`,
+    };
+  }
+  if (hasChildren(node)) {
+    return { ...node, children: node.children.map(truncateText) };
+  }
+  return node;
+}
+
+/** Keep only interactive nodes and the containers leading to them. */
+function pruneToInteractive(node: CSTNode): CSTNode | null {
+  if (node.type === 'interactive') return node;
+  if (node.type === 'text') return null;
+  if (hasChildren(node)) {
+    const kept = node.children
+      .map(pruneToInteractive)
+      .filter((n): n is CSTNode => n !== null);
+    if (kept.length === 0) return null;
+    return { ...node, children: kept };
+  }
+  return node;
+}
+
+/**
+ * Enforce the token budget on a captured node list via the degradation
+ * ladder. Folding is assumed already applied (fold.ts).
+ */
+export function enforceBudget(
+  children: CSTNode[],
+  tokenBudget: number,
+): BudgetResult {
+  let cost = costOf(children);
+  if (cost <= tokenBudget) {
+    return { children, tokenEstimate: cost, degradation: 'none' };
+  }
+
+  // Pass 1 — truncate long text.
+  const truncated = children.map(truncateText);
+  cost = costOf(truncated);
+  if (cost <= tokenBudget) {
+    return { children: truncated, tokenEstimate: cost, degradation: 'truncated' };
+  }
+
+  // Pass 2 — interactive-only skeleton.
+  const skeleton = truncated
+    .map(pruneToInteractive)
+    .filter((n): n is CSTNode => n !== null);
+  cost = costOf(skeleton);
+  return {
+    children: skeleton,
+    tokenEstimate: cost,
+    degradation: 'interactive-only',
+  };
+}

package/src/lib/page-snapshot/capture/chrome-filter.ts

@@ -0,0 +1,81 @@
+/**
+ * Layout-chrome exclusion.
+ *
+ * Identifies global navigation / header / footer / sidebar — the
+ * "chrome" that surrounds real content. Runs inside every scope tier
+ * and again during the walk, so the snapshot never wastes tokens on
+ * app shell the user is not asking about.
+ *
+ * Combines three signals: ARIA landmark roles, the
+ * Readability `unlikelyCandidates` class/id regex, and geometry
+ * (fixed-position bars).
+ */
+
+import { tagName } from './dom-utils';
+
+/** Landmark roles / tags that are chrome by definition. */
+const CHROME_ROLES: ReadonlySet<string> = new Set([
+  'navigation',
+  'banner',
+  'contentinfo',
+  'complementary',
+]);
+
+const CHROME_TAGS: ReadonlySet<string> = new Set([
+  'nav',
+  'header',
+  'footer',
+  'aside',
+]);
+
+/**
+ * Readability's `unlikelyCandidates` regex — class/id tokens that mark
+ * an element as non-content. Trimmed to the app-UI-relevant subset.
+ */
+const UNLIKELY_RE =
+  /(^|[\s_-])(nav|navbar|sidebar|side-?bar|menu|header|footer|banner|breadcrumb|toolbar|topbar|appbar|masthead|drawer|skip-?link)([\s_-]|$)/i;
+
+/** Roles that explicitly mark content — never treat these as chrome. */
+const CONTENT_RE = /(^|[\s_-])(main|content|article|workspace)([\s_-]|$)/i;
+
+/** Does the element's role / tag make it a landmark-level chrome region. */
+function isLandmarkChrome(el: Element): boolean {
+  const role = el.getAttribute('role')?.toLowerCase();
+  if (role && CHROME_ROLES.has(role)) return true;
+  if (CHROME_TAGS.has(tagName(el))) return true;
+  return false;
+}
+
+/** Does the class/id name pattern mark the element as chrome. */
+function isNamedChrome(el: Element): boolean {
+  const tokens = `${el.className ?? ''} ${el.id ?? ''}`;
+  if (!tokens.trim()) return false;
+  if (CONTENT_RE.test(tokens)) return false;
+  return UNLIKELY_RE.test(tokens);
+}
+
+/** Is the element a fixed/sticky global bar (geometry signal). */
+function isFixedBar(el: Element): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  const pos = getComputedStyle(el).position;
+  if (pos !== 'fixed' && pos !== 'sticky') return false;
+  // A fixed bar is typically thin relative to the viewport.
+  const rect = el.getBoundingClientRect();
+  const thin =
+    rect.height < window.innerHeight * 0.25 ||
+    rect.width < window.innerWidth * 0.25;
+  return thin;
+}
+
+/**
+ * Is this element layout chrome that should be excluded from capture.
+ *
+ * A content landmark (`<main>`, `[role=main]`, or a content-named
+ * element) is never chrome, even if nested oddly.
+ */
+export function isChrome(el: Element): boolean {
+  const role = el.getAttribute('role')?.toLowerCase();
+  if (role === 'main' || tagName(el) === 'main') return false;
+
+  return isLandmarkChrome(el) || isNamedChrome(el) || isFixedBar(el);
+}

package/src/lib/page-snapshot/capture/classify.ts

@@ -0,0 +1,111 @@
+/**
+ * Element classification — map a DOM element to a CST node kind & role.
+ *
+ * The role tables are adapted from cmdop_browser/perception/axtree.py
+ * (its `_AX_JS` role map).
+ */
+
+import type { CSTContainerRole, CSTInteractiveRole } from '../cst/types';
+import { tagName } from './dom-utils';
+
+/** How an element should be represented in the CST. */
+export type NodeKind = 'interactive' | 'container' | 'text-host' | 'skip';
+
+/** Tags that are always interactive. */
+const INTERACTIVE_TAG_ROLE: Record<string, CSTInteractiveRole> = {
+  a: 'link',
+  button: 'button',
+  select: 'select',
+  textarea: 'textarea',
+};
+
+/** `<input type>` → interactive role. */
+const INPUT_TYPE_ROLE: Record<string, CSTInteractiveRole> = {
+  button: 'button',
+  submit: 'button',
+  reset: 'button',
+  checkbox: 'checkbox',
+  radio: 'radio',
+  range: 'slider',
+  number: 'spinbutton',
+  search: 'searchbox',
+};
+
+/** ARIA roles we treat as interactive. */
+const ARIA_INTERACTIVE: ReadonlySet<string> = new Set([
+  'button',
+  'link',
+  'textbox',
+  'checkbox',
+  'radio',
+  'combobox',
+  'switch',
+  'tab',
+  'menuitem',
+  'slider',
+  'spinbutton',
+  'searchbox',
+]);
+
+/**
+ * Tag → container role.
+ *
+ * `tr` / `li` map to `section` so each row / list item stays its own
+ * node — this is what lets sibling folding collapse repetitive table
+ * rows and list items (see fold.ts). Without it the cells
+ * flatten into one undifferentiated list and folding cannot fire.
+ */
+const CONTAINER_TAG_ROLE: Record<string, CSTContainerRole> = {
+  form: 'form',
+  table: 'table',
+  thead: 'section',
+  tbody: 'section',
+  tr: 'section',
+  ul: 'list',
+  ol: 'list',
+  li: 'section',
+  nav: 'navigation',
+  section: 'section',
+  article: 'section',
+};
+
+/** ARIA role → container role. */
+const ARIA_CONTAINER: Record<string, CSTContainerRole> = {
+  form: 'form',
+  table: 'table',
+  grid: 'grid',
+  list: 'list',
+  navigation: 'navigation',
+  region: 'region',
+};
+
+/** Resolve the interactive role of an element, if it is interactive. */
+export function interactiveRole(el: Element): CSTInteractiveRole | null {
+  const aria = el.getAttribute('role')?.toLowerCase();
+  if (aria && ARIA_INTERACTIVE.has(aria)) {
+    return aria as CSTInteractiveRole;
+  }
+
+  const tag = tagName(el);
+  if (tag === 'input') {
+    const type = (el.getAttribute('type') ?? 'text').toLowerCase();
+    return INPUT_TYPE_ROLE[type] ?? 'textbox';
+  }
+  if (el.getAttribute('contenteditable') === 'true') return 'textbox';
+
+  return INTERACTIVE_TAG_ROLE[tag] ?? null;
+}
+
+/** Resolve the container role of an element, if it is a container. */
+export function containerRole(el: Element): CSTContainerRole | null {
+  const aria = el.getAttribute('role')?.toLowerCase();
+  if (aria && aria in ARIA_CONTAINER) return ARIA_CONTAINER[aria];
+  return CONTAINER_TAG_ROLE[tagName(el)] ?? null;
+}
+
+/** Classify an element into a CST node kind. */
+export function classify(el: Element): NodeKind {
+  if (interactiveRole(el)) return 'interactive';
+  if (containerRole(el)) return 'container';
+  return 'text-host';
+}

package/src/lib/page-snapshot/capture/dom-utils.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared DOM helpers for capture — visibility, geometry, classification.
+ *
+ * All layout reads (`getBoundingClientRect`, `getComputedStyle`) live
+ * here so callers can keep them out of the recursive walk — interleaving
+ * layout reads with the walk would cause layout thrashing.
+ */
+
+/** Tags that never contribute to a snapshot. */
+export const SKIP_TAGS: ReadonlySet<string> = new Set([
+  'script',
+  'style',
+  'noscript',
+  'meta',
+  'link',
+  'head',
+  'template',
+  'br',
+  'hr',
+]);
+
+/** Tags excluded but replaced with a placeholder (may carry text). */
+export const PLACEHOLDER_TAGS: ReadonlySet<string> = new Set([
+  'canvas',
+  'svg',
+  'iframe',
+]);
+
+/**
+ * Tags whose zero geometry must not mark them invisible — leaf controls
+ * and media that legitimately have no text content, plus table
+ * structure with no own box. Visibility for these is style-only.
+ */
+const ZERO_BOX_OK: ReadonlySet<string> = new Set([
+  // Form controls — leaf, often no text content.
+  'input',
+  'select',
+  'textarea',
+  'button',
+  'option',
+  'optgroup',
+  // Media / embedded — captured as placeholders.
+  'canvas',
+  'svg',
+  'img',
+  'iframe',
+  // Table structure with no own box.
+  'tr',
+  'tbody',
+  'thead',
+  'tfoot',
+  'colgroup',
+  'col',
+]);
+
+/**
+ * Is an element rendered — not display:none / visibility:hidden /
+ * collapsed to nothing.
+ *
+ * Visibility is decided primarily from computed *style* (reliable
+ * everywhere, including jsdom which does no layout). Geometry is only a
+ * secondary signal: a real zero-size box marks an element hidden, but
+ * an environment that reports zero geometry for everything (jsdom) must
+ * not blank the whole tree — so a zero box is only disqualifying when
+ * the element also has no text and no children.
+ */
+export function isVisible(el: Element): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  const style = getComputedStyle(el);
+  if (style.display === 'none') return false;
+  if (style.visibility === 'hidden' || style.visibility === 'collapse') {
+    return false;
+  }
+  if (style.opacity === '0') return false;
+  if (el.hasAttribute('hidden')) return false;
+  if (el.getAttribute('aria-hidden') === 'true') return false;
+
+  if (ZERO_BOX_OK.has(tagName(el))) return true;
+
+  const rect = el.getBoundingClientRect();
+  if (rect.width === 0 && rect.height === 0) {
+    // A truly empty zero-box is hidden; but an element with content and
+    // a zero box is likely just an un-laid-out environment — keep it.
+    const hasContent =
+      el.children.length > 0 || (el.textContent ?? '').trim().length > 0;
+    return hasContent;
+  }
+  return true;
+}
+
+/** Rendered area of an element in CSS pixels. */
+export function elementArea(el: Element): number {
+  const rect = el.getBoundingClientRect();
+  return Math.max(0, rect.width) * Math.max(0, rect.height);
+}
+
+/** Ratio of link-text length to total text length in a subtree (0–1). */
+export function linkDensity(el: Element): number {
+  const total = (el.textContent ?? '').trim().length;
+  if (total === 0) return 0;
+  let linkChars = 0;
+  el.querySelectorAll('a').forEach((a) => {
+    linkChars += (a.textContent ?? '').trim().length;
+  });
+  return Math.min(1, linkChars / total);
+}
+
+/** lowercased tag name. */
+export function tagName(el: Element): string {
+  return el.tagName.toLowerCase();
+}

package/src/lib/page-snapshot/capture/fold.ts

@@ -0,0 +1,96 @@
+/**
+ * Sibling folding — collapse repetitive structure.
+ *
+ * Always-on, applied to every node list. Structurally-identical sibling
+ * chains (table rows, list items, grid cells) collapse to "first N +
+ * a collapsed marker". This is what makes a 100-row data table fit the
+ * token budget — without it a 100-row table snapshot is ~10x over.
+ *
+ */
+
+import type { CSTNode } from '../cst/types';
+import { hasChildren } from '../cst/types';
+
+/** How many leading instances of a repeated chain to keep. */
+const KEEP_LEADING = 3;
+/** A chain shorter than this is never folded. */
+const MIN_CHAIN = 5;
+
+/** Result of a folding pass. */
+export interface FoldResult {
+  /** The folded tree. */
+  children: CSTNode[];
+  /** How many sibling chains were folded. */
+  foldedCount: number;
+}
+
+/**
+ * A shallow structural hash of a node — its shape, not its content.
+ * Two nodes with the same hash are "the same kind of thing" (e.g. two
+ * table rows), regardless of the text they hold.
+ */
+function structuralHash(node: CSTNode): string {
+  switch (node.type) {
+    case 'text':
+      return 't';
+    case 'interactive':
+      return `i:${node.role}`;
+    case 'container':
+      return `c:${node.role}:[${node.children
+        .map(structuralHash)
+        .join(',')}]`;
+    case 'root':
+      return 'root';
+  }
+}
+
+/** Counter threaded through a recursive fold so totals aggregate. */
+interface FoldCtx {
+  folded: number;
+}
+
+/** Fold one list of sibling nodes. */
+function foldList(nodes: CSTNode[], ctx: FoldCtx): CSTNode[] {
+  // Recurse first so nested lists are folded before the outer pass.
+  const deep = nodes.map((n) => foldNode(n, ctx));
+
+  const out: CSTNode[] = [];
+  let i = 0;
+  while (i < deep.length) {
+    const hash = structuralHash(deep[i]);
+    // Extend the run of identically-shaped siblings.
+    let j = i + 1;
+    while (j < deep.length && structuralHash(deep[j]) === hash) j++;
+    const runLength = j - i;
+
+    if (runLength >= MIN_CHAIN) {
+      // Keep the leading N, collapse the rest into one marker.
+      for (let k = i; k < i + KEEP_LEADING; k++) out.push(deep[k]);
+      const collapsed = runLength - KEEP_LEADING;
+      out.push({
+        type: 'text',
+        content: `[… ${collapsed} more similar items collapsed]`,
+      });
+      ctx.folded++;
+    } else {
+      for (let k = i; k < j; k++) out.push(deep[k]);
+    }
+    i = j;
+  }
+  return out;
+}
+
+/** Recursively fold a single node's children. */
+function foldNode(node: CSTNode, ctx: FoldCtx): CSTNode {
+  if (!hasChildren(node)) return node;
+  return { ...node, children: foldList(node.children, ctx) };
+}
+
+/**
+ * Fold repetitive sibling chains within a node list.
+ */
+export function foldSiblings(children: CSTNode[]): FoldResult {
+  const ctx: FoldCtx = { folded: 0 };
+  const folded = foldList(children, ctx);
+  return { children: folded, foldedCount: ctx.folded };
+}