@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/packages/public-runtime/src/tracking-id-derivation.ts

@@ -0,0 +1,1008 @@
+/**
+ * `data-tot-el` id derivation — the authoring-time engine that proposes a
+ * stable, human-readable IDENTITY for an element in a tenant-authored body
+ * fragment.
+ *
+ * SCOPE. This module is a pure proposal engine and NOTHING else. It is not
+ * wired into any render path, publish pipeline, or validator, and it is never a
+ * runtime fallback: `validateChromeConfig` still fails an item that declares
+ * neither an `action` nor `tracking: "none"`, and `trackingAttributes()` still
+ * throws on a missing field. Derivation happens at authoring / migration time,
+ * writes an EXPLICIT value into the source, and then has no further say. The
+ * consumers are separate units: one writes proposals back to source as a
+ * reviewable diff, one stamps non-git content at publish time, one raises
+ * validator warnings.
+ *
+ * It derives ONE axis. `data-tot-el` (identity) and `data-tot-action` (intent)
+ * are independent axes, and this engine deliberately contains no path between
+ * them in either direction.
+ *
+ * ---------------------------------------------------------------------------
+ * THE PAYLOAD GUARDRAIL — the constraint that shapes everything below
+ * ---------------------------------------------------------------------------
+ *
+ * An id is derived from STRUCTURE ONLY. This module never reads rendered
+ * content: no character data, no `alt`/`value`/`placeholder`/heading text, no
+ * DOM traversal, no node enumeration. What an element visually SAYS has no
+ * influence on its derived id.
+ *
+ * That is why the input is a plain structural descriptor — a tag name, an
+ * attribute bag, and the chain of open ancestors — rather than a DOM node: a
+ * descriptor that carries no children and no character data cannot leak
+ * content even by accident. The shape is deliberately what a STREAMING rewriter
+ * can supply from an open tag plus the tag stack it already maintains, so the
+ * git-time rewriter and the publish-time streaming rewriter feed the same
+ * engine.
+ *
+ * Two mechanical enforcements, in tests/tracking-id-derivation.test.ts:
+ *   1. a source sweep for every DOM-text and form-value API (the same sweep
+ *      interaction-tracking.ts carries);
+ *   2. a CLOSED ALLOWLIST of readable attributes ({@link READABLE_ATTRIBUTES}
+ *      plus {@link DEFAULT_NAMING_ATTRIBUTES}), asserted to exclude every
+ *      text-bearing attribute — so a fragment whose only difference is its
+ *      visible copy derives byte-identical ids.
+ *
+ * Note the contrast with `content/prose.ts`, which derives heading ANCHORS from
+ * heading text. That is a URL fragment for a human to link to. This is an
+ * analytics identity, bound by the payload guardrail, and the two must not
+ * borrow each other's approach.
+ *
+ * ---------------------------------------------------------------------------
+ * THE THREE PROPERTIES
+ * ---------------------------------------------------------------------------
+ *
+ * HUMAN-READABLE. A hash fails this module's purpose. Every token in a derived
+ * id comes from the author's own vocabulary — their `id`, their `data-section`,
+ * their role class, their link destination — composed the way the hand-authored
+ * governed-chrome ids compose (`nav-pricing`, `ftr-company-pricing`,
+ * `nav-shop-pods`): an outermost-first region path, then the element's role.
+ *
+ * DETERMINISTIC. A pure function of the descriptor. No randomness, no clock, no
+ * hashing, no iteration over unordered maps.
+ *
+ * STABLE UNDER UNRELATED EDITS. An id is built from the element's OWN naming
+ * attributes plus the names of its ancestor regions. Editing, restyling,
+ * reordering or deleting an unrelated element elsewhere in the document touches
+ * neither, so the id does not move. Raw sibling position is the LAST resort,
+ * never a preference — and when it is used the result is reported as
+ * `confidence: "positional"` with `needsReview: true`, because that is exactly
+ * the id a human should look at before it is committed.
+ *
+ * PRESERVED PROPERTY. The same intent at two placements derives two DIFFERENT
+ * ids, because the region path differs (`nav-pricing` in the header nav,
+ * `ftr-pricing` in the footer) — which is the property the governed-chrome
+ * convention depends on, since those two share one `data-tot-action`.
+ *
+ * ---------------------------------------------------------------------------
+ * FEEDING THE ENGINE
+ * ---------------------------------------------------------------------------
+ *
+ * This module owns no parser and imports none — `@tot/public-runtime` is
+ * Node-free and edge-shipped, and a parser choice belongs to the caller. Each
+ * consumer builds {@link DerivationTarget}s from whatever it already has:
+ *
+ * - a git-time rewriter walks `parse5`'s `parseFragment` tree keeping a tag
+ *   stack (the pattern `apps/storefront/src/lib/the-build/toc.ts` already uses
+ *   to add heading anchors and re-`serialize()` byte-preserving when nothing
+ *   changed);
+ * - a publish-time `HTMLRewriter` handler keeps the same stack across
+ *   element/end-tag callbacks and derives at the open tag;
+ * - a validator reads authored JSON and needs no parser at all.
+ *
+ * Iterate in DOCUMENT ORDER and the ordinals from
+ * {@link createTrackingIdDeriver} are identical across all three.
+ *
+ * Contract: docs/architecture/interaction-tracking-attribute-contract.md
+ */
+
+import { TRACKING_ATTR_EL } from "./interaction-tracking.js";
+
+// ---------------------------------------------------------------------------
+// Limits
+// ---------------------------------------------------------------------------
+
+/** Longest derived id. Past this a name stops being something a human reads. */
+export const TRACKING_ID_MAX_LENGTH = 64;
+
+/** Most `-`-joined tokens in a derived id. Region tokens are trimmed first. */
+export const TRACKING_ID_MAX_TOKENS = 6;
+
+/** Longest single token taken from an authored name. */
+const MAX_TOKEN_SOURCE_LENGTH = 40;
+
+// ---------------------------------------------------------------------------
+// The closed attribute allowlist — the guardrail's positive half
+// ---------------------------------------------------------------------------
+
+/**
+ * Non-`data-` attributes this engine may read. A CLOSED list, asserted by test
+ * to contain nothing text-bearing: no `alt`, no `title`, no `value`, no
+ * `placeholder`, no `aria-label`. Each is a declaration of structure — what the
+ * element IS or where it POINTS — never of what it displays.
+ */
+export const READABLE_ATTRIBUTES: readonly string[] = ["id", "class", "href", "name", "type", "role"];
+
+/**
+ * `data-` attributes that carry an author-chosen NAME for a block, section or
+ * interaction. Closed by default rather than an open `data-*` sweep, so a
+ * tenant attribute that happens to hold display copy can never become an id
+ * source. Extend per-call with {@link DerivationOptions.namingAttributes}.
+ */
+export const DEFAULT_NAMING_ATTRIBUTES: readonly string[] = [
+  // An authored interaction name. Already in use in tenant fragments
+  // (`data-ev="request_access_hero"`) and the single best identity seed there
+  // is: the author has already named the interaction AND its placement.
+  "data-ev",
+  "data-event",
+  "data-section",
+  "data-region",
+  "data-block",
+  "data-component",
+  "data-cmp",
+  "data-card",
+  "data-slot",
+  "data-name",
+  "data-key",
+  "data-testid",
+  "data-test-id",
+  "data-qa",
+];
+
+/**
+ * Attributes that hold display copy. Never read, never accepted through
+ * {@link DerivationOptions.namingAttributes}, and asserted absent from both
+ * allowlists by test. Reading any of these would be a payload-guardrail
+ * violation, not a naming shortcut.
+ *
+ * The whole `data-tot-*` namespace is refused too, by prefix rather than by
+ * name — it is the contract's own namespace, so nothing an emitter stamps
+ * there may ever seed an identity.
+ */
+export const TEXT_BEARING_ATTRIBUTES: readonly string[] = [
+  "alt",
+  "aria-description",
+  "aria-label",
+  "aria-placeholder",
+  "aria-roledescription",
+  "aria-valuetext",
+  "content",
+  "download",
+  "label",
+  "placeholder",
+  "srcdoc",
+  "title",
+  "value",
+];
+
+// ---------------------------------------------------------------------------
+// Vocabulary tables
+// ---------------------------------------------------------------------------
+
+/**
+ * Landmark tags that name a region. Abbreviated to match the hand-authored
+ * convention in the migrated configs (`ftr-company-pricing`, not
+ * `footer-company-pricing`, in the tokenoftrust chrome).
+ *
+ * The in-repo configs are not uniform about this — `ftr-` and `footer-`,
+ * `utility-` and `util-` both occur across tenants — so a tenant that settled
+ * on the other spelling overrides the table via
+ * {@link DerivationOptions.landmarkRegions} rather than fighting the default.
+ */
+export const DEFAULT_LANDMARK_REGIONS: Readonly<Record<string, string>> = {
+  header: "header",
+  nav: "nav",
+  footer: "ftr",
+  aside: "aside",
+  form: "form",
+  table: "table",
+  thead: "head",
+  tfoot: "foot",
+  dialog: "dialog",
+  fieldset: "fieldset",
+};
+
+/**
+ * The page-level landmarks. Two special properties:
+ *
+ * 1. They TERMINATE the upward region walk. `header` above `nav` adds nothing —
+ *    the hand-authored convention is `nav-pricing`, not `header-nav-pricing`.
+ * 2. Their CLASS is ignored. A landmark's class is reliably a styling handle
+ *    (`nav-links`, `site-header`, `site-footer`), not a region name, so the
+ *    landmark word wins. An `id` or a naming attribute still beats it — that is
+ *    an author naming the region deliberately.
+ *
+ * `form`, `table` and `fieldset` are deliberately NOT here: they nest, they
+ * carry genuinely-naming classes (`pricing-table`), and the region above them
+ * is what tells two of them apart.
+ */
+const DOCUMENT_LANDMARKS: readonly string[] = ["header", "nav", "footer", "aside", "dialog"];
+
+/**
+ * Tags whose region name, absent a naming attribute, is not worth a token —
+ * every page has them, so they discriminate nothing.
+ */
+const GENERIC_CONTAINER_TAGS: readonly string[] = [
+  "html",
+  "body",
+  "main",
+  "div",
+  "span",
+  "p",
+  "tbody",
+  "tr",
+  "ul",
+  "ol",
+  "dl",
+  "picture",
+];
+
+/**
+ * The role word for an element with no authored name of its own. Generic by
+ * construction, which is why a tag-only role is reported as `positional`.
+ */
+const DEFAULT_TAG_ROLES: Readonly<Record<string, string>> = {
+  a: "link",
+  button: "btn",
+  summary: "toggle",
+  details: "details",
+  input: "field",
+  textarea: "field",
+  select: "select",
+  option: "option",
+  label: "field-label",
+  form: "form",
+  tr: "row",
+  td: "cell",
+  th: "cell",
+  li: "item",
+  dt: "term",
+  dd: "def",
+  img: "image",
+  video: "video",
+  audio: "audio",
+  iframe: "frame",
+  section: "section",
+  article: "article",
+  figure: "figure",
+};
+
+/** Tags an interaction can originate from — the derivation candidates. */
+const TRACKABLE_TAGS: readonly string[] = [
+  "a",
+  "area",
+  "button",
+  "details",
+  "summary",
+  "form",
+  "input",
+  "select",
+  "textarea",
+  "label",
+];
+
+/**
+ * Class names that describe LAYOUT or STATE rather than role. Rejected as id
+ * sources: they recur everywhere, so they name nothing, and state classes move
+ * at runtime. Drawn from the vocabulary actually present in the in-repo tenant
+ * fragments (`wrap`, `center`, `blk`, `panel`, `stage`, `big`, `top`) plus the
+ * usual utility words.
+ */
+const DEFAULT_UTILITY_CLASSES: readonly string[] = [
+  "active",
+  "background",
+  "bg",
+  "big",
+  "blk",
+  "block",
+  "body",
+  "bottom",
+  "box",
+  "center",
+  "centre",
+  "clearfix",
+  "col",
+  "column",
+  "container",
+  "content",
+  "current",
+  "disabled",
+  "even",
+  "first",
+  "flex",
+  "fluid",
+  "full",
+  "grid",
+  "group",
+  "half",
+  "hidden",
+  "holder",
+  "inner",
+  "invisible",
+  "is-active",
+  "is-open",
+  "large",
+  "last",
+  "layout",
+  "left",
+  "lg",
+  "main",
+  "md",
+  "middle",
+  "mini",
+  "narrow",
+  "odd",
+  "off",
+  "on",
+  "open",
+  "outer",
+  "panel",
+  "relative",
+  "right",
+  "row",
+  "screen-reader-text",
+  "section",
+  "selected",
+  "sm",
+  "small",
+  "sr-only",
+  "stack",
+  "stage",
+  "sticky",
+  "text",
+  "top",
+  "visible",
+  "visually-hidden",
+  "wide",
+  "wrap",
+  "wrapper",
+  "xl",
+  "xs",
+];
+
+/**
+ * Suffixes that turn a role class into a layout class. Stripped so an author's
+ * `class="cmp-wrap blk"` yields `cmp` and `class="hero hero-grid"` yields
+ * `hero`, matching how they would have named it by hand.
+ */
+const LAYOUT_CLASS_SUFFIXES: readonly string[] = [
+  "-wrap",
+  "-wrapper",
+  "-container",
+  "-inner",
+  "-outer",
+  "-grid",
+  "-flex",
+  "-row",
+  "-col",
+  "-cols",
+  "-column",
+  "-box",
+  "-left",
+  "-right",
+  "-top",
+  "-bottom",
+  "-center",
+  "-holder",
+];
+
+/** URL schemes that address something other than a page. Never an id source. */
+const NON_PAGE_SCHEMES: readonly string[] = ["mailto:", "tel:", "sms:", "javascript:", "data:", "blob:"];
+
+// ---------------------------------------------------------------------------
+// Input / output shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * One element as this engine sees it: a tag name and an attribute bag. No
+ * children, no character data — structurally incapable of carrying content, and
+ * exactly what a streaming rewriter has at an open tag.
+ */
+export interface StructuralNode {
+  /** Tag name. Case-insensitive; normalized internally. */
+  tag: string;
+  /** Attribute bag. Only allowlisted keys are ever read. */
+  attrs?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/** The element to derive an id for, plus the structure it sits in. */
+export interface DerivationTarget {
+  /** The element itself. */
+  node: StructuralNode;
+  /**
+   * The chain of open ancestors, **OUTERMOST FIRST** — i.e. an open-tag stack
+   * in push order. A streaming rewriter passes its stack as-is.
+   */
+  ancestors?: readonly StructuralNode[] | undefined;
+  /**
+   * The repeat container this element instantiates, when the caller knows it
+   * (the `data-tot-scope` axis). Used as a region token when the ancestors
+   * carry no better name.
+   */
+  scope?: string | undefined;
+  /**
+   * Zero-based instance index within `scope` (the `data-tot-i` axis). When
+   * given, it supplies the ordinal instead of the collision counter — a
+   * caller-known index is the more stable of the two.
+   */
+  index?: number | undefined;
+}
+
+/**
+ * How much author intent the id carries. Descending stability, and the signal
+ * downstream units gate on.
+ */
+export type DerivationConfidence =
+  /** The element already declared `data-tot-el`. Returned verbatim; derive nothing. */
+  | "declared"
+  /** From a name the author chose: `id`, `data-section`, `data-ev`, `name`. */
+  | "authored"
+  /** From structure the author shaped: a link destination, a role class. */
+  | "structural"
+  /** Needed the element's position — a tag-only role, or an ordinal. Review it. */
+  | "positional";
+
+/** One derived id, and everything a reviewer or a validator needs about it. */
+export interface DerivedTrackingId {
+  /** The proposed `data-tot-el` value. Always `[a-z0-9-]`, never empty. */
+  el: string;
+  /** The id before any ordinal was appended. */
+  base: string;
+  confidence: DerivationConfidence;
+  /**
+   * What produced it, most significant first — e.g.
+   * `["attr:data-ev", "region:section#pricing", "ordinal:2"]`. For a review
+   * diff and for a validator message; not machine-contracted beyond being
+   * stable for a given input.
+   */
+  signals: readonly string[];
+  /**
+   * True iff the id leans on position (`confidence: "positional"`). A human
+   * should name this element explicitly instead of accepting the proposal.
+   */
+  needsReview: boolean;
+}
+
+export interface DerivationOptions {
+  /** Extra author-name `data-` attributes, appended to {@link DEFAULT_NAMING_ATTRIBUTES}. */
+  namingAttributes?: readonly string[] | undefined;
+  /** Extra layout/state class names, appended to the built-in stoplist. */
+  utilityClasses?: readonly string[] | undefined;
+  /** Extra or overriding tag→role words. */
+  tagRoles?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Extra or overriding landmark-tag→region names — e.g. `{ footer: "footer" }`
+   * for a tenant whose hand-authored ids spell the footer out in full.
+   */
+  landmarkRegions?: Readonly<Record<string, string>> | undefined;
+  /** Default {@link TRACKING_ID_MAX_LENGTH}. */
+  maxLength?: number | undefined;
+  /** Default {@link TRACKING_ID_MAX_TOKENS}. */
+  maxTokens?: number | undefined;
+  /**
+   * Whether a link's destination PATH may seed the role token. Default true —
+   * it is how the hand-authored ids read (`nav-pricing` for `/pricing`).
+   * Only the last path segment or a same-document `#fragment` is ever used;
+   * query strings, hashes-with-queries, credentials and opaque tokens are
+   * discarded before anything is considered. Set false for a tenant whose URLs
+   * are not stable names.
+   */
+  useHrefPath?: boolean | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Slug plumbing
+// ---------------------------------------------------------------------------
+
+/**
+ * An authored name reduced to id tokens. Underscores, camelCase and separators
+ * all collapse to `-`, so `data-ev="request_access_hero"` and
+ * `data-section="requestAccessHero"` derive the same tokens.
+ */
+function tokenize(raw: string | undefined): string[] {
+  if (typeof raw !== "string") return [];
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed.length > MAX_TOKEN_SOURCE_LENGTH) return [];
+  return trimmed
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length > 0);
+}
+
+/** Join tokens into an id, dropping duplicates and trimming region tokens first. */
+function assemble(regionTokens: readonly string[], roleTokens: readonly string[], maxTokens: number, maxLength: number): string {
+  // Dedupe globally, keeping first occurrence: an author who already wrote the
+  // region into the element's own name ("request_access_hero" inside the hero)
+  // must not get it twice.
+  const seen = new Set<string>();
+  const region: string[] = [];
+  for (const t of regionTokens) {
+    if (!seen.has(t)) {
+      seen.add(t);
+      region.push(t);
+    }
+  }
+  const role: string[] = [];
+  for (const t of roleTokens) {
+    if (!seen.has(t)) {
+      seen.add(t);
+      role.push(t);
+    }
+  }
+  // Over budget: the role is the specific half, so trim region tokens from the
+  // OUTSIDE in. Never trim the role.
+  let tokens = [...region, ...role];
+  while (tokens.length > maxTokens && region.length > 0) {
+    region.shift();
+    tokens = [...region, ...role];
+  }
+  let id = tokens.join("-");
+  while (id.length > maxLength && region.length > 0) {
+    region.shift();
+    id = [...region, ...role].join("-");
+  }
+  if (id.length > maxLength) {
+    // Role alone is still too long: drop whole trailing role tokens rather
+    // than cutting a word in half, which would read as a typo.
+    const kept = [...role];
+    while (kept.length > 1 && kept.join("-").length > maxLength) kept.pop();
+    id = kept.join("-").slice(0, maxLength);
+  }
+  return id.replace(/^-+|-+$/g, "");
+}
+
+// ---------------------------------------------------------------------------
+// Attribute reads — every one goes through here
+// ---------------------------------------------------------------------------
+
+/**
+ * The ONLY attribute read in this module. Refuses anything outside the closed
+ * allowlist, so a new call site cannot widen the guardrail by accident.
+ */
+function readAttr(node: StructuralNode, name: string, naming: readonly string[]): string | undefined {
+  if (!READABLE_ATTRIBUTES.includes(name) && !naming.includes(name) && name !== TRACKING_ATTR_EL) {
+    return undefined;
+  }
+  const bag = node.attrs;
+  if (!bag) return undefined;
+  const raw = bag[name];
+  return typeof raw === "string" ? raw : undefined;
+}
+
+function tagOf(node: StructuralNode): string {
+  return typeof node.tag === "string" ? node.tag.trim().toLowerCase() : "";
+}
+
+// ---------------------------------------------------------------------------
+// Class-name filtering
+// ---------------------------------------------------------------------------
+
+const TAILWINDISH =
+  /^-?[a-z]{1,5}-(?:\d+(?:\.\d+)?|px|full|auto|screen|min|max|fit|none|dvh|svh|xs|sm|md|lg|xl|\d?xl)$/;
+
+function isUtilityClass(cls: string, stoplist: readonly string[]): boolean {
+  if (cls.length < 3 || cls.length > 32) return true;
+  // Variant / arbitrary-value / opacity syntax — never a role name.
+  if (/[:[\]/()!]/.test(cls)) return true;
+  if (stoplist.includes(cls)) return true;
+  if (TAILWINDISH.test(cls)) return true;
+  // Generated / hashed module class (`css-1x2y3z`, `_hero_1a2b3c`): a segment
+  // that leads with a digit, or interleaves digits and letters, is a build
+  // artifact and not a name a human wrote.
+  if (cls.startsWith("_")) return true;
+  for (const segment of cls.split(/[-_]/)) {
+    if (/^\d/.test(segment) || /\d[a-z]/.test(segment)) return true;
+  }
+  return false;
+}
+
+/**
+ * The role-bearing class on an element, or undefined. Authors write role-first
+ * (`class="btn btn-grad"`, `class="cmp-wrap blk"`), so the first surviving
+ * class wins; a layout suffix is then stripped off it.
+ */
+function roleClass(node: StructuralNode, naming: readonly string[], stoplist: readonly string[]): string | undefined {
+  const raw = readAttr(node, "class", naming);
+  if (!raw) return undefined;
+  for (const cls of raw.trim().toLowerCase().split(/\s+/)) {
+    if (!cls || isUtilityClass(cls, stoplist)) continue;
+    let name = cls;
+    for (const suffix of LAYOUT_CLASS_SUFFIXES) {
+      if (name.length > suffix.length && name.endsWith(suffix)) {
+        name = name.slice(0, -suffix.length);
+        break;
+      }
+    }
+    if (isUtilityClass(name, stoplist)) continue;
+    return name;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Link destinations
+// ---------------------------------------------------------------------------
+
+/**
+ * The stable name inside a link destination, or undefined.
+ *
+ * Query strings, fragments-after-a-path, credentials and hosts are discarded
+ * FIRST and never considered, so a URL that carries session state, a token or a
+ * redirect target contributes nothing. What survives is a single path segment
+ * or a same-document `#fragment`, and only when it reads like a name a human
+ * chose: no all-digit ids, no hex blobs, no template placeholders.
+ */
+function hrefToken(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  const href = raw.trim();
+  if (!href) return undefined;
+  const lower = href.toLowerCase();
+  for (const scheme of NON_PAGE_SCHEMES) {
+    if (lower.startsWith(scheme)) return undefined;
+  }
+  let candidate: string;
+  if (href.startsWith("#")) {
+    // Same-document target: pure structure, the author named an anchor.
+    candidate = href.slice(1).split(/[?&]/)[0] ?? "";
+  } else {
+    // Everything from the first `?` or `#` onward is state, not structure.
+    let path = href.split(/[?#]/)[0] ?? "";
+    // A scheme and authority name a HOST, never an element. Drop both before
+    // anything is considered, so credentials and hostnames cannot leak in.
+    path = path.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, "").replace(/^\/\/[^/]*/, "");
+    const segments = path.split("/").filter((s) => s.length > 0);
+    candidate = segments[segments.length - 1] ?? "";
+  }
+  candidate = candidate.replace(/\.(?:html?|php|aspx?|jsp)$/i, "");
+  if (!candidate || candidate.length > MAX_TOKEN_SOURCE_LENGTH) return undefined;
+  if (!/^[A-Za-z][A-Za-z0-9._-]*$/.test(candidate)) return undefined;
+  // An opaque id, not a name: a hex blob or a uuid-shaped token.
+  if (/^[0-9a-f-]{16,}$/i.test(candidate)) return undefined;
+  const tokens = tokenize(candidate);
+  if (tokens.length === 0) return undefined;
+  if (tokens.every((t) => /^\d+$/.test(t))) return undefined;
+  return tokens.join("-");
+}
+
+// ---------------------------------------------------------------------------
+// Region path
+// ---------------------------------------------------------------------------
+
+interface RegionToken {
+  tokens: string[];
+  signal: string;
+  /** True for a page-level landmark: nothing above it adds information. */
+  terminal: boolean;
+}
+
+/** The region name one ancestor contributes, or undefined if it names nothing. */
+function regionOf(
+  node: StructuralNode,
+  naming: readonly string[],
+  stoplist: readonly string[],
+  landmarks: Readonly<Record<string, string>>,
+): RegionToken | undefined {
+  const tag = tagOf(node);
+  const terminal = DOCUMENT_LANDMARKS.includes(tag);
+  // An author-chosen block name beats the tag every time.
+  for (const attr of naming) {
+    const tokens = tokenize(readAttr(node, attr, naming));
+    if (tokens.length > 0) return { tokens, signal: `region:${tag}[${attr}]`, terminal };
+  }
+  const own = tokenize(readAttr(node, "id", naming));
+  if (own.length > 0) return { tokens: own, signal: `region:${tag}#${own.join("-")}`, terminal };
+  const landmark = landmarks[tag];
+  // A landmark's class is a styling handle, not a region name — skip it.
+  if (landmark && terminal) return { tokens: [landmark], signal: `region:<${tag}>`, terminal };
+  const cls = roleClass(node, naming, stoplist);
+  if (cls) return { tokens: tokenize(cls), signal: `region:${tag}.${cls}`, terminal };
+  if (landmark) return { tokens: [landmark], signal: `region:<${tag}>`, terminal };
+  if (GENERIC_CONTAINER_TAGS.includes(tag)) return undefined;
+  const role = readAttr(node, "role", naming);
+  const roleTokens = tokenize(role);
+  if (roleTokens.length > 0) return { tokens: roleTokens, signal: `region:${tag}[role]`, terminal };
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// The element's own role token
+// ---------------------------------------------------------------------------
+
+interface RoleToken {
+  tokens: string[];
+  confidence: Exclude<DerivationConfidence, "declared">;
+  signal: string;
+}
+
+function roleOf(
+  node: StructuralNode,
+  naming: readonly string[],
+  stoplist: readonly string[],
+  tagRoles: Readonly<Record<string, string>>,
+  useHrefPath: boolean,
+): RoleToken {
+  const tag = tagOf(node);
+
+  // 1. An author-chosen interaction / block name. The strongest signal there
+  //    is, and the one that already encodes placement in real fragments
+  //    (`data-ev="request_access_hero"` vs `..._header"`).
+  for (const attr of naming) {
+    const tokens = tokenize(readAttr(node, attr, naming));
+    if (tokens.length > 0) return { tokens, confidence: "authored", signal: `attr:${attr}` };
+  }
+
+  // 2. An authored element id.
+  const own = tokenize(readAttr(node, "id", naming));
+  if (own.length > 0) return { tokens: own, confidence: "authored", signal: "attr:id" };
+
+  // 3. A form control's submitted name — authored, and the field's real identity.
+  const name = tokenize(readAttr(node, "name", naming));
+  if (name.length > 0) return { tokens: name, confidence: "authored", signal: "attr:name" };
+
+  // 4. Where the link goes. Structure the author shaped, and how the
+  //    hand-authored chrome ids read.
+  if (useHrefPath) {
+    const dest = hrefToken(readAttr(node, "href", naming));
+    if (dest) return { tokens: tokenize(dest), confidence: "structural", signal: "attr:href" };
+  }
+
+  // 5. A role-bearing class.
+  const cls = roleClass(node, naming, stoplist);
+  if (cls) return { tokens: tokenize(cls), confidence: "structural", signal: `attr:class(${cls})` };
+
+  // 6. A submit/reset button's kind, or an explicit ARIA role. Structural, and
+  //    more specific than the bare tag.
+  const type = tokenize(readAttr(node, "type", naming));
+  if ((tag === "button" || tag === "input") && type.length > 0 && type[0] !== "text") {
+    return { tokens: type, confidence: "structural", signal: "attr:type" };
+  }
+  const role = tokenize(readAttr(node, "role", naming));
+  if (role.length > 0) return { tokens: role, confidence: "structural", signal: "attr:role" };
+
+  // 7. Nothing authored anywhere. The tag's generic role word — which
+  //    discriminates only by position, hence `positional`.
+  const word = tagRoles[tag] ?? (tag ? tokenize(tag).join("-") : "el");
+  return { tokens: tokenize(word), confidence: "positional", signal: `tag:<${tag || "unknown"}>` };
+}
+
+// ---------------------------------------------------------------------------
+// The single-element engine
+// ---------------------------------------------------------------------------
+
+function resolveOptions(options: DerivationOptions | undefined): {
+  naming: readonly string[];
+  stoplist: readonly string[];
+  tagRoles: Readonly<Record<string, string>>;
+  landmarks: Readonly<Record<string, string>>;
+  maxLength: number;
+  maxTokens: number;
+  useHrefPath: boolean;
+} {
+  const extraNaming = (options?.namingAttributes ?? []).filter(
+    // A caller cannot widen the guardrail: only `data-` names are accepted at
+    // all, a text-bearing attribute is refused even when explicitly asked for,
+    // and the contract's own `data-tot-*` namespace is refused by prefix.
+    (a) =>
+      typeof a === "string" &&
+      a.startsWith("data-") &&
+      !a.startsWith("data-tot-") &&
+      !TEXT_BEARING_ATTRIBUTES.includes(a),
+  );
+  return {
+    naming: [...DEFAULT_NAMING_ATTRIBUTES, ...extraNaming],
+    stoplist: [...DEFAULT_UTILITY_CLASSES, ...(options?.utilityClasses ?? [])],
+    tagRoles: { ...DEFAULT_TAG_ROLES, ...(options?.tagRoles ?? {}) },
+    landmarks: { ...DEFAULT_LANDMARK_REGIONS, ...(options?.landmarkRegions ?? {}) },
+    maxLength:
+      typeof options?.maxLength === "number" && options.maxLength > 0
+        ? Math.floor(options.maxLength)
+        : TRACKING_ID_MAX_LENGTH,
+    maxTokens:
+      typeof options?.maxTokens === "number" && options.maxTokens > 0
+        ? Math.floor(options.maxTokens)
+        : TRACKING_ID_MAX_TOKENS,
+    useHrefPath: options?.useHrefPath !== false,
+  };
+}
+
+/**
+ * Derive the BASE id for one element — no ordinal, no collision handling.
+ *
+ * Pure and self-contained: the same {@link DerivationTarget} always yields the
+ * same result, independent of anything else in the document. Use
+ * {@link createTrackingIdDeriver} or {@link deriveTrackingIds} when ids must be
+ * unique across a fragment; this function is the right one when re-deriving a
+ * single element to check it has not drifted.
+ *
+ * An element already carrying `data-tot-el` is returned verbatim with
+ * `confidence: "declared"` — a declared identity is permanent and this engine
+ * never proposes a replacement.
+ */
+export function deriveTrackingId(target: DerivationTarget, options?: DerivationOptions): DerivedTrackingId {
+  const opts = resolveOptions(options);
+  const node = target.node;
+
+  const declared = readAttr(node, TRACKING_ATTR_EL, opts.naming);
+  if (typeof declared === "string" && declared.trim().length > 0) {
+    const el = declared.trim();
+    return { el, base: el, confidence: "declared", signals: [`declared:${TRACKING_ATTR_EL}`], needsReview: false };
+  }
+
+  const role = roleOf(node, opts.naming, opts.stoplist, opts.tagRoles, opts.useHrefPath);
+
+  // Region path, NEAREST first while we pick, emitted outermost-first.
+  const ancestors = target.ancestors ?? [];
+  const nearestFirst: RegionToken[] = [];
+  for (let i = ancestors.length - 1; i >= 0; i -= 1) {
+    const a = ancestors[i];
+    if (!a) continue;
+    const region = regionOf(a, opts.naming, opts.stoplist, opts.landmarks);
+    if (region) {
+      nearestFirst.push(region);
+      // A page-level landmark ends the walk: `header` above `nav` would only
+      // lengthen the id without telling two elements apart.
+      if (region.terminal) break;
+    }
+  }
+  if (nearestFirst.length === 0 && target.scope) {
+    const tokens = tokenize(target.scope);
+    if (tokens.length > 0) nearestFirst.push({ tokens, signal: "scope", terminal: false });
+  }
+
+  // Adaptive budget. A role name the author already PLACED — `request_access_hero`
+  // inside the hero, `nav_why` inside the nav — needs no region at all; re-adding
+  // it is the noise that makes derived ids read like machine output. Otherwise a
+  // name-shaped role takes one region token for placement (`nav` + `pricing`) and
+  // a generic one takes two to say anything (`pricing` + `table` + `row`).
+  const placedTokens = new Set(nearestFirst.flatMap((r) => r.tokens));
+  const alreadyPlaced = role.tokens.some((t) => placedTokens.has(t));
+  const budget = alreadyPlaced ? 0 : role.tokens.length >= 2 ? 1 : 2;
+  const picked = nearestFirst.slice(0, budget);
+  const regionTokens = [...picked].reverse().flatMap((r) => r.tokens);
+
+  const base = assemble(regionTokens, role.tokens, opts.maxTokens, opts.maxLength);
+  const signals = [role.signal, ...[...picked].reverse().map((r) => r.signal)];
+
+  // Degenerate input (empty tag, no attributes at all): still return something
+  // valid and obviously-review-worthy rather than an empty attribute value.
+  const el = base || "el";
+  return {
+    el,
+    base: el,
+    confidence: base ? role.confidence : "positional",
+    signals: base ? signals : [...signals, "fallback:empty"],
+    needsReview: (base ? role.confidence : "positional") === "positional",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fragment-wide uniqueness
+// ---------------------------------------------------------------------------
+
+/** A stateful deriver that keeps ids unique across one fragment. */
+export interface TrackingIdDeriver {
+  /**
+   * Derive an id, appending the smallest ordinal needed to keep it unique
+   * within this deriver. Call in DOCUMENT ORDER — that is what makes the
+   * ordinals deterministic, and it is the order both a git-time rewriter and a
+   * streaming rewriter already have.
+   */
+  derive(target: DerivationTarget): DerivedTrackingId;
+  /**
+   * Claim an id without deriving one — for ids already present in the source,
+   * so a proposal never collides with a declared identity. Seed these BEFORE
+   * deriving.
+   */
+  reserve(el: string): void;
+  /** Every id this deriver has issued or reserved, in claim order. */
+  claimed(): readonly string[];
+}
+
+/**
+ * A deriver scoped to one fragment.
+ *
+ * Ordinals are counted PER BASE ID, not per document, so adding an element that
+ * derives a different base leaves every other id untouched. Only an element
+ * inserted ahead of a same-base sibling renumbers anything — which is why any
+ * id that took an ordinal comes back `needsReview: true`.
+ */
+export function createTrackingIdDeriver(options?: DerivationOptions): TrackingIdDeriver {
+  const counts = new Map<string, number>();
+  const claimedIds: string[] = [];
+  const taken = new Set<string>();
+
+  const claim = (el: string): void => {
+    if (!taken.has(el)) {
+      taken.add(el);
+      claimedIds.push(el);
+    }
+  };
+
+  return {
+    reserve(el: string): void {
+      if (typeof el === "string" && el.trim()) claim(el.trim());
+    },
+    claimed(): readonly string[] {
+      return claimedIds;
+    },
+    derive(target: DerivationTarget): DerivedTrackingId {
+      const derived = deriveTrackingId(target, options);
+      if (derived.confidence === "declared") {
+        claim(derived.el);
+        return derived;
+      }
+      const base = derived.base;
+      // A caller-known repeat index is the more stable ordinal — prefer it.
+      const explicit =
+        typeof target.index === "number" && Number.isInteger(target.index) && target.index > 0
+          ? target.index + 1
+          : undefined;
+      let ordinal = explicit ?? (counts.get(base) ?? 0) + 1;
+      let el = ordinal === 1 ? base : `${base}-${ordinal}`;
+      while (taken.has(el)) {
+        ordinal += 1;
+        el = `${base}-${ordinal}`;
+      }
+      counts.set(base, Math.max(counts.get(base) ?? 0, ordinal));
+      claim(el);
+      const ordinaled = el !== base;
+      return {
+        el,
+        base,
+        confidence: ordinaled ? "positional" : derived.confidence,
+        signals: ordinaled ? [...derived.signals, `ordinal:${ordinal}`] : derived.signals,
+        needsReview: ordinaled || derived.needsReview,
+      };
+    },
+  };
+}
+
+/**
+ * Derive unique ids for a whole fragment in one call — {@link
+ * createTrackingIdDeriver} over an array already in document order. `reserved`
+ * seeds ids that exist in the source and must not be re-proposed.
+ */
+export function deriveTrackingIds(
+  targets: readonly DerivationTarget[],
+  options?: DerivationOptions & { reserved?: readonly string[] | undefined },
+): DerivedTrackingId[] {
+  const deriver = createTrackingIdDeriver(options);
+  for (const el of options?.reserved ?? []) deriver.reserve(el);
+  return targets.map((t) => deriver.derive(t));
+}
+
+// ---------------------------------------------------------------------------
+// Candidate selection — shared by every consumer
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an element is one an interaction can originate from, and therefore a
+ * derivation candidate. Structural test only: the tag, an interactive ARIA
+ * role, or an `href`. An `<a>` with no `href` is not actionable and is skipped.
+ */
+export function isTrackableNode(node: StructuralNode): boolean {
+  const tag = tagOf(node);
+  if (tag === "a" || tag === "area") {
+    const href = node.attrs?.["href"];
+    return typeof href === "string" && href.trim().length > 0;
+  }
+  if (TRACKABLE_TAGS.includes(tag)) return true;
+  const role = node.attrs?.["role"];
+  if (typeof role !== "string") return false;
+  const r = role.trim().toLowerCase();
+  return r === "button" || r === "link" || r === "tab" || r === "menuitem" || r === "switch" || r === "checkbox";
+}
+
+/**
+ * Whether `el` is shaped like a derived / hand-authored identity: lowercase
+ * kebab tokens, within the length budget. The validator unit's cheap check on
+ * an authored value, and a post-condition on everything this module returns.
+ */
+export function isWellFormedTrackingId(el: string, maxLength: number = TRACKING_ID_MAX_LENGTH): boolean {
+  return (
+    typeof el === "string" &&
+    el.length > 0 &&
+    el.length <= maxLength &&
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(el)
+  );
+}