@nexface/tools 0.1.0

package/src/browser/snapshot.ts

@@ -0,0 +1,542 @@
+import {
+  composedChildren,
+  composedParent,
+  computeNameInfo,
+  computeRole,
+  computeState,
+  createIdentity,
+  createScrollableIdentity,
+  findNearestHeadingText,
+  getElementScrollability,
+  isActionableRole,
+  isContextRole,
+  isElementInViewport,
+  isElementRendered,
+  normalizeText,
+  walkComposedElements,
+} from "./dom.js";
+import type { ElementScrollability, NameSource } from "./dom.js";
+import type {
+  PageSnapshot,
+  SemanticState,
+  SnapshotBundle,
+  SnapshotLimits,
+  SnapshotRegistry,
+  SnapshotScope,
+} from "./types.js";
+
+interface RenderNode {
+  element?: Element;
+  role: string;
+  name: string;
+  normalizedName: string;
+  nameSource: NameSource;
+  state: SemanticState;
+  actionable: boolean;
+  scrollable?: ElementScrollability;
+  children: RenderNode[];
+}
+
+interface WalkContext {
+  scope: SnapshotScope;
+  activeModal?: Element;
+  allowedPortalRoots: Set<Element>;
+  styles: WeakMap<Element, CSSStyleDeclaration>;
+  rects: WeakMap<Element, DOMRect>;
+  visitedNodes: number;
+  maxVisitedNodes: number;
+  truncated: boolean;
+  execution?: SnapshotExecutionContext;
+}
+
+interface RenderContext {
+  refs: SnapshotRegistry["refs"];
+  maxChars: number;
+  usedChars: number;
+  lines: string[];
+  truncated: boolean;
+  renderedNodes: number;
+  execution?: SnapshotExecutionContext;
+}
+
+export interface SnapshotExecutionContext {
+  deadline: number;
+  signal: AbortSignal;
+}
+
+const DEFAULT_LIMITS: SnapshotLimits = {
+  viewportMaxChars: 18_000,
+  viewportMaxVisitedNodes: 12_000,
+  fullMaxChars: 50_000,
+  fullMaxVisitedNodes: 30_000,
+};
+
+const STRUCTURAL_ROLES = new Set([
+  "alert",
+  "alertdialog",
+  "dialog",
+  "form",
+  "heading",
+  "iframe",
+  "list",
+  "listbox",
+  "menu",
+  "navigation",
+  "progressbar",
+  "region",
+  "row",
+  "rowgroup",
+  "status",
+  "table",
+  "tooltip",
+  "tree",
+  "listitem",
+]);
+
+const PORTAL_ROLES = new Set([
+  "alert",
+  "listbox",
+  "menu",
+  "progressbar",
+  "status",
+  "tooltip",
+  "tree",
+]);
+
+const REDUNDANT_WRAPPER_ROLES = new Set(["group", "listitem"]);
+
+function checkExecution(context?: SnapshotExecutionContext): void {
+  if (!context) return;
+  context.signal.throwIfAborted();
+  if (performance.now() >= context.deadline) {
+    throw new DOMException(
+      "Snapshot collection exceeded the executeCode deadline.",
+      "TimeoutError",
+    );
+  }
+}
+
+function nextAnimationFrame(
+  context?: SnapshotExecutionContext,
+): Promise<void> {
+  checkExecution(context);
+  if (!context) {
+    return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let frame = 0;
+    const remaining = Math.max(0, context.deadline - performance.now());
+    const cleanup = (): void => {
+      window.clearTimeout(timer);
+      context.signal.removeEventListener("abort", onAbort);
+    };
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error) reject(error);
+      else resolve();
+    };
+    const onAbort = (): void => finish(
+      context.signal.reason instanceof Error
+        ? context.signal.reason
+        : new DOMException("Execution cancelled.", "AbortError"),
+    );
+    const timer = window.setTimeout(() => finish(new DOMException(
+      "Snapshot collection exceeded the executeCode deadline.",
+      "TimeoutError",
+    )), remaining);
+    context.signal.addEventListener("abort", onAbort, { once: true });
+    frame = requestAnimationFrame(() => finish());
+    if (settled && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(frame);
+    }
+  });
+}
+
+function cachedStyle(
+  element: Element,
+  cache: WeakMap<Element, CSSStyleDeclaration>,
+): CSSStyleDeclaration {
+  const existing = cache.get(element);
+  if (existing) return existing;
+  const style = getComputedStyle(element);
+  cache.set(element, style);
+  return style;
+}
+
+function cachedRect(
+  element: Element,
+  cache: WeakMap<Element, DOMRect>,
+): DOMRect {
+  const existing = cache.get(element);
+  if (existing) return existing;
+  const rect = element.getBoundingClientRect();
+  cache.set(element, rect);
+  return rect;
+}
+
+function isTextInScope(node: Text, context: WalkContext): boolean {
+  if (!normalizeText(node.data)) return false;
+  const parent = node.parentElement;
+  if (!parent) return false;
+  const style = cachedStyle(parent, context.styles);
+  if (!isElementRendered(parent, style)) return false;
+  if (context.scope === "full") return true;
+  const parentRect = cachedRect(parent, context.rects);
+  if (!isElementInViewport(parent, parentRect)) return false;
+  const range = document.createRange();
+  range.selectNodeContents(node);
+  const rect = range.getBoundingClientRect();
+  range.detach();
+  return (
+    rect.width > 0 &&
+    rect.height > 0 &&
+    rect.right > 0 &&
+    rect.bottom > 0 &&
+    rect.left < window.innerWidth &&
+    rect.top < window.innerHeight
+  );
+}
+
+function isElementInScope(element: Element, context: WalkContext): boolean {
+  const style = cachedStyle(element, context.styles);
+  if (!isElementRendered(element, style)) return false;
+  if (context.scope === "full") {
+    const rect = cachedRect(element, context.rects);
+    return rect.width > 0 && rect.height > 0;
+  }
+  return isElementInViewport(element, cachedRect(element, context.rects));
+}
+
+function isDescendantOrSelf(element: Element, ancestor: Element): boolean {
+  if (element === ancestor) return true;
+  let current: Element | null = element;
+  while (current) {
+    if (current === ancestor) return true;
+    current = composedParent(current);
+  }
+  return false;
+}
+
+function isAllowedByModal(element: Element, context: WalkContext): boolean {
+  if (!context.activeModal) return true;
+  if (isDescendantOrSelf(element, context.activeModal)) return true;
+  for (const root of context.allowedPortalRoots) {
+    if (isDescendantOrSelf(element, root)) return true;
+  }
+  return false;
+}
+
+function normalizeNodeChildren(node: RenderNode): void {
+  const merged: RenderNode[] = [];
+  for (const child of node.children) {
+    const previous = merged.at(-1);
+    if (
+      child.role === "text" &&
+      previous?.role === "text" &&
+      !child.element &&
+      !previous.element
+    ) {
+      previous.name = normalizeText(`${previous.name} ${child.name}`);
+      previous.normalizedName = previous.name;
+      continue;
+    }
+    merged.push(child);
+  }
+
+  const directText = normalizeText(
+    merged
+      .filter((child) => child.role === "text")
+      .map((child) => child.name)
+      .join(" "),
+  );
+  node.children =
+    node.normalizedName &&
+    directText &&
+    node.normalizedName === directText
+      ? merged.filter((child) => child.role !== "text")
+      : merged;
+
+  const onlyChild = node.children.length === 1 ? node.children[0] : undefined;
+  if (
+    REDUNDANT_WRAPPER_ROLES.has(node.role) &&
+    node.nameSource === "content" &&
+    !node.actionable &&
+    Object.keys(node.state).length === 0 &&
+    onlyChild &&
+    onlyChild.role !== "text" &&
+    node.normalizedName === onlyChild.normalizedName
+  ) {
+    node.name = "";
+    node.normalizedName = "";
+  }
+}
+
+function visitNode(node: Node, context: WalkContext): RenderNode[] {
+  context.visitedNodes += 1;
+  if (context.visitedNodes % 128 === 0) checkExecution(context.execution);
+  if (context.visitedNodes > context.maxVisitedNodes) {
+    context.truncated = true;
+    return [];
+  }
+
+  if (node instanceof Text) {
+    if (!isTextInScope(node, context)) return [];
+    const parent = node.parentElement;
+    if (parent && !isAllowedByModal(parent, context)) return [];
+    return [{
+      role: "text",
+      name: normalizeText(node.data),
+      normalizedName: normalizeText(node.data),
+      nameSource: "content",
+      state: {},
+      actionable: false,
+      children: [],
+    }];
+  }
+
+  if (!(node instanceof Element)) return [];
+  const tag = node.tagName.toLowerCase();
+  if (["script", "style", "template", "meta", "link", "noscript"].includes(tag)) {
+    return [];
+  }
+
+  const style = cachedStyle(node, context.styles);
+  if (!isElementRendered(node, style)) return [];
+
+  const children = composedChildren(node).flatMap((child) =>
+    visitNode(child, context),
+  );
+  const inScope = isElementInScope(node, context);
+  const allowed = isAllowedByModal(node, context);
+  const role = computeRole(node);
+  const state = computeState(node);
+  const inferredActionable = isActionableRole(role);
+  const focusOnlyActionable =
+    role === "actionable" &&
+    node instanceof HTMLElement &&
+    node.tabIndex >= 0 &&
+    node.onclick === null &&
+    !node.hasAttribute("onclick") &&
+    !node.isContentEditable;
+  const scrollable = inScope && (!inferredActionable || focusOnlyActionable)
+    ? getElementScrollability(node, style)
+    : undefined;
+  const actionable = inferredActionable && !scrollable;
+  const hasState = Object.keys(state).length > 0;
+  const keep =
+    allowed &&
+    ((inScope && (actionable || scrollable || STRUCTURAL_ROLES.has(role) || hasState)) ||
+      (children.length > 0 && (isContextRole(role) || role === "table" || role === "list")));
+
+  if (!keep) return children;
+
+  const computedName = computeNameInfo(node);
+  const scrollableName =
+    scrollable && computedName.source === "content"
+      ? findNearestHeadingText(node)
+      : computedName.value || (scrollable ? findNearestHeadingText(node) : "");
+  const renderNode: RenderNode = {
+    element: node,
+    role: scrollable && (!role || role === "actionable")
+      ? "scrollable"
+      : role || "group",
+    name: scrollableName,
+    normalizedName: normalizeText(scrollableName),
+    nameSource: computedName.source,
+    state,
+    actionable,
+    ...(scrollable ? { scrollable } : {}),
+    children,
+  };
+  normalizeNodeChildren(renderNode);
+  return [renderNode];
+}
+
+function isVisibleModal(element: Element): boolean {
+  const role = computeRole(element);
+  const ariaModal =
+    role === "dialog" && element.getAttribute("aria-modal") === "true";
+  const alertDialog = role === "alertdialog";
+  let nativeModal = false;
+  if (element instanceof HTMLDialogElement && element.open) {
+    try {
+      nativeModal = element.matches(":modal");
+    } catch {
+      nativeModal = element.open;
+    }
+  }
+  return (ariaModal || alertDialog || nativeModal) && isElementInViewport(element);
+}
+
+function findActiveModal(
+  execution?: SnapshotExecutionContext,
+): Element | undefined {
+  let activeModal: Element | undefined;
+  let visited = 0;
+  for (const element of walkComposedElements()) {
+    visited += 1;
+    if (visited % 128 === 0) checkExecution(execution);
+    if (isVisibleModal(element)) activeModal = element;
+  }
+  return activeModal;
+}
+
+function findPortalRoots(
+  activeModal: Element,
+  execution?: SnapshotExecutionContext,
+): Set<Element> {
+  const roots = new Set<Element>();
+  let visited = 0;
+  for (const element of walkComposedElements()) {
+    visited += 1;
+    if (visited % 128 === 0) checkExecution(execution);
+    if (isDescendantOrSelf(element, activeModal)) continue;
+    const role = computeRole(element);
+    if (
+      (PORTAL_ROLES.has(role) || element.hasAttribute("aria-live")) &&
+      isElementInViewport(element)
+    ) {
+      roots.add(element);
+    }
+  }
+  return roots;
+}
+
+function serializeState(state: SemanticState): string {
+  const entries = Object.entries(state);
+  if (entries.length === 0) return "";
+  return ` [${entries
+    .map(([key, value]) =>
+      typeof value === "boolean"
+        ? value
+          ? key
+          : `${key}=false`
+        : `${key}=${JSON.stringify(value)}`,
+    )
+    .join(" ")}]`;
+}
+
+function serializeScrollability(value: ElementScrollability | undefined): string {
+  if (!value) return "";
+  const axis = value.x && value.y ? "xy" : value.y ? "y" : "x";
+  const metrics = value.y
+    ? `scrollTop=${value.scrollTop} scrollHeight=${value.scrollHeight} clientHeight=${value.clientHeight}`
+    : `scrollLeft=${value.scrollLeft} scrollWidth=${value.scrollWidth} clientWidth=${value.clientWidth}`;
+  return ` [axis=${axis} ${metrics}]`;
+}
+
+function renderTree(nodes: RenderNode[], context: RenderContext): void {
+  const renderNode = (node: RenderNode, depth: number): void => {
+    if (context.truncated) return;
+    context.renderedNodes += 1;
+    if (context.renderedNodes % 128 === 0) {
+      checkExecution(context.execution);
+    }
+    const indent = "  ".repeat(Math.min(depth, 6));
+    const name = node.name ? ` ${JSON.stringify(normalizeText(node.name))}` : "";
+    const state = serializeState(node.state);
+    const scrollability = serializeScrollability(node.scrollable);
+    const nextRef = node.actionable || node.scrollable
+      ? `@${context.refs.size + 1}`
+      : undefined;
+    const refText = nextRef ? ` [ref=${nextRef}]` : "";
+    const prefix = node.role === "text" ? `${indent}- text:` : `${indent}- ${node.role}`;
+    const line =
+      node.role === "text"
+        ? `${prefix} ${JSON.stringify(normalizeText(node.name))}`
+        : `${prefix}${name}${state}${scrollability}${refText}`;
+
+    const added = line.length + (context.lines.length > 0 ? 1 : 0);
+    if (context.usedChars + added > context.maxChars) {
+      context.truncated = true;
+      return;
+    }
+
+    context.lines.push(line);
+    context.usedChars += added;
+    if (nextRef && node.element) {
+      context.refs.set(nextRef, {
+        element: node.element,
+        identity: node.scrollable
+          ? createScrollableIdentity(node.element)
+          : createIdentity(node.element),
+        kind: node.scrollable ? "scrollable" : "element",
+      });
+    }
+
+    for (const child of node.children) renderNode(child, depth + 1);
+  };
+
+  for (const node of nodes) renderNode(node, 0);
+}
+
+export async function createSnapshot(
+  scope: SnapshotScope = "viewport",
+  limits: Partial<SnapshotLimits> = {},
+  execution?: SnapshotExecutionContext,
+): Promise<SnapshotBundle> {
+  await nextAnimationFrame(execution);
+  checkExecution(execution);
+  const resolvedLimits = { ...DEFAULT_LIMITS, ...limits };
+  const activeModal = findActiveModal(execution);
+  const walkContext: WalkContext = {
+    scope,
+    ...(activeModal ? { activeModal } : {}),
+    allowedPortalRoots: activeModal
+      ? findPortalRoots(activeModal, execution)
+      : new Set(),
+    styles: new WeakMap(),
+    rects: new WeakMap(),
+    visitedNodes: 0,
+    maxVisitedNodes:
+      scope === "viewport"
+        ? resolvedLimits.viewportMaxVisitedNodes
+        : resolvedLimits.fullMaxVisitedNodes,
+    truncated: false,
+    ...(execution ? { execution } : {}),
+  };
+
+  const tree = composedChildren(document.body).flatMap((node) =>
+    visitNode(node, walkContext),
+  );
+  const snapshotId = `s-${crypto.randomUUID()}`;
+  const registry: SnapshotRegistry = {
+    snapshotId,
+    refs: new Map(),
+  };
+  const renderContext: RenderContext = {
+    refs: registry.refs,
+    maxChars:
+      scope === "viewport"
+        ? resolvedLimits.viewportMaxChars
+        : resolvedLimits.fullMaxChars,
+    usedChars: 0,
+    lines: [],
+    truncated: false,
+    renderedNodes: 0,
+    ...(execution ? { execution } : {}),
+  };
+  renderTree(tree, renderContext);
+  checkExecution(execution);
+
+  const snapshot: PageSnapshot = {
+    snapshotId,
+    scope,
+    url: location.href,
+    title: document.title,
+    content: renderContext.lines.join("\n"),
+    truncated: walkContext.truncated || renderContext.truncated,
+  };
+
+  return { snapshot, registry };
+}
+
+export async function getSnapshot(
+  scope: SnapshotScope = "viewport",
+  limits: Partial<SnapshotLimits> = {},
+): Promise<PageSnapshot> {
+  return (await createSnapshot(scope, limits)).snapshot;
+}