@comty.io/core 0.1.8 → 0.1.10

package/src/resilient-anchor.ts

@@ -0,0 +1,551 @@
+// Shared with Hephaistos' commentaires/resilient-anchor.ts. Keep both copies identical.
+// No framework internals, authored IDs or editable values are required.
+interface Fingerprint {
+  tag: string;
+  attributes: Record<string, string>;
+  classes: string[];
+  text: string;
+  heading: string;
+  shape: string[];
+}
+
+export interface ResilientAnchor {
+  version: 1;
+  target: Fingerprint;
+  ancestors: Fingerprint[];
+  layer?: Fingerprint | null;
+  scope: number;
+  twins: number;
+  group: number;
+}
+
+export type AnchorResolution = {
+  element: Element | null;
+  status: "matched" | "hidden" | "missing" | "uncertain";
+};
+
+const generatedId =
+  /^(?:(?:radix|base-ui)-)?(?:_r_[\w-]+_|:r[\w-]+:)$|^mat-|^cdk-|^ng-/i;
+const anchorAttributes = [
+  "id",
+  "data-testid",
+  "data-test",
+  "data-cy",
+  "role",
+  "name",
+  "type",
+  "href",
+  "src",
+  "aria-label",
+  "alt",
+  "title",
+  "placeholder",
+];
+
+/** Read saved formats as evidence for the same engine; never reconstruct missing history from the DOM. */
+export function readAnchor(value: unknown): ResilientAnchor | null {
+  const record = (item: unknown): Record<string, unknown> =>
+    item && typeof item === "object" && !Array.isArray(item)
+      ? (item as Record<string, unknown>)
+      : {};
+  const raw = record(value);
+  const saved = raw.resilient ?? raw.anchor ?? value;
+  if (isResilientAnchor(saved)) return saved;
+  // A malformed current fingerprint must not silently become a selector-only anchor.
+  if (
+    raw.resilient !== undefined ||
+    raw.anchor !== undefined ||
+    "shape" in record(raw.target)
+  )
+    return null;
+  const context = record(raw.context);
+  const source = context.element ? context : raw;
+  const target = record(
+    source.element ??
+      source.target ??
+      (source.tag ? source : { text: source.text }),
+  );
+  const string = (item: unknown) =>
+    typeof item === "string" ? item.trim().slice(0, 160) : "";
+  const convert = (item: Record<string, unknown>): Fingerprint => {
+    const stored = record(item.attributes);
+    const attributes: Record<string, string> = {};
+    for (const name of anchorAttributes) {
+      const alias =
+        name === "aria-label"
+          ? "ariaLabel"
+          : name === "data-testid"
+            ? "testId"
+            : name;
+      const text = string(stored[name] ?? item[alias]);
+      if (text && !(name === "id" && generatedId.test(text)))
+        attributes[name] = text;
+    }
+    const tag = string(item.tag).toLowerCase();
+    return {
+      tag: /^[a-z][a-z0-9-]{0,79}$/.test(tag) ? tag : "*",
+      attributes,
+      classes: (Array.isArray(item.classes)
+        ? item.classes
+        : string(stored.class).split(/\s+/)
+      )
+        .filter(
+          (name): name is string =>
+            typeof name === "string" &&
+            !!name &&
+            name.length <= 80 &&
+            !/^(ng-|comty-|hph-)/.test(name),
+        )
+        .slice(0, 8),
+      text: /^(input|textarea|select)$/.test(tag)
+        ? ""
+        : string(item.text ?? item.ownText),
+      heading: "",
+      shape: [],
+    };
+  };
+  const ancestors = (Array.isArray(source.ancestors) ? source.ancestors : [])
+    .slice(0, 8)
+    .map((item) => convert(record(item)))
+    .filter((item) => item.tag !== "*" && !/^(body|html)$/.test(item.tag));
+  const inferredLayer = ancestors.find(
+    (item) =>
+      item.tag === "dialog" ||
+      /^(dialog|alertdialog)$/.test(item.attributes.role ?? ""),
+  );
+  return {
+    version: 1,
+    target: convert(target),
+    ancestors,
+    layer: source.layer
+      ? convert(record(source.layer))
+      : source.layer === null
+        ? null
+        : inferredLayer,
+    scope: -1,
+    group: -1,
+    twins:
+      typeof source.candidateCount === "number" &&
+      Number.isInteger(source.candidateCount) &&
+      source.candidateCount > 1
+        ? source.candidateCount
+        : 1,
+  };
+}
+
+export function createResilientAnchors(
+  excluded: (element: Element) => boolean,
+  presentationLayer = (element: Element): Element | null =>
+    element.closest('dialog, [role="dialog"], [role="alertdialog"], [popover]'),
+) {
+  const editable =
+    'input, textarea, select, [contenteditable]:not([contenteditable="false"])';
+  const attributes = anchorAttributes;
+  const stable = new Set([
+    "id",
+    "data-testid",
+    "data-test",
+    "data-cy",
+    "name",
+    "href",
+  ]);
+  let fingerprints = new WeakMap<Element, Fingerprint>();
+
+  function children(element: Element): Element[] {
+    return [...element.children].filter((child) => !excluded(child));
+  }
+
+  function semantic(element: Element): string {
+    const role = element.getAttribute("role");
+    if (role) return role.slice(0, 80);
+    const tag = element.localName;
+    if (/^h[1-6]$/.test(tag)) return "heading";
+    if (tag === "svg" || tag === "img" || tag.endsWith("-icon")) return "image";
+    return /^(button|a|input|textarea|select|p|table|tr|td|th|ul|ol|li|dl|dt|dd|canvas|video)$/.test(
+      tag,
+    )
+      ? tag
+      : "";
+  }
+
+  function shape(element: Element): string[] {
+    const counts = new Map<string, number>();
+    const queue = [element];
+    let visited = 0;
+    while (queue.length && visited++ < 120) {
+      const node = queue.shift();
+      if (!node || excluded(node)) continue;
+      const token = semantic(node);
+      if (token) counts.set(token, Math.min(3, (counts.get(token) ?? 0) + 1));
+      if (token === "image" || node.matches(editable)) continue;
+      const descendants = children(node);
+      // Repeated cards are data even when a prototype uses only generic divs.
+      const patterns = new Map<string, number>();
+      for (const child of descendants.slice(0, 24)) {
+        const parts = children(child).map(semantic).filter(Boolean);
+        if (parts.length < 2) continue;
+        const key = parts.join("/");
+        patterns.set(key, (patterns.get(key) ?? 0) + 1);
+      }
+      if ([...patterns.values()].some((count) => count >= 2))
+        counts.set("records", 3);
+      queue.push(...descendants.slice(0, 40));
+    }
+    return [...counts]
+      .flatMap(([token, count]) => Array<string>(count).fill(token))
+      .sort();
+  }
+
+  function text(element: Element): string {
+    if (element.closest(editable)) return "";
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+    let result = "",
+      count = 0;
+    for (
+      let node = walker.nextNode();
+      node && count++ < 100 && result.length < 160;
+      node = walker.nextNode()
+    ) {
+      const parent = node.parentElement;
+      if (
+        parent &&
+        !excluded(parent) &&
+        !parent.closest(`${editable}, script, style`)
+      )
+        result += ` ${node.textContent ?? ""}`;
+    }
+    return result.replace(/\s+/g, " ").trim().slice(0, 160);
+  }
+
+  function fingerprint(element: Element): Fingerprint {
+    const cached = fingerprints.get(element);
+    if (cached) return cached;
+    const attrs: Record<string, string> = {};
+    for (const name of attributes) {
+      const value = element.getAttribute(name)?.trim();
+      if (value && !(name === "id" && generatedId.test(value)))
+        attrs[name] = value.slice(0, 160);
+    }
+    const result = {
+      tag: element.localName,
+      attributes: attrs,
+      classes: [...element.classList]
+        .filter((name) => name.length <= 80 && !/^(ng-|comty-|hph-)/.test(name))
+        .slice(0, 8),
+      text: text(element),
+      heading: (() => {
+        const heading = element.querySelector("h1, h2, h3, h4, h5, h6, legend");
+        return heading && !excluded(heading) ? text(heading) : "";
+      })(),
+      shape: shape(element),
+    };
+    fingerprints.set(element, result);
+    return result;
+  }
+
+  function parents(element: Element): Element[] {
+    const result: Element[] = [];
+    for (
+      let parent = element.parentElement;
+      parent && parent !== document.body && result.length < 10;
+      parent = parent.parentElement
+    ) {
+      if (!excluded(parent)) result.push(parent);
+    }
+    return result;
+  }
+
+  function overlap(left: string[], right: string[]): number {
+    const remaining = [...right];
+    let count = 0;
+    for (const item of left) {
+      const index = remaining.indexOf(item);
+      if (index >= 0) {
+        count++;
+        remaining.splice(index, 1);
+      }
+    }
+    return count;
+  }
+
+  function score(saved: Fingerprint, current: Fingerprint): number {
+    if (saved.tag !== "*" && saved.tag !== current.tag) return -100;
+    let result = 20;
+    for (const [name, value] of Object.entries(saved.attributes)) {
+      if (current.attributes[name] === value)
+        result += stable.has(name) ? 45 : 12;
+      else if (stable.has(name) && current.attributes[name]) result -= 35;
+    }
+    result += Math.min(24, overlap(saved.classes, current.classes) * 12);
+    if (saved.text && saved.text === current.text) result += 36;
+    else if (saved.text && current.text) {
+      const left = [...new Set(saved.text.toLowerCase().split(/\s+/))];
+      const right = [...new Set(current.text.toLowerCase().split(/\s+/))];
+      if (overlap(left, right) / Math.max(left.length, right.length) >= 0.7)
+        result += 18;
+    }
+    if (saved.heading && saved.heading === current.heading) result += 24;
+    const total = Math.max(saved.shape.length, current.shape.length);
+    result += saved.shape.length
+      ? (12 * overlap(saved.shape, current.shape)) / total
+      : 12;
+    return result;
+  }
+
+  function differentState(saved: Fingerprint, current: Fingerprint): boolean {
+    // A changed label, wrapper, style or list length is never enough to hide a pin.
+    if (saved.shape.length < 3 || current.shape.length < 3) return false;
+    const hasRecords = (tokens: string[]) =>
+      tokens.some((token) => /^(records|tr|li|row|listitem)$/.test(token));
+    // Illustration replaced by repeated records is a state change even with the same headings/actions.
+    if (
+      hasRecords(saved.shape) !== hasRecords(current.shape) &&
+      saved.shape.includes("image") !== current.shape.includes("image")
+    )
+      return true;
+    const common = overlap(saved.shape, current.shape);
+    return (
+      common / saved.shape.length < 0.45 && common / current.shape.length < 0.45
+    );
+  }
+
+  function twins(
+    element: Element,
+    saved: Fingerprint,
+    includeText = false,
+  ): number {
+    return (
+      element.parentElement ? children(element.parentElement) : [element]
+    ).filter((child) => {
+      const candidate = fingerprint(child);
+      return (
+        candidate.tag === saved.tag &&
+        (!includeText || candidate.text === saved.text) &&
+        attributes.every(
+          (name) => candidate.attributes[name] === saved.attributes[name],
+        )
+      );
+    }).length;
+  }
+
+  function capture(element: Element): ResilientAnchor {
+    fingerprints = new WeakMap();
+    const target = fingerprint(element);
+    const ancestors = parents(element).slice(0, 8).map(fingerprint);
+    const layer = presentationLayer(element);
+    // Bind to the nearest small composition, not to the state of the entire page.
+    const scope = [target, ...ancestors.slice(0, 3)].findIndex(
+      (item) =>
+        !/^(main|body|html|nav)$/.test(item.tag) &&
+        item.shape.length >= 3 &&
+        item.shape.length <= 18,
+    );
+    const group = [element, ...parents(element).slice(0, 8)].findIndex(
+      (node) => {
+        const saved = fingerprint(node);
+        return (
+          saved.shape.length >= 2 &&
+          node.parentElement &&
+          children(node.parentElement).filter((peer) => {
+            const other = fingerprint(peer);
+            return (
+              other.tag === saved.tag &&
+              overlap(saved.shape, other.shape) /
+                Math.max(saved.shape.length, other.shape.length) >
+                0.8
+            );
+          }).length > 1
+        );
+      },
+    );
+    return {
+      version: 1,
+      target,
+      ancestors,
+      layer: layer ? fingerprint(layer) : null,
+      scope,
+      group,
+      twins: twins(element, target, true),
+    };
+  }
+
+  function resolve(
+    anchor: ResilientAnchor,
+    previous: Element | null = null,
+    exact: Element | null = null,
+  ): AnchorResolution {
+    fingerprints = new WeakMap();
+    const candidates = (
+      anchor.target.tag === "*"
+        ? exact
+          ? [exact]
+          : []
+        : [...document.getElementsByTagName(anchor.target.tag)]
+    ).filter((element) => !excluded(element));
+    const ranked: { element: Element; score: number; changed: boolean }[] = [];
+    for (const element of candidates) {
+      const layer = presentationLayer(element);
+      if (anchor.layer !== undefined && !!layer !== !!anchor.layer) continue;
+      if (layer && anchor.layer && score(anchor.layer, fingerprint(layer)) < 45)
+        continue;
+      const current = fingerprint(element);
+      // Never attach a removed, explicitly identified control to another identified one.
+      if (
+        Object.keys(anchor.target.attributes).some(
+          (name) =>
+            stable.has(name) &&
+            current.attributes[name] &&
+            current.attributes[name] !== anchor.target.attributes[name],
+        )
+      )
+        continue;
+      if (
+        anchor.target.attributes.id &&
+        !current.attributes.id &&
+        element !== previous &&
+        score(anchor.target, current) < 55
+      )
+        continue;
+      let points = score(anchor.target, current);
+      const chain = parents(element);
+      let next = 0;
+      let scope = anchor.scope === 0 ? current : null;
+      let group = anchor.group === 0 ? element : null;
+      for (const [index, saved] of anchor.ancestors.entries()) {
+        let best = -1,
+          bestScore = 0;
+        // Skip inserted layout wrappers without requiring an exact CSS path.
+        for (let i = next; i < Math.min(chain.length, next + 3); i++) {
+          const value = score(saved, fingerprint(chain[i]));
+          if (value > bestScore) {
+            best = i;
+            bestScore = value;
+          }
+        }
+        if (best < 0) continue;
+        next = best + 1;
+        points += Math.min(120, bestScore) * (index < 3 ? 0.6 : 0.4);
+        if (anchor.scope === index + 1) scope = fingerprint(chain[best]);
+        if (anchor.group === index + 1) group = chain[best];
+      }
+      // An absent local composition is not permission to borrow a target elsewhere.
+      if (anchor.scope >= 0 && !scope) continue;
+      const originalGroup = [anchor.target, ...anchor.ancestors][anchor.group];
+      // Shared styling cannot identify one record. Distinctive classes, attributes
+      // and textual similarity all contribute to the same confidence score.
+      if (originalGroup && element !== previous) {
+        if (!group) continue;
+        const peers = group.parentElement
+          ? children(group.parentElement).filter(
+              (peer) => peer !== group && peer.localName === group.localName,
+            )
+          : [];
+        const distinctClasses = originalGroup.classes.filter(
+          (name) =>
+            peers.length > 0 &&
+            peers.every((peer) => !peer.classList.contains(name)),
+        );
+        const distinctAttributes = Object.fromEntries(
+          Object.entries(originalGroup.attributes).filter(
+            ([name, value]) =>
+              /^(id|data-testid|data-test|data-cy)$/.test(name) ||
+              (peers.length > 0 &&
+                peers.every(
+                  (peer) => fingerprint(peer).attributes[name] !== value,
+                )),
+          ),
+        );
+        const witness = {
+          ...originalGroup,
+          classes: distinctClasses,
+          attributes: distinctAttributes,
+        };
+        const currentGroup = fingerprint(group);
+        const points =
+          score(witness, currentGroup) +
+          (overlap(distinctClasses, currentGroup.classes) ? 12 : 0);
+        if (points < 55) continue;
+      }
+      const originalScope = [anchor.target, ...anchor.ancestors][anchor.scope];
+      const changed =
+        !!(scope && originalScope && differentState(originalScope, scope)) ||
+        differentState(anchor.target, current);
+      if (anchor.twins > 1 && twins(element, anchor.target) < anchor.twins)
+        continue;
+      // Live identity survives a rewrite, but never bypasses the state comparison.
+      if (element === previous && previous.isConnected) points += 24;
+      if (candidates.length === 1) points += 24;
+      if (element === exact) points += anchor.target.tag === "*" ? 55 : 8;
+      ranked.push({ element, score: points, changed });
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    const best = ranked[0];
+    if (!best)
+      return {
+        element: null,
+        status: anchor.layer
+          ? "hidden"
+          : anchor.twins > 1 && candidates.length
+            ? "uncertain"
+            : "missing",
+      };
+    // Rank before checking state: don't jump to a weaker lookalike when the original changes.
+    if (best.score < 55 || (ranked[1] && best.score - ranked[1].score < 14))
+      return { element: null, status: "uncertain" };
+    return best.changed
+      ? { element: null, status: "hidden" }
+      : { element: best.element, status: "matched" };
+  }
+
+  return { capture, resolve };
+}
+
+export function isResilientAnchor(value: unknown): value is ResilientAnchor {
+  if (!value || typeof value !== "object") return false;
+  const anchor = value as Partial<ResilientAnchor>;
+  const strings = (items: unknown, max: number): items is string[] =>
+    Array.isArray(items) &&
+    items.length <= max &&
+    items.every((item) => typeof item === "string" && item.length <= 160);
+  const fingerprint = (item: unknown): item is Fingerprint => {
+    if (!item || typeof item !== "object") return false;
+    const part = item as Partial<Fingerprint>;
+    return (
+      typeof part.tag === "string" &&
+      /^[a-z][a-z0-9-]{0,79}$/.test(part.tag) &&
+      typeof part.text === "string" &&
+      part.text.length <= 160 &&
+      typeof part.heading === "string" &&
+      part.heading.length <= 160 &&
+      strings(part.classes, 8) &&
+      strings(part.shape, 120) &&
+      !!part.attributes &&
+      typeof part.attributes === "object" &&
+      !Array.isArray(part.attributes) &&
+      Object.entries(part.attributes).length <= 13 &&
+      Object.entries(part.attributes).every(
+        ([key, val]) =>
+          key.length < 40 && typeof val === "string" && val.length <= 160,
+      )
+    );
+  };
+  return (
+    anchor.version === 1 &&
+    fingerprint(anchor.target) &&
+    Array.isArray(anchor.ancestors) &&
+    anchor.ancestors.length <= 8 &&
+    anchor.ancestors.every(fingerprint) &&
+    (anchor.layer === null || fingerprint(anchor.layer)) &&
+    Number.isInteger(anchor.scope) &&
+    typeof anchor.scope === "number" &&
+    anchor.scope >= -1 &&
+    anchor.scope <= anchor.ancestors.length &&
+    Number.isInteger(anchor.group) &&
+    typeof anchor.group === "number" &&
+    anchor.group >= -1 &&
+    anchor.group <= anchor.ancestors.length &&
+    typeof anchor.twins === "number" &&
+    Number.isInteger(anchor.twins) &&
+    anchor.twins >= 1
+  );
+}