@amplitude/element-selector 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +22 -0
  2. package/lib/cjs/config/resolve-config.d.ts +21 -3
  3. package/lib/cjs/config/resolve-config.d.ts.map +1 -1
  4. package/lib/cjs/config/resolve-config.js +47 -2
  5. package/lib/cjs/config/resolve-config.js.map +1 -1
  6. package/lib/cjs/engine.d.ts.map +1 -1
  7. package/lib/cjs/engine.js +61 -27
  8. package/lib/cjs/engine.js.map +1 -1
  9. package/lib/cjs/fallback-css-path.d.ts +6 -1
  10. package/lib/cjs/fallback-css-path.d.ts.map +1 -1
  11. package/lib/cjs/fallback-css-path.js +38 -37
  12. package/lib/cjs/fallback-css-path.js.map +1 -1
  13. package/lib/cjs/helpers/shadow.d.ts +196 -0
  14. package/lib/cjs/helpers/shadow.d.ts.map +1 -0
  15. package/lib/cjs/helpers/shadow.js +415 -0
  16. package/lib/cjs/helpers/shadow.js.map +1 -0
  17. package/lib/cjs/index.d.ts +4 -2
  18. package/lib/cjs/index.d.ts.map +1 -1
  19. package/lib/cjs/index.js +19 -1
  20. package/lib/cjs/index.js.map +1 -1
  21. package/lib/cjs/orchestrator.d.ts.map +1 -1
  22. package/lib/cjs/orchestrator.js +4 -2
  23. package/lib/cjs/orchestrator.js.map +1 -1
  24. package/lib/cjs/types.d.ts +36 -1
  25. package/lib/cjs/types.d.ts.map +1 -1
  26. package/lib/cjs/types.js.map +1 -1
  27. package/lib/esm/config/resolve-config.d.ts +21 -3
  28. package/lib/esm/config/resolve-config.d.ts.map +1 -1
  29. package/lib/esm/config/resolve-config.js +46 -2
  30. package/lib/esm/config/resolve-config.js.map +1 -1
  31. package/lib/esm/engine.d.ts.map +1 -1
  32. package/lib/esm/engine.js +61 -27
  33. package/lib/esm/engine.js.map +1 -1
  34. package/lib/esm/fallback-css-path.d.ts +6 -1
  35. package/lib/esm/fallback-css-path.d.ts.map +1 -1
  36. package/lib/esm/fallback-css-path.js +37 -36
  37. package/lib/esm/fallback-css-path.js.map +1 -1
  38. package/lib/esm/helpers/shadow.d.ts +196 -0
  39. package/lib/esm/helpers/shadow.d.ts.map +1 -0
  40. package/lib/esm/helpers/shadow.js +402 -0
  41. package/lib/esm/helpers/shadow.js.map +1 -0
  42. package/lib/esm/index.d.ts +4 -2
  43. package/lib/esm/index.d.ts.map +1 -1
  44. package/lib/esm/index.js +9 -1
  45. package/lib/esm/index.js.map +1 -1
  46. package/lib/esm/orchestrator.d.ts.map +1 -1
  47. package/lib/esm/orchestrator.js +4 -2
  48. package/lib/esm/orchestrator.js.map +1 -1
  49. package/lib/esm/types.d.ts +36 -1
  50. package/lib/esm/types.d.ts.map +1 -1
  51. package/lib/esm/types.js.map +1 -1
  52. package/package.json +1 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shadow.js","sourceRoot":"","sources":["../../../src/helpers/shadow.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shadow-DOM traversal + re-resolution helpers.\n *\n * CSS selectors cannot pierce shadow boundaries: `document.querySelector` never\n * matches an element that lives inside a shadow root. So a selector that needs\n * to reach into shadow DOM can't be a single flat string — it has to be a\n * sequence of per-tree selectors, one per shadow tree, each resolvable within\n * its own root. We join those segments with `SHADOW_BOUNDARY_DELIMITER` and\n * re-resolve them with `resolveSelector`, descending one `shadowRoot` per\n * boundary.\n *\n * This module owns the primitives that knowledge lives in:\n *\n * - `composedParent` / `rootOf` — walk *out* of a shadow tree (the light-DOM\n * `parentElement` chain dead-ends at a shadow root; `getRootNode().host`\n * crosses the boundary).\n * - `segmentWalk` — split the outward walk into per-tree segments, honoring\n * the configured max shadow depth.\n * - `resolveSelector` — the symmetric inverse of the engine's output: split\n * on the delimiter and pierce open shadow roots to re-find the element.\n * - `walkComposedAncestors` — yield ancestors up the composed tree, honoring a\n * shadow-boundary crossing budget (shared by capture and selector layers).\n * - `collectOpenShadowRoots` — DFS collection of open shadow roots for\n * observer fan-out and deep `querySelectorAll`.\n * - `positionalStep` — a shadow-aware `tag:nth-of-type(n)` builder shared by\n * the orchestrator's descent and the fallback walker, so a shadow-root-top\n * element is still disambiguated against its `ShadowRoot` siblings.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\n/**\n * Delimiter that separates per-shadow-tree segments in a generated selector.\n *\n * Chosen to be visually distinct and trivially splittable, and to be invalid as\n * a real CSS combinator so it can never be confused with a `>` child combinator\n * the engine emits inside a single tree. Example output:\n *\n * `div#host >>> button:nth-of-type(1)`\n *\n * which `resolveSelector` re-resolves as\n * `document.querySelector('div#host').shadowRoot.querySelector('button:nth-of-type(1)')`.\n */\nexport const SHADOW_BOUNDARY_DELIMITER = ' >>> ';\n\n/**\n * Marker prefix for a \"direct child from the root\" chain inside a shadow tree.\n *\n * A positional chain scoped to a `ShadowRoot` (e.g. `div:nth-of-type(2)`) is not\n * anchored: `querySelector` matches it tree-wide, and `:scope` matches nothing\n * on a `ShadowRoot` (it isn't an element), so there is no CSS way to express\n * \"direct child of the root.\" The generator therefore prefixes such chains with\n * this marker and `resolveSelector` resolves them by strict direct-child descent\n * instead of `querySelector`. Keying off this explicit marker — rather than\n * sniffing a segment for the absence of `#`/`[` — keeps the round-trip correct\n * no matter what the steps contain (tag, `:nth-of-type`, classes, …).\n *\n * `:scope > ` is deliberately valid CSS syntax so a generated selector stays a\n * syntactically legal string; its meaning here is purely the descent signal.\n */\nexport const SHADOW_CHILD_CHAIN_PREFIX = ':scope > ';\n\n/** Narrowing guard that tolerates environments without a `ShadowRoot` global. */\nexport function isShadowRoot(node: Node): node is ShadowRoot {\n return typeof ShadowRoot !== 'undefined' && node instanceof ShadowRoot;\n}\n\n/**\n * Anchor a per-tree segment so it re-resolves within a `ShadowRoot`.\n *\n * Both selector algorithms (the strategy-chain fallback and the legacy Chromium\n * `cssPath`) can emit a segment that is only *positionally* specified — a chain\n * of `tag:nth-*` / class steps with no id or attribute to pin it. In the light\n * DOM the chain is implicitly anchored by the unique `<html>` root; inside a\n * shadow root there is no such root element, so `querySelector` matches the\n * chain tree-wide and can resolve to the wrong element (or none).\n *\n * When `segment` is such a root-anchored positional chain inside a shadow root,\n * we prefix it with {@link SHADOW_CHILD_CHAIN_PREFIX} so `resolveSelector`\n * descends by strict direct-child matching instead of `querySelector`. An\n * id/attribute-anchored segment is already resolvable tree-wide and is returned\n * untouched. `isRootAnchored` is the caller's decision (each generator knows\n * whether its own output reached the tree top vs. short-circuited on an id), so\n * this stays correct regardless of what the steps contain.\n */\nexport function anchorSegmentToShadowScope(segment: string, scope: ParentNode, isRootAnchored: boolean): string {\n if (segment && isRootAnchored && isShadowRoot(scope as Node)) {\n return `${SHADOW_CHILD_CHAIN_PREFIX}${segment}`;\n }\n return segment;\n}\n\n/**\n * Whether the legacy `cssPath` output for `el` is a root-anchored positional\n * chain rather than one anchored by an id.\n *\n * `legacyCssPath` short-circuits at the first element — inclusive of `el` —\n * that carries an `id`, emitting `tag#id > …` from there. If some element in\n * `el`'s ancestor chain has an id the emitted selector is id-anchored (a plain,\n * tree-wide-resolvable `querySelector`); if none does, the chain spans the tree\n * top down to `el` via positional steps and must be marked for direct-child\n * descent inside a shadow root. This walks the same `parentElement` chain the\n * legacy walker does, so the two stay in lockstep.\n */\nexport function legacyPathIsRootAnchored(el: Element): boolean {\n for (let node: Element | null = el; node !== null; node = node.parentElement) {\n if (node.getAttribute('id')) {\n return false;\n }\n }\n return true;\n}\n\n/**\n * The queryable root for `el`'s own tree: the enclosing `ShadowRoot` when `el`\n * lives inside shadow DOM, otherwise the owner document. Both support\n * `querySelectorAll`, so uniqueness checks can be scoped to the correct tree.\n *\n * Preserves the legacy default for non-shadow elements (`ownerDocument`), so\n * nothing changes for the common flat-document case.\n */\nexport function rootOf(el: Element): ParentNode {\n const root = el.getRootNode();\n if (isShadowRoot(root)) {\n return root;\n }\n return el.ownerDocument ?? document;\n}\n\n/**\n * The next element up, crossing shadow boundaries: `parentElement` within a\n * tree, or the shadow host when `el` is at the top of a shadow tree. Returns\n * `null` only at the document root (or a detached non-shadow root).\n */\nexport function composedParent(el: Element): Element | null {\n if (el.parentElement) {\n return el.parentElement;\n }\n const root = el.getRootNode();\n if (isShadowRoot(root)) {\n return root.host;\n }\n return null;\n}\n\n/** One tree's contribution to a piercing selector. */\nexport interface TreeSegment {\n /** Queryable root for this tree — a `Document` or `ShadowRoot`. */\n root: ParentNode;\n /** Element to locate within `root`: the host of the next inner tree, or the original target. */\n target: Element;\n}\n\nexport interface SegmentWalkResult {\n /** Tree segments, outermost (document) first — the order they're joined for output. */\n segments: TreeSegment[];\n /**\n * True when the target sat deeper than `maxShadowDepth` allowed, so inner\n * trees were dropped and the innermost emitted segment targets the shadow\n * host at the depth limit rather than the original target.\n */\n truncated: boolean;\n}\n\n/**\n * Defensive bound on composed-ancestor walks (host-chain iteration in\n * `walkComposedAncestors` and `segmentWalk`). Far above any real shadow nesting\n * (the resolver caps effective depth at `MAX_SHADOW_DOM_DEPTH`). See also\n * {@link MAX_SHADOW_DOM_TRAVERSAL_NODES} for the DFS collection cap.\n */\nexport const MAX_SHADOW_COMPOSED_WALK_ITERATIONS = 1024;\n\n/**\n * Defensive bound on node visits when collecting open shadow roots via DFS.\n * Caps synchronous work inside MutationObserver callbacks on pathologically\n * large trees. See also {@link MAX_SHADOW_COMPOSED_WALK_ITERATIONS} for the\n * ancestor-walk cap.\n */\nexport const MAX_SHADOW_DOM_TRAVERSAL_NODES = 50000;\n\nexport interface OpenShadowRootEntry {\n root: ShadowRoot;\n /** 1-based shadow-boundary depth relative to the collection `root`. */\n depth: number;\n}\n\n/**\n * Yield `start` and each ancestor up the composed tree. Within a tree the walk\n * follows `parentElement`; at the top of a shadow tree it crosses to the host\n * when `crossings < maxShadowDepth`. Yields every element including detached\n * nodes at the top of their tree (where `parentElement` is null).\n */\nexport function* walkComposedAncestors(start: Element, maxShadowDepth: number): Generator<Element> {\n let node: Element | null = start;\n let crossings = 0;\n let iterations = 0;\n\n while (node !== null && iterations < MAX_SHADOW_COMPOSED_WALK_ITERATIONS) {\n iterations += 1;\n yield node;\n\n if (node.parentElement) {\n node = node.parentElement;\n continue;\n }\n if (crossings < maxShadowDepth && typeof node.getRootNode === 'function') {\n const host = composedParent(node);\n if (host && host !== node) {\n crossings += 1;\n node = host;\n continue;\n }\n }\n break;\n }\n}\n\n/**\n * Collect the OPEN shadow roots within `root`'s composed subtree (its own light\n * children and any nested shadow trees), each paired with how many shadow\n * boundary crossings deep it sits relative to `root` (1-based). Bounded by\n * `maxShadowDepth` crossings and by {@link MAX_SHADOW_DOM_TRAVERSAL_NODES}\n * total nodes. Closed roots are invisible (`el.shadowRoot` is null) and skipped.\n */\nexport function collectOpenShadowRoots(root: Element, maxShadowDepth: number): OpenShadowRootEntry[] {\n const found: OpenShadowRootEntry[] = [];\n if (maxShadowDepth <= 0) {\n return found;\n }\n const stack: Array<[Element, number]> = [[root, 0]];\n let visited = 0;\n while (stack.length && visited < MAX_SHADOW_DOM_TRAVERSAL_NODES) {\n visited += 1;\n const [el, depth] = stack.pop() as [Element, number];\n const shadowRoot = el.shadowRoot;\n if (shadowRoot && depth + 1 <= maxShadowDepth) {\n found.push({ root: shadowRoot, depth: depth + 1 });\n const shadowChildren = shadowRoot.children;\n for (let i = 0; i < shadowChildren.length; i++) {\n stack.push([shadowChildren[i], depth + 1]);\n }\n }\n const children = el.children;\n for (let i = 0; i < children.length; i++) {\n stack.push([children[i], depth]);\n }\n }\n return found;\n}\n\n/**\n * Split the outward composed walk from `el` into per-tree segments.\n *\n * Always walks fully out to the document so the outermost segment is\n * document-rooted and therefore re-resolvable. `maxShadowDepth` caps how many\n * shadow boundaries the *emitted* selector descends through: when the target is\n * nested deeper than the budget, the innermost (over-budget) trees are dropped\n * and the result is flagged `truncated` — the innermost kept segment then\n * targets the shadow host at the depth limit (a best-effort, still-resolvable\n * selector for an ancestor of the true target).\n */\nexport function segmentWalk(el: Element, maxShadowDepth: number): SegmentWalkResult {\n // Build innermost-first: one segment per tree, each `target` being the\n // element to locate within that tree (the inner tree's host, or `el`).\n const innermostFirst: TreeSegment[] = [];\n let node: Element | null = el;\n let iterations = 0;\n\n while (node !== null && iterations < MAX_SHADOW_COMPOSED_WALK_ITERATIONS) {\n iterations += 1;\n const root = rootOf(node);\n innermostFirst.push({ root, target: node });\n const actualRoot = node.getRootNode();\n if (!isShadowRoot(actualRoot)) {\n break; // reached the document (or a detached non-shadow root)\n }\n node = actualRoot.host; // cross the boundary outward\n }\n\n const totalCrossings = innermostFirst.length - 1;\n let truncated = false;\n let kept = innermostFirst;\n\n if (totalCrossings > maxShadowDepth) {\n // Drop the innermost over-budget trees, keeping the outermost\n // (maxShadowDepth + 1) trees. The new innermost kept segment's `target` is\n // already the shadow host of the first dropped tree.\n kept = innermostFirst.slice(totalCrossings - maxShadowDepth);\n truncated = true;\n }\n\n // Reverse to outermost-first so the engine joins document → target order.\n return { segments: kept.reverse(), truncated };\n}\n\n/**\n * Re-resolve a generated selector back to its element, piercing open shadow\n * roots at each boundary. The symmetric inverse of `engine.generate`.\n *\n * Returns `null` when any segment fails to match, or when a boundary crossing\n * hits a *closed* shadow root (`host.shadowRoot === null`) — closed roots are\n * opaque from outside, so such selectors cannot round-trip (a documented\n * limitation). Never throws on a malformed segment.\n *\n * @param root Root to resolve against — almost always `document`.\n * @param selector A selector produced by the engine (may contain boundary delimiters).\n */\nexport function resolveSelector(root: ParentNode, selector: string): Element | null {\n const segments = selector.split(SHADOW_BOUNDARY_DELIMITER);\n let scope: ParentNode | null = root;\n let found: Element | null = null;\n\n for (let i = 0; i < segments.length; i++) {\n if (scope === null) {\n return null; // previous segment's host had no (open) shadow root\n }\n const segment = segments[i].trim();\n try {\n found = resolveSegment(scope, segment);\n } catch {\n return null; // malformed segment — never throw out of the resolver\n }\n if (found === null) {\n return null;\n }\n if (i < segments.length - 1) {\n // Descend into this host's shadow root for the next segment. `null` for a\n // closed root ends resolution gracefully on the next iteration.\n scope = found.shadowRoot;\n }\n }\n\n return found;\n}\n\n/**\n * Resolve a single (non-delimited) segment within `scope`.\n *\n * A segment marked with {@link SHADOW_CHILD_CHAIN_PREFIX} is a root-anchored\n * \"direct child from the root\" chain (emitted by the fallback for a shadow-root\n * scope, where `querySelector` can't express that anchoring). We strip the\n * marker and resolve by strict direct-child descent. The marker is set\n * explicitly by the generator, so this stays correct regardless of what the\n * steps contain (tag, `:nth-of-type`, classes, …). Every other segment —\n * id/attribute-anchored, or any document-scope segment — resolves via a plain\n * `querySelector`.\n */\nfunction resolveSegment(scope: ParentNode, segment: string): Element | null {\n if (segment.startsWith(SHADOW_CHILD_CHAIN_PREFIX)) {\n return resolveChildChain(scope, segment.slice(SHADOW_CHILD_CHAIN_PREFIX.length));\n }\n return scope.querySelector(segment);\n}\n\n/**\n * Resolve a `>`-joined chain as a strict direct-child descent from `scope`. At\n * each level exactly one child matches the step (positional or otherwise via\n * `matches()`), so the walk is deterministic. Returns `null` if any step matches\n * no child.\n */\nfunction resolveChildChain(scope: ParentNode, chain: string): Element | null {\n const steps = chain.split('>').map((s) => s.trim());\n let children: Element[] = Array.from(scope.children);\n let el: Element | null = null;\n for (const step of steps) {\n el = children.find((child) => child.matches(step)) ?? null;\n if (el === null) {\n return null;\n }\n children = Array.from(el.children);\n }\n return el;\n}\n\n/**\n * Build a single positional step for `el`: `tag:nth-of-type(n)`, indexed among\n * its same-tag siblings. A parentless element emits the bare tag.\n *\n * `shadowAware` extends the parentless case: an element at the top of a shadow\n * tree has a null `parentElement` but can still have same-tag peers among the\n * `ShadowRoot`'s children, so it is indexed against those instead. When\n * `shadowAware` is false every parentless element emits the bare tag.\n */\nexport function positionalStep(el: Element, shadowAware: boolean): string {\n const tag = el.tagName.toLowerCase();\n const parent = el.parentElement;\n\n if (parent === null) {\n // Parentless means the document root (`<html>`), a detached element, or the\n // top of a shadow tree. Only the last has siblings worth indexing, and only\n // when the caller asks for shadow-aware stepping.\n const root = el.getRootNode();\n if (shadowAware && isShadowRoot(root)) {\n return `${tag}:nth-of-type(${sameTypeIndexAmong(el, root.children)})`;\n }\n return tag;\n }\n\n return `${tag}:nth-of-type(${sameTypeIndexAmong(el, parent.children)})`;\n}\n\n/**\n * 1-based index of `el` among same-tag siblings in `siblings`, mirroring\n * `:nth-of-type`. Takes an `HTMLCollection` rather than a parent `Element` so a\n * `ShadowRoot`'s children can be counted too — a `ShadowRoot` is not an\n * `Element` but does expose `children`.\n */\nfunction sameTypeIndexAmong(el: Element, siblings: HTMLCollection): number {\n let count = 0;\n for (let i = 0; i < siblings.length; i++) {\n const sibling = siblings[i];\n if (sibling.tagName === el.tagName) {\n count += 1;\n if (sibling === el) {\n return count;\n }\n }\n }\n // Defensive: element not found among its parent's children (shouldn't happen\n // for a live element). Return 1 rather than throwing.\n return 1;\n}\n"]}
@@ -13,18 +13,20 @@
13
13
  * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
14
14
  */
15
15
  export declare const PACKAGE_NAME = "@amplitude/element-selector";
16
- export type { Strategy, StrategyContext, ResolvedSelectorConfig, ElementSelectorRemoteConfig, ElementSelectorLogger, SelectorEngine, } from './types';
16
+ export type { Strategy, StrategyContext, ResolvedSelectorConfig, NormalizedSelectorConfig, ElementSelectorRemoteConfig, ElementSelectorLogger, SelectorEngine, } from './types';
17
17
  export { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, isStableId, } from './patterns/autogenerated-ids';
18
18
  export { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns, filterClasses, } from './patterns/unstable-classes';
19
19
  export { getStableId } from './helpers/get-stable-id';
20
20
  export { describeRelative } from './helpers/describe-relative';
21
+ export { resolveSelector, SHADOW_BOUNDARY_DELIMITER, composedParent, isShadowRoot, segmentWalk, walkComposedAncestors, collectOpenShadowRoots, MAX_SHADOW_COMPOSED_WALK_ITERATIONS, MAX_SHADOW_DOM_TRAVERSAL_NODES, } from './helpers/shadow';
22
+ export type { OpenShadowRootEntry } from './helpers/shadow';
21
23
  export { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';
22
24
  export { stableId as stableIdStrategy } from './strategies/stable-id';
23
25
  export { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';
24
26
  export type { OrchestratorOptions } from './orchestrator';
25
27
  export { fallbackCssPath } from './fallback-css-path';
26
28
  export { legacyCssPath } from './legacy-css-path';
27
- export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
29
+ export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG, normalizeResolvedConfig } from './config/resolve-config';
28
30
  export { createSelectorEngine } from './engine';
29
31
  export type { CreateSelectorEngineOptions } from './engine';
30
32
  export { generateSelector } from './generate-selector';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,YAAY,gCAAgC,CAAC;AAG1D,YAAY,EACV,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iCAAiC,EACjC,OAAO,IAAI,8BAA8B,EACzC,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,+BAA+B,EAC/B,OAAO,IAAI,4BAA4B,EACvC,aAAa,GACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAKtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAWtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAO5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,YAAY,gCAAgC,CAAC;AAG1D,YAAY,EACV,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iCAAiC,EACjC,OAAO,IAAI,8BAA8B,EACzC,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,+BAA+B,EAC/B,OAAO,IAAI,4BAA4B,EACvC,aAAa,GACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAS/D,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,mCAAmC,EACnC,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAKtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAWtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlH,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAO5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}
package/lib/cjs/index.js CHANGED
@@ -14,7 +14,7 @@
14
14
  * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
15
15
  */
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.generateSelector = exports.createSelectorEngine = exports.DEFAULT_RESOLVED_CONFIG = exports.resolveSelectorConfig = exports.legacyCssPath = exports.fallbackCssPath = exports.DEFAULT_STRATEGIES = exports.runOrchestrator = exports.stableIdStrategy = exports.explicitTrackingAttribute = exports.describeRelative = exports.getStableId = exports.filterClasses = exports.compileUnstableClassPatterns = exports.DEFAULT_UNSTABLE_CLASS_PATTERNS = exports.isStableId = exports.compileAutogeneratedIdPatterns = exports.DEFAULT_AUTOGENERATED_ID_PATTERNS = exports.PACKAGE_NAME = void 0;
17
+ exports.generateSelector = exports.createSelectorEngine = exports.normalizeResolvedConfig = exports.DEFAULT_RESOLVED_CONFIG = exports.resolveSelectorConfig = exports.legacyCssPath = exports.fallbackCssPath = exports.DEFAULT_STRATEGIES = exports.runOrchestrator = exports.stableIdStrategy = exports.explicitTrackingAttribute = exports.MAX_SHADOW_DOM_TRAVERSAL_NODES = exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS = exports.collectOpenShadowRoots = exports.walkComposedAncestors = exports.segmentWalk = exports.isShadowRoot = exports.composedParent = exports.SHADOW_BOUNDARY_DELIMITER = exports.resolveSelector = exports.describeRelative = exports.getStableId = exports.filterClasses = exports.compileUnstableClassPatterns = exports.DEFAULT_UNSTABLE_CLASS_PATTERNS = exports.isStableId = exports.compileAutogeneratedIdPatterns = exports.DEFAULT_AUTOGENERATED_ID_PATTERNS = exports.PACKAGE_NAME = void 0;
18
18
  exports.PACKAGE_NAME = '@amplitude/element-selector';
19
19
  // ===== Pattern packs =====
20
20
  var autogenerated_ids_1 = require("./patterns/autogenerated-ids");
@@ -30,6 +30,23 @@ var get_stable_id_1 = require("./helpers/get-stable-id");
30
30
  Object.defineProperty(exports, "getStableId", { enumerable: true, get: function () { return get_stable_id_1.getStableId; } });
31
31
  var describe_relative_1 = require("./helpers/describe-relative");
32
32
  Object.defineProperty(exports, "describeRelative", { enumerable: true, get: function () { return describe_relative_1.describeRelative; } });
33
+ // ===== Shadow DOM =====
34
+ // `resolveSelector` is the symmetric inverse of `engine.generate` — consumers
35
+ // (autocapture, dashboard tagging UI, Chrome extension) MUST re-resolve a
36
+ // generated selector through this rather than `document.querySelector`, since a
37
+ // shadow-piercing selector is delimited and `querySelector` can't cross shadow
38
+ // boundaries. `composedParent` is exported for consumers that walk ancestors
39
+ // (e.g. closest-tracked-ancestor logic) across shadow boundaries.
40
+ var shadow_1 = require("./helpers/shadow");
41
+ Object.defineProperty(exports, "resolveSelector", { enumerable: true, get: function () { return shadow_1.resolveSelector; } });
42
+ Object.defineProperty(exports, "SHADOW_BOUNDARY_DELIMITER", { enumerable: true, get: function () { return shadow_1.SHADOW_BOUNDARY_DELIMITER; } });
43
+ Object.defineProperty(exports, "composedParent", { enumerable: true, get: function () { return shadow_1.composedParent; } });
44
+ Object.defineProperty(exports, "isShadowRoot", { enumerable: true, get: function () { return shadow_1.isShadowRoot; } });
45
+ Object.defineProperty(exports, "segmentWalk", { enumerable: true, get: function () { return shadow_1.segmentWalk; } });
46
+ Object.defineProperty(exports, "walkComposedAncestors", { enumerable: true, get: function () { return shadow_1.walkComposedAncestors; } });
47
+ Object.defineProperty(exports, "collectOpenShadowRoots", { enumerable: true, get: function () { return shadow_1.collectOpenShadowRoots; } });
48
+ Object.defineProperty(exports, "MAX_SHADOW_COMPOSED_WALK_ITERATIONS", { enumerable: true, get: function () { return shadow_1.MAX_SHADOW_COMPOSED_WALK_ITERATIONS; } });
49
+ Object.defineProperty(exports, "MAX_SHADOW_DOM_TRAVERSAL_NODES", { enumerable: true, get: function () { return shadow_1.MAX_SHADOW_DOM_TRAVERSAL_NODES; } });
33
50
  // ===== Strategies =====
34
51
  var explicit_tracking_attribute_1 = require("./strategies/explicit-tracking-attribute");
35
52
  Object.defineProperty(exports, "explicitTrackingAttribute", { enumerable: true, get: function () { return explicit_tracking_attribute_1.explicitTrackingAttribute; } });
@@ -58,6 +75,7 @@ Object.defineProperty(exports, "legacyCssPath", { enumerable: true, get: functio
58
75
  var resolve_config_1 = require("./config/resolve-config");
59
76
  Object.defineProperty(exports, "resolveSelectorConfig", { enumerable: true, get: function () { return resolve_config_1.resolveSelectorConfig; } });
60
77
  Object.defineProperty(exports, "DEFAULT_RESOLVED_CONFIG", { enumerable: true, get: function () { return resolve_config_1.DEFAULT_RESOLVED_CONFIG; } });
78
+ Object.defineProperty(exports, "normalizeResolvedConfig", { enumerable: true, get: function () { return resolve_config_1.normalizeResolvedConfig; } });
61
79
  // ===== Engine factory =====
62
80
  var engine_1 = require("./engine");
63
81
  Object.defineProperty(exports, "createSelectorEngine", { enumerable: true, get: function () { return engine_1.createSelectorEngine; } });
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEU,QAAA,YAAY,GAAG,6BAA6B,CAAC;AAY1D,4BAA4B;AAC5B,kEAIsC;AAHpC,sIAAA,iCAAiC,OAAA;AACjC,mIAAA,OAAO,OAAkC;AACzC,+GAAA,UAAU,OAAA;AAGZ,gEAIqC;AAHnC,mIAAA,+BAA+B,OAAA;AAC/B,gIAAA,OAAO,OAAgC;AACvC,iHAAA,aAAa,OAAA;AAGf,sBAAsB;AACtB,yDAAsD;AAA7C,4GAAA,WAAW,OAAA;AACpB,iEAA+D;AAAtD,qHAAA,gBAAgB,OAAA;AAEzB,yBAAyB;AACzB,wFAAqF;AAA5E,wIAAA,yBAAyB,OAAA;AAClC,oDAAsE;AAA7D,6GAAA,QAAQ,OAAoB;AAErC,sCAAsC;AACtC,4EAA4E;AAC5E,8EAA8E;AAC9E,+CAAqE;AAA5D,+GAAA,eAAe,OAAA;AAAE,kHAAA,kBAAkB,OAAA;AAE5C,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AAExB,4BAA4B;AAC5B,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,4DAA4D;AAC5D,2EAA2E;AAC3E,qEAAqE;AACrE,sBAAsB;AACtB,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AAEtB,8BAA8B;AAC9B,0DAAyF;AAAhF,uHAAA,qBAAqB,OAAA;AAAE,yHAAA,uBAAuB,OAAA;AAEvD,6BAA6B;AAC7B,mCAAgD;AAAvC,8GAAA,oBAAoB,OAAA;AAG7B,6CAA6C;AAC7C,2EAA2E;AAC3E,gEAAgE;AAChE,yEAAyE;AACzE,YAAY;AACZ,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA","sourcesContent":["/**\n * @amplitude/element-selector\n *\n * Shared element-selector algorithm consumed by autocapture, the\n * app.amplitude.com tagging UI, and the Chrome extension visual tagger.\n *\n * This file is the package's public API surface. The orchestrator, fallback,\n * config resolver, and engine factory compose on top of the primitives\n * (types, pattern packs, helpers, strategies) to produce the runtime engine\n * consumers actually call.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nexport const PACKAGE_NAME = '@amplitude/element-selector';\n\n// ===== Types =====\nexport type {\n Strategy,\n StrategyContext,\n ResolvedSelectorConfig,\n ElementSelectorRemoteConfig,\n ElementSelectorLogger,\n SelectorEngine,\n} from './types';\n\n// ===== Pattern packs =====\nexport {\n DEFAULT_AUTOGENERATED_ID_PATTERNS,\n compile as compileAutogeneratedIdPatterns,\n isStableId,\n} from './patterns/autogenerated-ids';\n\nexport {\n DEFAULT_UNSTABLE_CLASS_PATTERNS,\n compile as compileUnstableClassPatterns,\n filterClasses,\n} from './patterns/unstable-classes';\n\n// ===== Helpers =====\nexport { getStableId } from './helpers/get-stable-id';\nexport { describeRelative } from './helpers/describe-relative';\n\n// ===== Strategies =====\nexport { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';\nexport { stableId as stableIdStrategy } from './strategies/stable-id';\n\n// ===== Orchestrator + fallback =====\n// Exposed publicly so the dashboard / Chrome extension can call them ad-hoc\n// without instantiating a full engine — useful for preview / debugging flows.\nexport { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';\nexport type { OrchestratorOptions } from './orchestrator';\nexport { fallbackCssPath } from './fallback-css-path';\n\n// ===== Legacy walker =====\n// Canonical home for the Chromium-DevTools-derived `cssPath` algorithm.\n// Both `plugin-autocapture-browser` and `session-replay-ui` historically\n// shipped their own copies kept in sync by comment; both will switch to\n// re-exporting from here so the two can never drift again. End consumers\n// rarely need to call this directly — `engine.generate` and\n// `generateSelector` route through it automatically — but it's exported so\n// the SDK and dashboard can drop their local copies without breaking\n// downstream imports.\nexport { legacyCssPath } from './legacy-css-path';\n\n// ===== Config resolver =====\nexport { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';\n\n// ===== Engine factory =====\nexport { createSelectorEngine } from './engine';\nexport type { CreateSelectorEngineOptions } from './engine';\n\n// ===== Top-level selector entry point =====\n// Use this from React contexts / boot-time call sites where the engine may\n// not yet be available. When the engine *is* present, just call\n// `engine.generate(el)` directly — it has the same kill-switch semantics\n// baked in.\nexport { generateSelector } from './generate-selector';\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEU,QAAA,YAAY,GAAG,6BAA6B,CAAC;AAa1D,4BAA4B;AAC5B,kEAIsC;AAHpC,sIAAA,iCAAiC,OAAA;AACjC,mIAAA,OAAO,OAAkC;AACzC,+GAAA,UAAU,OAAA;AAGZ,gEAIqC;AAHnC,mIAAA,+BAA+B,OAAA;AAC/B,gIAAA,OAAO,OAAgC;AACvC,iHAAA,aAAa,OAAA;AAGf,sBAAsB;AACtB,yDAAsD;AAA7C,4GAAA,WAAW,OAAA;AACpB,iEAA+D;AAAtD,qHAAA,gBAAgB,OAAA;AAEzB,yBAAyB;AACzB,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,+EAA+E;AAC/E,6EAA6E;AAC7E,kEAAkE;AAClE,2CAU0B;AATxB,yGAAA,eAAe,OAAA;AACf,mHAAA,yBAAyB,OAAA;AACzB,wGAAA,cAAc,OAAA;AACd,sGAAA,YAAY,OAAA;AACZ,qGAAA,WAAW,OAAA;AACX,+GAAA,qBAAqB,OAAA;AACrB,gHAAA,sBAAsB,OAAA;AACtB,6HAAA,mCAAmC,OAAA;AACnC,wHAAA,8BAA8B,OAAA;AAIhC,yBAAyB;AACzB,wFAAqF;AAA5E,wIAAA,yBAAyB,OAAA;AAClC,oDAAsE;AAA7D,6GAAA,QAAQ,OAAoB;AAErC,sCAAsC;AACtC,4EAA4E;AAC5E,8EAA8E;AAC9E,+CAAqE;AAA5D,+GAAA,eAAe,OAAA;AAAE,kHAAA,kBAAkB,OAAA;AAE5C,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AAExB,4BAA4B;AAC5B,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,4DAA4D;AAC5D,2EAA2E;AAC3E,qEAAqE;AACrE,sBAAsB;AACtB,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AAEtB,8BAA8B;AAC9B,0DAAkH;AAAzG,uHAAA,qBAAqB,OAAA;AAAE,yHAAA,uBAAuB,OAAA;AAAE,yHAAA,uBAAuB,OAAA;AAEhF,6BAA6B;AAC7B,mCAAgD;AAAvC,8GAAA,oBAAoB,OAAA;AAG7B,6CAA6C;AAC7C,2EAA2E;AAC3E,gEAAgE;AAChE,yEAAyE;AACzE,YAAY;AACZ,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA","sourcesContent":["/**\n * @amplitude/element-selector\n *\n * Shared element-selector algorithm consumed by autocapture, the\n * app.amplitude.com tagging UI, and the Chrome extension visual tagger.\n *\n * This file is the package's public API surface. The orchestrator, fallback,\n * config resolver, and engine factory compose on top of the primitives\n * (types, pattern packs, helpers, strategies) to produce the runtime engine\n * consumers actually call.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nexport const PACKAGE_NAME = '@amplitude/element-selector';\n\n// ===== Types =====\nexport type {\n Strategy,\n StrategyContext,\n ResolvedSelectorConfig,\n NormalizedSelectorConfig,\n ElementSelectorRemoteConfig,\n ElementSelectorLogger,\n SelectorEngine,\n} from './types';\n\n// ===== Pattern packs =====\nexport {\n DEFAULT_AUTOGENERATED_ID_PATTERNS,\n compile as compileAutogeneratedIdPatterns,\n isStableId,\n} from './patterns/autogenerated-ids';\n\nexport {\n DEFAULT_UNSTABLE_CLASS_PATTERNS,\n compile as compileUnstableClassPatterns,\n filterClasses,\n} from './patterns/unstable-classes';\n\n// ===== Helpers =====\nexport { getStableId } from './helpers/get-stable-id';\nexport { describeRelative } from './helpers/describe-relative';\n\n// ===== Shadow DOM =====\n// `resolveSelector` is the symmetric inverse of `engine.generate` — consumers\n// (autocapture, dashboard tagging UI, Chrome extension) MUST re-resolve a\n// generated selector through this rather than `document.querySelector`, since a\n// shadow-piercing selector is delimited and `querySelector` can't cross shadow\n// boundaries. `composedParent` is exported for consumers that walk ancestors\n// (e.g. closest-tracked-ancestor logic) across shadow boundaries.\nexport {\n resolveSelector,\n SHADOW_BOUNDARY_DELIMITER,\n composedParent,\n isShadowRoot,\n segmentWalk,\n walkComposedAncestors,\n collectOpenShadowRoots,\n MAX_SHADOW_COMPOSED_WALK_ITERATIONS,\n MAX_SHADOW_DOM_TRAVERSAL_NODES,\n} from './helpers/shadow';\nexport type { OpenShadowRootEntry } from './helpers/shadow';\n\n// ===== Strategies =====\nexport { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';\nexport { stableId as stableIdStrategy } from './strategies/stable-id';\n\n// ===== Orchestrator + fallback =====\n// Exposed publicly so the dashboard / Chrome extension can call them ad-hoc\n// without instantiating a full engine — useful for preview / debugging flows.\nexport { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';\nexport type { OrchestratorOptions } from './orchestrator';\nexport { fallbackCssPath } from './fallback-css-path';\n\n// ===== Legacy walker =====\n// Canonical home for the Chromium-DevTools-derived `cssPath` algorithm.\n// Both `plugin-autocapture-browser` and `session-replay-ui` historically\n// shipped their own copies kept in sync by comment; both will switch to\n// re-exporting from here so the two can never drift again. End consumers\n// rarely need to call this directly — `engine.generate` and\n// `generateSelector` route through it automatically — but it's exported so\n// the SDK and dashboard can drop their local copies without breaking\n// downstream imports.\nexport { legacyCssPath } from './legacy-css-path';\n\n// ===== Config resolver =====\nexport { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG, normalizeResolvedConfig } from './config/resolve-config';\n\n// ===== Engine factory =====\nexport { createSelectorEngine } from './engine';\nexport type { CreateSelectorEngineOptions } from './engine';\n\n// ===== Top-level selector entry point =====\n// Use this from React contexts / boot-time call sites where the engine may\n// not yet be available. When the engine *is* present, just call\n// `engine.generate(el)` directly — it has the same kill-switch semantics\n// baked in.\nexport { generateSelector } from './generate-selector';\n"]}
@@ -1 +1 @@
1
- {"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,QAAQ,EAAmB,MAAM,SAAS,CAAC;AAKnG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,QAAQ,CAAiD,CAAC;AAEzG,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrC,mGAAmG;IACnG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,IAAI,CAoCf"}
1
+ {"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,QAAQ,EAAmB,MAAM,SAAS,CAAC;AAMnG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,QAAQ,CAAiD,CAAC;AAEzG,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrC,mGAAmG;IACnG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,IAAI,CAqCf"}
@@ -26,6 +26,7 @@
26
26
  Object.defineProperty(exports, "__esModule", { value: true });
27
27
  exports.runOrchestrator = exports.DEFAULT_STRATEGIES = void 0;
28
28
  var tslib_1 = require("tslib");
29
+ var resolve_config_1 = require("./config/resolve-config");
29
30
  var explicit_tracking_attribute_1 = require("./strategies/explicit-tracking-attribute");
30
31
  var stable_id_1 = require("./strategies/stable-id");
31
32
  var describe_relative_1 = require("./helpers/describe-relative");
@@ -55,10 +56,11 @@ function runOrchestrator(el, config, options) {
55
56
  var e_1, _a;
56
57
  var _b, _c, _d;
57
58
  if (options === void 0) { options = {}; }
59
+ var resolved = (0, resolve_config_1.normalizeResolvedConfig)(config);
58
60
  var strategies = (_b = options.strategies) !== null && _b !== void 0 ? _b : exports.DEFAULT_STRATEGIES;
59
61
  var scope = (_d = (_c = options.scope) !== null && _c !== void 0 ? _c : el.ownerDocument) !== null && _d !== void 0 ? _d : document;
60
- var ctx = { scope: scope, config: config };
61
- var walk = collectWalk(el, config.maxAncestorWalkDepth);
62
+ var ctx = { scope: scope, config: resolved };
63
+ var walk = collectWalk(el, resolved.maxAncestorWalkDepth);
62
64
  try {
63
65
  // Two-pass: try strategy[0] across the whole walk, then strategy[1], etc.
64
66
  // This gives an "explicit anchor at any depth beats a structural anchor any
@@ -1 +1 @@
1
- {"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../src/orchestrator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Orchestrator — the entry point for the v1 element-selector algorithm.\n *\n * Given a click target, the orchestrator walks from the target up through its\n * ancestors and tries each registered strategy at each level. The first\n * strategy that returns a non-null candidate (and produces a selector that\n * resolves uniquely under the scope) wins; the trail of intermediate elements\n * between the anchor and the original target is then expressed as a positional\n * descent via `describeRelative`.\n *\n * Two-pass design: every ancestor is tried under the `explicitTrackingAttribute`\n * strategy first, then the entire walk repeats with `stableId`. This ordering\n * means an explicit anchor anywhere up the tree always beats a stable id deeper\n * down — the design doc describes this as the \"customer intent overrides\n * structural inference\" rule.\n *\n * The orchestrator does not own the fallback. When no strategy + walk produces\n * a unique selector, it returns `null` and the engine wires the\n * `fallback-css-path` path in instead. Keeping the fallback outside the\n * orchestrator keeps the strategy chain testable in isolation.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nimport { ElementSelectorLogger, ResolvedSelectorConfig, Strategy, StrategyContext } from './types';\nimport { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';\nimport { stableId as stableIdStrategy } from './strategies/stable-id';\nimport { describeRelative } from './helpers/describe-relative';\n\n/**\n * Default strategy chain in priority order. Used by the engine factory when the\n * caller doesn't provide an explicit list. Exported for diagnostics — tests\n * import this so they don't have to duplicate the list.\n */\nexport const DEFAULT_STRATEGIES: ReadonlyArray<Strategy> = [explicitTrackingAttribute, stableIdStrategy];\n\nexport interface OrchestratorOptions {\n /** Strategy chain. Defaults to `DEFAULT_STRATEGIES`. Order = priority. */\n strategies?: ReadonlyArray<Strategy>;\n /** Document or shadow root used for uniqueness checks. Defaults to the target's owner document. */\n scope?: ParentNode;\n /**\n * Optional logger. When provided, the orchestrator emits a `debug` log if a\n * strategy produces a malformed selector that throws during the uniqueness\n * check — useful for diagnosing strategy bugs without crashing the engine.\n */\n logger?: ElementSelectorLogger;\n}\n\n/**\n * Try to produce a CSS selector for `el` using the strategy chain.\n *\n * Returns the composed selector string on success, or `null` if every strategy\n * declined at every walked ancestor. Callers (the engine) treat `null` as the\n * signal to invoke the fallback walker.\n *\n * Selector format on success:\n *\n * - Anchor only (target itself was an anchor): `<anchor-selector>`\n * - Anchor + trail (anchor was an ancestor): `<anchor-selector> > <descent>`\n *\n * Where `<anchor-selector>` is whatever the winning strategy returned for the\n * anchor element (e.g. `[data-amp-track-id=\"login-form\"]` or `div#hero`), and\n * `<descent>` is `describeRelative(anchor, trail)`.\n */\nexport function runOrchestrator(\n el: Element,\n config: ResolvedSelectorConfig,\n options: OrchestratorOptions = {},\n): string | null {\n const strategies = options.strategies ?? DEFAULT_STRATEGIES;\n const scope: ParentNode = options.scope ?? el.ownerDocument ?? document;\n const ctx: StrategyContext = { scope, config };\n\n const walk = collectWalk(el, config.maxAncestorWalkDepth);\n\n // Two-pass: try strategy[0] across the whole walk, then strategy[1], etc.\n // This gives an \"explicit anchor at any depth beats a structural anchor any\n // depth\" priority, which matches the design doc's \"customer intent overrides\n // structural inference\" rule.\n for (const strategy of strategies) {\n for (let i = 0; i < walk.length; i++) {\n const anchor = walk[i];\n const anchorSelector = strategy.try(anchor, ctx);\n if (anchorSelector === null) continue;\n\n // Anchor was the target itself — no descent needed.\n if (i === 0) {\n if (isUniqueMatch(scope, anchorSelector, el, strategy.name, options.logger)) {\n return anchorSelector;\n }\n continue;\n }\n\n // Anchor was an ancestor — descend back to the target through the trail.\n const trail = walk.slice(0, i).reverse();\n const descent = describeRelative(anchor, trail);\n const composed = `${anchorSelector} > ${descent}`;\n if (isUniqueMatch(scope, composed, el, strategy.name, options.logger)) {\n return composed;\n }\n }\n }\n\n return null;\n}\n\n/**\n * Build the walk array `[target, parent, grandparent, ...]`, stopping at\n * `<html>` (or at the depth limit if configured). Excludes the document\n * element's parent (which is the Document node and not an Element).\n */\nfunction collectWalk(el: Element, maxDepth: number | undefined): Element[] {\n const walk: Element[] = [];\n let cursor: Element | null = el;\n while (cursor !== null) {\n walk.push(cursor);\n if (maxDepth !== undefined && walk.length > maxDepth) break;\n cursor = cursor.parentElement;\n }\n return walk;\n}\n\n/**\n * Check whether `selector` resolves to exactly `el` and no other element in\n * `scope`. The strategies themselves don't run uniqueness checks — that's the\n * orchestrator's job, so strategies stay pure transforms and stay testable in\n * isolation.\n *\n * When the selector is malformed (which is a strategy bug rather than user\n * input), we log at `debug` and return false rather than throwing. The log\n * lets engineers diagnose a misbehaving strategy without the engine taking\n * down whatever it's wired into.\n */\nfunction isUniqueMatch(\n scope: ParentNode,\n selector: string,\n el: Element,\n strategyName: string,\n logger?: ElementSelectorLogger,\n): boolean {\n let matches: NodeListOf<Element>;\n try {\n matches = scope.querySelectorAll(selector);\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n logger?.debug(\n `@amplitude/element-selector: strategy \"${strategyName}\" emitted a malformed selector \"${selector}\" (${message})`,\n );\n return false;\n }\n return matches.length === 1 && matches[0] === el;\n}\n"]}
1
+ {"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../src/orchestrator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Orchestrator — the entry point for the v1 element-selector algorithm.\n *\n * Given a click target, the orchestrator walks from the target up through its\n * ancestors and tries each registered strategy at each level. The first\n * strategy that returns a non-null candidate (and produces a selector that\n * resolves uniquely under the scope) wins; the trail of intermediate elements\n * between the anchor and the original target is then expressed as a positional\n * descent via `describeRelative`.\n *\n * Two-pass design: every ancestor is tried under the `explicitTrackingAttribute`\n * strategy first, then the entire walk repeats with `stableId`. This ordering\n * means an explicit anchor anywhere up the tree always beats a stable id deeper\n * down — the design doc describes this as the \"customer intent overrides\n * structural inference\" rule.\n *\n * The orchestrator does not own the fallback. When no strategy + walk produces\n * a unique selector, it returns `null` and the engine wires the\n * `fallback-css-path` path in instead. Keeping the fallback outside the\n * orchestrator keeps the strategy chain testable in isolation.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nimport { ElementSelectorLogger, ResolvedSelectorConfig, Strategy, StrategyContext } from './types';\nimport { normalizeResolvedConfig } from './config/resolve-config';\nimport { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';\nimport { stableId as stableIdStrategy } from './strategies/stable-id';\nimport { describeRelative } from './helpers/describe-relative';\n\n/**\n * Default strategy chain in priority order. Used by the engine factory when the\n * caller doesn't provide an explicit list. Exported for diagnostics — tests\n * import this so they don't have to duplicate the list.\n */\nexport const DEFAULT_STRATEGIES: ReadonlyArray<Strategy> = [explicitTrackingAttribute, stableIdStrategy];\n\nexport interface OrchestratorOptions {\n /** Strategy chain. Defaults to `DEFAULT_STRATEGIES`. Order = priority. */\n strategies?: ReadonlyArray<Strategy>;\n /** Document or shadow root used for uniqueness checks. Defaults to the target's owner document. */\n scope?: ParentNode;\n /**\n * Optional logger. When provided, the orchestrator emits a `debug` log if a\n * strategy produces a malformed selector that throws during the uniqueness\n * check — useful for diagnosing strategy bugs without crashing the engine.\n */\n logger?: ElementSelectorLogger;\n}\n\n/**\n * Try to produce a CSS selector for `el` using the strategy chain.\n *\n * Returns the composed selector string on success, or `null` if every strategy\n * declined at every walked ancestor. Callers (the engine) treat `null` as the\n * signal to invoke the fallback walker.\n *\n * Selector format on success:\n *\n * - Anchor only (target itself was an anchor): `<anchor-selector>`\n * - Anchor + trail (anchor was an ancestor): `<anchor-selector> > <descent>`\n *\n * Where `<anchor-selector>` is whatever the winning strategy returned for the\n * anchor element (e.g. `[data-amp-track-id=\"login-form\"]` or `div#hero`), and\n * `<descent>` is `describeRelative(anchor, trail)`.\n */\nexport function runOrchestrator(\n el: Element,\n config: ResolvedSelectorConfig,\n options: OrchestratorOptions = {},\n): string | null {\n const resolved = normalizeResolvedConfig(config);\n const strategies = options.strategies ?? DEFAULT_STRATEGIES;\n const scope: ParentNode = options.scope ?? el.ownerDocument ?? document;\n const ctx: StrategyContext = { scope, config: resolved };\n\n const walk = collectWalk(el, resolved.maxAncestorWalkDepth);\n\n // Two-pass: try strategy[0] across the whole walk, then strategy[1], etc.\n // This gives an \"explicit anchor at any depth beats a structural anchor any\n // depth\" priority, which matches the design doc's \"customer intent overrides\n // structural inference\" rule.\n for (const strategy of strategies) {\n for (let i = 0; i < walk.length; i++) {\n const anchor = walk[i];\n const anchorSelector = strategy.try(anchor, ctx);\n if (anchorSelector === null) continue;\n\n // Anchor was the target itself — no descent needed.\n if (i === 0) {\n if (isUniqueMatch(scope, anchorSelector, el, strategy.name, options.logger)) {\n return anchorSelector;\n }\n continue;\n }\n\n // Anchor was an ancestor — descend back to the target through the trail.\n const trail = walk.slice(0, i).reverse();\n const descent = describeRelative(anchor, trail);\n const composed = `${anchorSelector} > ${descent}`;\n if (isUniqueMatch(scope, composed, el, strategy.name, options.logger)) {\n return composed;\n }\n }\n }\n\n return null;\n}\n\n/**\n * Build the walk array `[target, parent, grandparent, ...]`, stopping at\n * `<html>` (or at the depth limit if configured). Excludes the document\n * element's parent (which is the Document node and not an Element).\n */\nfunction collectWalk(el: Element, maxDepth: number | undefined): Element[] {\n const walk: Element[] = [];\n let cursor: Element | null = el;\n while (cursor !== null) {\n walk.push(cursor);\n if (maxDepth !== undefined && walk.length > maxDepth) break;\n cursor = cursor.parentElement;\n }\n return walk;\n}\n\n/**\n * Check whether `selector` resolves to exactly `el` and no other element in\n * `scope`. The strategies themselves don't run uniqueness checks — that's the\n * orchestrator's job, so strategies stay pure transforms and stay testable in\n * isolation.\n *\n * When the selector is malformed (which is a strategy bug rather than user\n * input), we log at `debug` and return false rather than throwing. The log\n * lets engineers diagnose a misbehaving strategy without the engine taking\n * down whatever it's wired into.\n */\nfunction isUniqueMatch(\n scope: ParentNode,\n selector: string,\n el: Element,\n strategyName: string,\n logger?: ElementSelectorLogger,\n): boolean {\n let matches: NodeListOf<Element>;\n try {\n matches = scope.querySelectorAll(selector);\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n logger?.debug(\n `@amplitude/element-selector: strategy \"${strategyName}\" emitted a malformed selector \"${selector}\" (${message})`,\n );\n return false;\n }\n return matches.length === 1 && matches[0] === el;\n}\n"]}
@@ -60,7 +60,35 @@ export interface ResolvedSelectorConfig {
60
60
  unstableClassPatterns: RegExp[];
61
61
  /** Optional throttle on the ancestor walk. When undefined, the walk runs to <html>. */
62
62
  maxAncestorWalkDepth?: number;
63
+ /**
64
+ * Dedicated kill switch for shadow-DOM piercing. Defaults to false. When
65
+ * false, `generate` walks only the target's own tree (today's behavior, no
66
+ * boundary delimiter) even when the element lives inside a shadow root. This
67
+ * is independent of `enabled` so shadow support can be rolled out separately.
68
+ *
69
+ * Optional on input — the engine applies {@link DEFAULT_SHADOW_DOM_ENABLED}
70
+ * when omitted so downstream consumers are not broken by new fields.
71
+ */
72
+ shadowDomEnabled?: boolean;
73
+ /**
74
+ * Maximum number of shadow-boundary crossings the engine will traverse when
75
+ * `shadowDomEnabled` is true. Defaults to 1 (a single shadow level) and is
76
+ * clamped to the internal hard cap `MAX_SHADOW_DOM_DEPTH`. A target deeper
77
+ * than this produces a best-effort selector for the outermost in-budget host.
78
+ *
79
+ * Optional on input — the engine applies {@link DEFAULT_MAX_SHADOW_DOM_DEPTH}
80
+ * when omitted.
81
+ */
82
+ maxShadowDomDepth?: number;
63
83
  }
84
+ /**
85
+ * Runtime config after the engine applies shadow-field defaults. Consumers
86
+ * reading `getConfig()` always see normalized values.
87
+ */
88
+ export type NormalizedSelectorConfig = ResolvedSelectorConfig & {
89
+ shadowDomEnabled: boolean;
90
+ maxShadowDomDepth: number;
91
+ };
64
92
  /**
65
93
  * Remote-config payload shape. Each field is optional; absent fields fall back
66
94
  * to built-in defaults. Customers see the defaults in the remote-config UI and
@@ -77,6 +105,13 @@ export interface ElementSelectorRemoteConfig {
77
105
  unstableClassPatterns?: string[];
78
106
  /** Defensive throttle on the ancestor walk. Omit for unbounded walking to <html>. */
79
107
  maxAncestorWalkDepth?: number;
108
+ /** Kill switch for shadow-DOM piercing. When omitted, defaults to false (shadow support off). */
109
+ shadowDomEnabled?: boolean;
110
+ /**
111
+ * Max number of shadow-boundary crossings to traverse. When omitted, defaults
112
+ * to 1. Clamped at resolve time into [1, MAX_SHADOW_DOM_DEPTH] (currently 10).
113
+ */
114
+ maxShadowDomDepth?: number;
80
115
  }
81
116
  /**
82
117
  * Public interface of the runtime engine. Implementation lands in the
@@ -87,7 +122,7 @@ export interface SelectorEngine {
87
122
  /** Produce a CSS selector string identifying `el` using the engine's current config. */
88
123
  generate(el: Element): string;
89
124
  /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */
90
- getConfig(): Readonly<ResolvedSelectorConfig>;
125
+ getConfig(): Readonly<NormalizedSelectorConfig>;
91
126
  /** Replace the current config. Notifies any onConfigChange subscribers. */
92
127
  updateConfig(next: ResolvedSelectorConfig): void;
93
128
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,iGAAiG;IACjG,yBAAyB,EAAE,MAAM,CAAC;IAClC,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,uGAAuG;IACvG,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,0FAA0F;IAC1F,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IAE9B,gGAAgG;IAChG,SAAS,IAAI,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IAE9C,2EAA2E;IAC3E,YAAY,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEjD;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1E"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,iGAAiG;IACjG,yBAAyB,EAAE,MAAM,CAAC;IAClC,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,uGAAuG;IACvG,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,sBAAsB,GAAG;IAC9D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,0FAA0F;IAC1F,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IAE9B,gGAAgG;IAChG,SAAS,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAAC;IAEhD,2EAA2E;IAC3E,YAAY,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEjD;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1E"}
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * Core type definitions for the v1 element-selector algorithm.\n *\n * These are the public-API contract that consumers (autocapture SDK, dashboard\n * tagging UI, Chrome extension visual tagger) design against. They land before\n * any implementation so the contract is stable for cross-team review.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\n/**\n * A pluggable selector strategy. Given an element + context, returns a CSS\n * selector string candidate (which the orchestrator will then uniqueness-check)\n * or `null` when the strategy doesn't apply to this element.\n */\nexport interface Strategy {\n /** Stable identifier for the strategy. Used for diagnostics and remote-config references. */\n readonly name: string;\n\n /**\n * Produce a candidate selector for `el`, or `null` if this strategy has\n * nothing to contribute for this element. Strategies are pure transforms —\n * they never call `querySelectorAll` themselves; uniqueness is checked by\n * the orchestrator in the next layer up.\n */\n try(el: Element, ctx: StrategyContext): string | null;\n}\n\n/**\n * Context passed to every strategy invocation. `scope` is the document or\n * shadow root the orchestrator will use for uniqueness checks; `config` is the\n * resolved configuration (defaults + remote + local options merged).\n */\nexport interface StrategyContext {\n scope: ParentNode;\n config: ResolvedSelectorConfig;\n}\n\n/**\n * Logger shape accepted by element-selector diagnostics.\n *\n * This is intentionally structural so callers can pass the SDK's\n * `@amplitude/analytics-core` ILogger without this package needing to import\n * analytics-core types during standalone tests/builds.\n */\nexport interface ElementSelectorLogger {\n warn(...args: unknown[]): void;\n debug(...args: unknown[]): void;\n}\n\n/**\n * Fully-resolved configuration consumed at runtime. Produced by\n * `resolveSelectorConfig` (lands in the orchestration PR) from the\n * `ElementSelectorRemoteConfig` payload plus built-in defaults.\n */\nexport interface ResolvedSelectorConfig {\n /** Master kill switch. When false, autocapture reverts to legacy cssPath. */\n enabled: boolean;\n /** Attribute name customers can use to set or suppress anchors. Default: 'data-amp-track-id'. */\n explicitTrackingAttribute: string;\n /** Compiled regex patterns matching ids the algorithm should treat as autogenerated. */\n autogeneratedIdPatterns: RegExp[];\n /** Compiled regex patterns matching classes the fallback should filter from sibling disambiguation. */\n unstableClassPatterns: RegExp[];\n /** Optional throttle on the ancestor walk. When undefined, the walk runs to <html>. */\n maxAncestorWalkDepth?: number;\n}\n\n/**\n * Remote-config payload shape. Each field is optional; absent fields fall back\n * to built-in defaults. Customers see the defaults in the remote-config UI and\n * may add or remove patterns as needed.\n */\nexport interface ElementSelectorRemoteConfig {\n /** Kill switch. When set, overrides the default at resolve time. */\n enabled?: boolean;\n /** Override the attribute name used for explicit tracking. */\n explicitTrackingAttribute?: string;\n /** Full replacement for the autogenerated-id pattern list. When omitted, defaults apply. */\n autogeneratedIdPatterns?: string[];\n /** Full replacement for the unstable-class pattern list. When omitted, defaults apply. */\n unstableClassPatterns?: string[];\n /** Defensive throttle on the ancestor walk. Omit for unbounded walking to <html>. */\n maxAncestorWalkDepth?: number;\n}\n\n/**\n * Public interface of the runtime engine. Implementation lands in the\n * orchestration PR; the interface is declared here so consumers can write\n * against the contract before the class exists.\n */\nexport interface SelectorEngine {\n /** Produce a CSS selector string identifying `el` using the engine's current config. */\n generate(el: Element): string;\n\n /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */\n getConfig(): Readonly<ResolvedSelectorConfig>;\n\n /** Replace the current config. Notifies any onConfigChange subscribers. */\n updateConfig(next: ResolvedSelectorConfig): void;\n\n /**\n * Subscribe to config-change notifications. Returns an unsubscribe function.\n * Used by the Chrome extension to keep its locally-hydrated engine in sync\n * with the customer's SDK as remote config updates flow in.\n */\n onConfigChange(cb: (config: ResolvedSelectorConfig) => void): () => void;\n}\n"]}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * Core type definitions for the v1 element-selector algorithm.\n *\n * These are the public-API contract that consumers (autocapture SDK, dashboard\n * tagging UI, Chrome extension visual tagger) design against. They land before\n * any implementation so the contract is stable for cross-team review.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\n/**\n * A pluggable selector strategy. Given an element + context, returns a CSS\n * selector string candidate (which the orchestrator will then uniqueness-check)\n * or `null` when the strategy doesn't apply to this element.\n */\nexport interface Strategy {\n /** Stable identifier for the strategy. Used for diagnostics and remote-config references. */\n readonly name: string;\n\n /**\n * Produce a candidate selector for `el`, or `null` if this strategy has\n * nothing to contribute for this element. Strategies are pure transforms —\n * they never call `querySelectorAll` themselves; uniqueness is checked by\n * the orchestrator in the next layer up.\n */\n try(el: Element, ctx: StrategyContext): string | null;\n}\n\n/**\n * Context passed to every strategy invocation. `scope` is the document or\n * shadow root the orchestrator will use for uniqueness checks; `config` is the\n * resolved configuration (defaults + remote + local options merged).\n */\nexport interface StrategyContext {\n scope: ParentNode;\n config: ResolvedSelectorConfig;\n}\n\n/**\n * Logger shape accepted by element-selector diagnostics.\n *\n * This is intentionally structural so callers can pass the SDK's\n * `@amplitude/analytics-core` ILogger without this package needing to import\n * analytics-core types during standalone tests/builds.\n */\nexport interface ElementSelectorLogger {\n warn(...args: unknown[]): void;\n debug(...args: unknown[]): void;\n}\n\n/**\n * Fully-resolved configuration consumed at runtime. Produced by\n * `resolveSelectorConfig` (lands in the orchestration PR) from the\n * `ElementSelectorRemoteConfig` payload plus built-in defaults.\n */\nexport interface ResolvedSelectorConfig {\n /** Master kill switch. When false, autocapture reverts to legacy cssPath. */\n enabled: boolean;\n /** Attribute name customers can use to set or suppress anchors. Default: 'data-amp-track-id'. */\n explicitTrackingAttribute: string;\n /** Compiled regex patterns matching ids the algorithm should treat as autogenerated. */\n autogeneratedIdPatterns: RegExp[];\n /** Compiled regex patterns matching classes the fallback should filter from sibling disambiguation. */\n unstableClassPatterns: RegExp[];\n /** Optional throttle on the ancestor walk. When undefined, the walk runs to <html>. */\n maxAncestorWalkDepth?: number;\n /**\n * Dedicated kill switch for shadow-DOM piercing. Defaults to false. When\n * false, `generate` walks only the target's own tree (today's behavior, no\n * boundary delimiter) even when the element lives inside a shadow root. This\n * is independent of `enabled` so shadow support can be rolled out separately.\n *\n * Optional on input — the engine applies {@link DEFAULT_SHADOW_DOM_ENABLED}\n * when omitted so downstream consumers are not broken by new fields.\n */\n shadowDomEnabled?: boolean;\n /**\n * Maximum number of shadow-boundary crossings the engine will traverse when\n * `shadowDomEnabled` is true. Defaults to 1 (a single shadow level) and is\n * clamped to the internal hard cap `MAX_SHADOW_DOM_DEPTH`. A target deeper\n * than this produces a best-effort selector for the outermost in-budget host.\n *\n * Optional on input — the engine applies {@link DEFAULT_MAX_SHADOW_DOM_DEPTH}\n * when omitted.\n */\n maxShadowDomDepth?: number;\n}\n\n/**\n * Runtime config after the engine applies shadow-field defaults. Consumers\n * reading `getConfig()` always see normalized values.\n */\nexport type NormalizedSelectorConfig = ResolvedSelectorConfig & {\n shadowDomEnabled: boolean;\n maxShadowDomDepth: number;\n};\n\n/**\n * Remote-config payload shape. Each field is optional; absent fields fall back\n * to built-in defaults. Customers see the defaults in the remote-config UI and\n * may add or remove patterns as needed.\n */\nexport interface ElementSelectorRemoteConfig {\n /** Kill switch. When set, overrides the default at resolve time. */\n enabled?: boolean;\n /** Override the attribute name used for explicit tracking. */\n explicitTrackingAttribute?: string;\n /** Full replacement for the autogenerated-id pattern list. When omitted, defaults apply. */\n autogeneratedIdPatterns?: string[];\n /** Full replacement for the unstable-class pattern list. When omitted, defaults apply. */\n unstableClassPatterns?: string[];\n /** Defensive throttle on the ancestor walk. Omit for unbounded walking to <html>. */\n maxAncestorWalkDepth?: number;\n /** Kill switch for shadow-DOM piercing. When omitted, defaults to false (shadow support off). */\n shadowDomEnabled?: boolean;\n /**\n * Max number of shadow-boundary crossings to traverse. When omitted, defaults\n * to 1. Clamped at resolve time into [1, MAX_SHADOW_DOM_DEPTH] (currently 10).\n */\n maxShadowDomDepth?: number;\n}\n\n/**\n * Public interface of the runtime engine. Implementation lands in the\n * orchestration PR; the interface is declared here so consumers can write\n * against the contract before the class exists.\n */\nexport interface SelectorEngine {\n /** Produce a CSS selector string identifying `el` using the engine's current config. */\n generate(el: Element): string;\n\n /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */\n getConfig(): Readonly<NormalizedSelectorConfig>;\n\n /** Replace the current config. Notifies any onConfigChange subscribers. */\n updateConfig(next: ResolvedSelectorConfig): void;\n\n /**\n * Subscribe to config-change notifications. Returns an unsubscribe function.\n * Used by the Chrome extension to keep its locally-hydrated engine in sync\n * with the customer's SDK as remote config updates flow in.\n */\n onConfigChange(cb: (config: ResolvedSelectorConfig) => void): () => void;\n}\n"]}
@@ -27,13 +27,24 @@
27
27
  * See the design doc:
28
28
  * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
29
29
  */
30
- import { ElementSelectorLogger, ElementSelectorRemoteConfig, ResolvedSelectorConfig } from '../types';
30
+ import { ElementSelectorLogger, ElementSelectorRemoteConfig, NormalizedSelectorConfig, ResolvedSelectorConfig } from '../types';
31
+ /** Shadow-DOM piercing is disabled by default, opt in via remote config. */
32
+ export declare const DEFAULT_SHADOW_DOM_ENABLED = false;
33
+ /** Default number of shadow-boundary crossings to traverse when piercing is on. */
34
+ export declare const DEFAULT_MAX_SHADOW_DOM_DEPTH = 1;
35
+ /**
36
+ * Internal hard cap on shadow-boundary crossings. Customer-supplied
37
+ * `maxShadowDomDepth` is clamped into `[1, MAX_SHADOW_DOM_DEPTH]` — a defensive
38
+ * bound on traversal cost (and on selector length) for pathologically nested
39
+ * shadow trees, mirroring how `maxAncestorWalkDepth` guards the light-DOM walk.
40
+ */
41
+ export declare const MAX_SHADOW_DOM_DEPTH = 10;
31
42
  /**
32
43
  * Built-in defaults applied when a field is absent from the remote payload.
33
44
  * Exported so consumers (and tests) can introspect the baseline without
34
45
  * round-tripping through `resolveSelectorConfig({})`.
35
46
  */
36
- export declare const DEFAULT_RESOLVED_CONFIG: Readonly<ResolvedSelectorConfig>;
47
+ export declare const DEFAULT_RESOLVED_CONFIG: Readonly<NormalizedSelectorConfig>;
37
48
  /**
38
49
  * Resolve a (possibly partial, possibly absent) remote-config payload into a
39
50
  * fully-typed runtime config. Always returns a fresh object; never mutates the
@@ -52,5 +63,12 @@ export declare const DEFAULT_RESOLVED_CONFIG: Readonly<ResolvedSelectorConfig>;
52
63
  * - `maxAncestorWalkDepth`: positive finite integer → use as-is. Anything
53
64
  * else (zero, negative, NaN, Infinity) → `undefined` (no limit).
54
65
  */
55
- export declare function resolveSelectorConfig(remote?: ElementSelectorRemoteConfig, logger?: ElementSelectorLogger): ResolvedSelectorConfig;
66
+ /**
67
+ * Apply shadow-field defaults to a resolved config object. Callers that
68
+ * construct a `ResolvedSelectorConfig` manually (dashboard, extension, tests)
69
+ * may omit the shadow fields added after the initial API ship; the engine
70
+ * normalizes through this before reading them.
71
+ */
72
+ export declare function normalizeResolvedConfig(config: ResolvedSelectorConfig): NormalizedSelectorConfig;
73
+ export declare function resolveSelectorConfig(remote?: ElementSelectorRemoteConfig, logger?: ElementSelectorLogger): NormalizedSelectorConfig;
56
74
  //# sourceMappingURL=resolve-config.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"resolve-config.d.ts","sourceRoot":"","sources":["../../../src/config/resolve-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAOtG;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,sBAAsB,CAQnE,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,2BAA2B,EACpC,MAAM,CAAC,EAAE,qBAAqB,GAC7B,sBAAsB,CA4BxB"}
1
+ {"version":3,"file":"resolve-config.d.ts","sourceRoot":"","sources":["../../../src/config/resolve-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,UAAU,CAAC;AAOlB,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,wBAAwB,CAUrE,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,sBAAsB,GAAG,wBAAwB,CAMhG;AAED,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,2BAA2B,EACpC,MAAM,CAAC,EAAE,qBAAqB,GAC7B,wBAAwB,CAkC1B"}
@@ -27,9 +27,20 @@
27
27
  * See the design doc:
28
28
  * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
29
29
  */
30
- import { __read, __spreadArray } from "tslib";
30
+ import { __assign, __read, __spreadArray } from "tslib";
31
31
  import { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, } from '../patterns/autogenerated-ids';
32
32
  import { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns } from '../patterns/unstable-classes';
33
+ /** Shadow-DOM piercing is disabled by default, opt in via remote config. */
34
+ export var DEFAULT_SHADOW_DOM_ENABLED = false;
35
+ /** Default number of shadow-boundary crossings to traverse when piercing is on. */
36
+ export var DEFAULT_MAX_SHADOW_DOM_DEPTH = 1;
37
+ /**
38
+ * Internal hard cap on shadow-boundary crossings. Customer-supplied
39
+ * `maxShadowDomDepth` is clamped into `[1, MAX_SHADOW_DOM_DEPTH]` — a defensive
40
+ * bound on traversal cost (and on selector length) for pathologically nested
41
+ * shadow trees, mirroring how `maxAncestorWalkDepth` guards the light-DOM walk.
42
+ */
43
+ export var MAX_SHADOW_DOM_DEPTH = 10;
33
44
  /**
34
45
  * Built-in defaults applied when a field is absent from the remote payload.
35
46
  * Exported so consumers (and tests) can introspect the baseline without
@@ -43,6 +54,8 @@ export var DEFAULT_RESOLVED_CONFIG = Object.freeze({
43
54
  autogeneratedIdPatterns: __spreadArray([], __read(DEFAULT_AUTOGENERATED_ID_PATTERNS), false),
44
55
  unstableClassPatterns: __spreadArray([], __read(DEFAULT_UNSTABLE_CLASS_PATTERNS), false),
45
56
  maxAncestorWalkDepth: undefined,
57
+ shadowDomEnabled: DEFAULT_SHADOW_DOM_ENABLED,
58
+ maxShadowDomDepth: DEFAULT_MAX_SHADOW_DOM_DEPTH,
46
59
  });
47
60
  /**
48
61
  * Resolve a (possibly partial, possibly absent) remote-config payload into a
@@ -62,6 +75,16 @@ export var DEFAULT_RESOLVED_CONFIG = Object.freeze({
62
75
  * - `maxAncestorWalkDepth`: positive finite integer → use as-is. Anything
63
76
  * else (zero, negative, NaN, Infinity) → `undefined` (no limit).
64
77
  */
78
+ /**
79
+ * Apply shadow-field defaults to a resolved config object. Callers that
80
+ * construct a `ResolvedSelectorConfig` manually (dashboard, extension, tests)
81
+ * may omit the shadow fields added after the initial API ship; the engine
82
+ * normalizes through this before reading them.
83
+ */
84
+ export function normalizeResolvedConfig(config) {
85
+ var _a;
86
+ return __assign(__assign({}, config), { shadowDomEnabled: (_a = config.shadowDomEnabled) !== null && _a !== void 0 ? _a : DEFAULT_SHADOW_DOM_ENABLED, maxShadowDomDepth: clampShadowDepth(config.maxShadowDomDepth) });
87
+ }
65
88
  export function resolveSelectorConfig(remote, logger) {
66
89
  if (!remote) {
67
90
  // Return a fresh copy so callers can safely mutate the result without
@@ -82,7 +105,11 @@ export function resolveSelectorConfig(remote, logger) {
82
105
  resolved.unstableClassPatterns = compileUnstableClassPatterns(remote.unstableClassPatterns, logger);
83
106
  }
84
107
  resolved.maxAncestorWalkDepth = clampDepth(remote.maxAncestorWalkDepth);
85
- return resolved;
108
+ if (typeof remote.shadowDomEnabled === 'boolean') {
109
+ resolved.shadowDomEnabled = remote.shadowDomEnabled;
110
+ }
111
+ resolved.maxShadowDomDepth = clampShadowDepth(remote.maxShadowDomDepth);
112
+ return normalizeResolvedConfig(resolved);
86
113
  }
87
114
  /**
88
115
  * Coerce a remote-supplied depth value into the runtime contract:
@@ -98,6 +125,21 @@ function clampDepth(depth) {
98
125
  return undefined;
99
126
  return Math.floor(depth);
100
127
  }
128
+ /**
129
+ * Coerce a remote-supplied shadow depth into the runtime contract:
130
+ * - undefined / non-number / NaN / Infinity → default (1)
131
+ * - otherwise → floor()'d, then clamped into [1, MAX_SHADOW_DOM_DEPTH]
132
+ *
133
+ * Unlike `maxAncestorWalkDepth`, this never resolves to "no limit" — shadow
134
+ * piercing is always bounded by the hard cap to keep traversal and selector
135
+ * length under control.
136
+ */
137
+ function clampShadowDepth(depth) {
138
+ if (typeof depth !== 'number' || !Number.isFinite(depth)) {
139
+ return DEFAULT_MAX_SHADOW_DOM_DEPTH;
140
+ }
141
+ return Math.min(Math.max(Math.floor(depth), 1), MAX_SHADOW_DOM_DEPTH);
142
+ }
101
143
  function cloneDefaults() {
102
144
  return {
103
145
  enabled: DEFAULT_RESOLVED_CONFIG.enabled,
@@ -105,6 +147,8 @@ function cloneDefaults() {
105
147
  autogeneratedIdPatterns: __spreadArray([], __read(DEFAULT_RESOLVED_CONFIG.autogeneratedIdPatterns), false),
106
148
  unstableClassPatterns: __spreadArray([], __read(DEFAULT_RESOLVED_CONFIG.unstableClassPatterns), false),
107
149
  maxAncestorWalkDepth: DEFAULT_RESOLVED_CONFIG.maxAncestorWalkDepth,
150
+ shadowDomEnabled: DEFAULT_RESOLVED_CONFIG.shadowDomEnabled,
151
+ maxShadowDomDepth: DEFAULT_RESOLVED_CONFIG.maxShadowDomDepth,
108
152
  };
109
153
  }
110
154
  //# sourceMappingURL=resolve-config.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"resolve-config.js","sourceRoot":"","sources":["../../../src/config/resolve-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;AAGH,OAAO,EACL,iCAAiC,EACjC,OAAO,IAAI,8BAA8B,GAC1C,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,+BAA+B,EAAE,OAAO,IAAI,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAExH;;;;GAIG;AACH,MAAM,CAAC,IAAM,uBAAuB,GAAqC,MAAM,CAAC,MAAM,CAAC;IACrF,wEAAwE;IACxE,kDAAkD;IAClD,OAAO,EAAE,KAAK;IACd,yBAAyB,EAAE,mBAAmB;IAC9C,uBAAuB,2BAAM,iCAAiC,SAAC;IAC/D,qBAAqB,2BAAM,+BAA+B,SAAC;IAC3D,oBAAoB,EAAE,SAAS;CAChC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAoC,EACpC,MAA8B;IAE9B,IAAI,CAAC,MAAM,EAAE;QACX,sEAAsE;QACtE,2CAA2C;QAC3C,OAAO,aAAa,EAAE,CAAC;KACxB;IAED,IAAM,QAAQ,GAA2B,aAAa,EAAE,CAAC;IAEzD,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE;QACvC,QAAQ,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;KACnC;IAED,IAAI,OAAO,MAAM,CAAC,yBAAyB,KAAK,QAAQ,IAAI,MAAM,CAAC,yBAAyB,KAAK,EAAE,EAAE;QACnG,QAAQ,CAAC,yBAAyB,GAAG,MAAM,CAAC,yBAAyB,CAAC;KACvE;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAC,EAAE;QACjD,QAAQ,CAAC,uBAAuB,GAAG,8BAA8B,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;KAC3G;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE;QAC/C,QAAQ,CAAC,qBAAqB,GAAG,4BAA4B,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;KACrG;IAED,QAAQ,CAAC,oBAAoB,GAAG,UAAU,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAExE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAyB;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,aAAa;IACpB,OAAO;QACL,OAAO,EAAE,uBAAuB,CAAC,OAAO;QACxC,yBAAyB,EAAE,uBAAuB,CAAC,yBAAyB;QAC5E,uBAAuB,2BAAM,uBAAuB,CAAC,uBAAuB,SAAC;QAC7E,qBAAqB,2BAAM,uBAAuB,CAAC,qBAAqB,SAAC;QACzE,oBAAoB,EAAE,uBAAuB,CAAC,oBAAoB;KACnE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Config resolver — collapses the optional, string-based remote-config payload\n * into the fully-typed `ResolvedSelectorConfig` that strategies, orchestrator,\n * and fallback consume at runtime.\n *\n * Responsibilities:\n *\n * 1. Apply defaults for every field. The defaults (enabled = false,\n * attribute = `data-amp-track-id`, built-in pattern packs) match the\n * design doc's \"v1 defaults\" table.\n *\n * 2. Compile regex strings into `RegExp[]`. Bad regexes are skipped by the\n * underlying `compile` helpers; when a logger is provided it surfaces a\n * warning for each invalid pattern so customers can diagnose why their\n * override isn't taking effect.\n *\n * 3. Treat customer-provided pattern lists as a **full replacement** of the\n * defaults — not a merge. This matches the design doc: \"The customer\n * sees the defaults in the remote-config UI and may add or remove\n * patterns as needed.\" If a customer provides `autogeneratedIdPatterns:\n * []`, that's their explicit request to disable autogen filtering.\n *\n * 4. Clamp `maxAncestorWalkDepth` into a sane range. Negative / zero values\n * are coerced to `undefined` (treat as \"no limit\") rather than throwing —\n * remote config should never crash the engine.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nimport { ElementSelectorLogger, ElementSelectorRemoteConfig, ResolvedSelectorConfig } from '../types';\nimport {\n DEFAULT_AUTOGENERATED_ID_PATTERNS,\n compile as compileAutogeneratedIdPatterns,\n} from '../patterns/autogenerated-ids';\nimport { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns } from '../patterns/unstable-classes';\n\n/**\n * Built-in defaults applied when a field is absent from the remote payload.\n * Exported so consumers (and tests) can introspect the baseline without\n * round-tripping through `resolveSelectorConfig({})`.\n */\nexport const DEFAULT_RESOLVED_CONFIG: Readonly<ResolvedSelectorConfig> = Object.freeze({\n // v1 ships disabled — autocapture only flips to the new engine when the\n // remote config explicitly enables it for an org.\n enabled: false,\n explicitTrackingAttribute: 'data-amp-track-id',\n autogeneratedIdPatterns: [...DEFAULT_AUTOGENERATED_ID_PATTERNS],\n unstableClassPatterns: [...DEFAULT_UNSTABLE_CLASS_PATTERNS],\n maxAncestorWalkDepth: undefined,\n});\n\n/**\n * Resolve a (possibly partial, possibly absent) remote-config payload into a\n * fully-typed runtime config. Always returns a fresh object; never mutates the\n * input.\n *\n * Field-by-field semantics:\n *\n * - `enabled`: defaults to false (the engine ships dormant). Any boolean in\n * the payload — including `false` — wins.\n * - `explicitTrackingAttribute`: defaults to `data-amp-track-id`. Empty\n * strings are rejected (they'd make the strategy match every element);\n * fall back to the default in that case.\n * - `autogeneratedIdPatterns` / `unstableClassPatterns`: present → compile\n * the strings (skipping invalid regexes), use the compiled list as-is.\n * Absent → use the defaults.\n * - `maxAncestorWalkDepth`: positive finite integer → use as-is. Anything\n * else (zero, negative, NaN, Infinity) → `undefined` (no limit).\n */\nexport function resolveSelectorConfig(\n remote?: ElementSelectorRemoteConfig,\n logger?: ElementSelectorLogger,\n): ResolvedSelectorConfig {\n if (!remote) {\n // Return a fresh copy so callers can safely mutate the result without\n // poisoning the frozen defaults singleton.\n return cloneDefaults();\n }\n\n const resolved: ResolvedSelectorConfig = cloneDefaults();\n\n if (typeof remote.enabled === 'boolean') {\n resolved.enabled = remote.enabled;\n }\n\n if (typeof remote.explicitTrackingAttribute === 'string' && remote.explicitTrackingAttribute !== '') {\n resolved.explicitTrackingAttribute = remote.explicitTrackingAttribute;\n }\n\n if (Array.isArray(remote.autogeneratedIdPatterns)) {\n resolved.autogeneratedIdPatterns = compileAutogeneratedIdPatterns(remote.autogeneratedIdPatterns, logger);\n }\n\n if (Array.isArray(remote.unstableClassPatterns)) {\n resolved.unstableClassPatterns = compileUnstableClassPatterns(remote.unstableClassPatterns, logger);\n }\n\n resolved.maxAncestorWalkDepth = clampDepth(remote.maxAncestorWalkDepth);\n\n return resolved;\n}\n\n/**\n * Coerce a remote-supplied depth value into the runtime contract:\n * - undefined / non-number / NaN / Infinity / <= 0 → undefined (no limit)\n * - positive finite number → floor()'d integer\n */\nfunction clampDepth(depth: number | undefined): number | undefined {\n if (typeof depth !== 'number') return undefined;\n if (!Number.isFinite(depth)) return undefined;\n if (depth <= 0) return undefined;\n return Math.floor(depth);\n}\n\nfunction cloneDefaults(): ResolvedSelectorConfig {\n return {\n enabled: DEFAULT_RESOLVED_CONFIG.enabled,\n explicitTrackingAttribute: DEFAULT_RESOLVED_CONFIG.explicitTrackingAttribute,\n autogeneratedIdPatterns: [...DEFAULT_RESOLVED_CONFIG.autogeneratedIdPatterns],\n unstableClassPatterns: [...DEFAULT_RESOLVED_CONFIG.unstableClassPatterns],\n maxAncestorWalkDepth: DEFAULT_RESOLVED_CONFIG.maxAncestorWalkDepth,\n };\n}\n"]}
1
+ {"version":3,"file":"resolve-config.js","sourceRoot":"","sources":["../../../src/config/resolve-config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Config resolver — collapses the optional, string-based remote-config payload\n * into the fully-typed `ResolvedSelectorConfig` that strategies, orchestrator,\n * and fallback consume at runtime.\n *\n * Responsibilities:\n *\n * 1. Apply defaults for every field. The defaults (enabled = false,\n * attribute = `data-amp-track-id`, built-in pattern packs) match the\n * design doc's \"v1 defaults\" table.\n *\n * 2. Compile regex strings into `RegExp[]`. Bad regexes are skipped by the\n * underlying `compile` helpers; when a logger is provided it surfaces a\n * warning for each invalid pattern so customers can diagnose why their\n * override isn't taking effect.\n *\n * 3. Treat customer-provided pattern lists as a **full replacement** of the\n * defaults — not a merge. This matches the design doc: \"The customer\n * sees the defaults in the remote-config UI and may add or remove\n * patterns as needed.\" If a customer provides `autogeneratedIdPatterns:\n * []`, that's their explicit request to disable autogen filtering.\n *\n * 4. Clamp `maxAncestorWalkDepth` into a sane range. Negative / zero values\n * are coerced to `undefined` (treat as \"no limit\") rather than throwing —\n * remote config should never crash the engine.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nimport {\n ElementSelectorLogger,\n ElementSelectorRemoteConfig,\n NormalizedSelectorConfig,\n ResolvedSelectorConfig,\n} from '../types';\nimport {\n DEFAULT_AUTOGENERATED_ID_PATTERNS,\n compile as compileAutogeneratedIdPatterns,\n} from '../patterns/autogenerated-ids';\nimport { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns } from '../patterns/unstable-classes';\n\n/** Shadow-DOM piercing is disabled by default, opt in via remote config. */\nexport const DEFAULT_SHADOW_DOM_ENABLED = false;\n\n/** Default number of shadow-boundary crossings to traverse when piercing is on. */\nexport const DEFAULT_MAX_SHADOW_DOM_DEPTH = 1;\n\n/**\n * Internal hard cap on shadow-boundary crossings. Customer-supplied\n * `maxShadowDomDepth` is clamped into `[1, MAX_SHADOW_DOM_DEPTH]` — a defensive\n * bound on traversal cost (and on selector length) for pathologically nested\n * shadow trees, mirroring how `maxAncestorWalkDepth` guards the light-DOM walk.\n */\nexport const MAX_SHADOW_DOM_DEPTH = 10;\n\n/**\n * Built-in defaults applied when a field is absent from the remote payload.\n * Exported so consumers (and tests) can introspect the baseline without\n * round-tripping through `resolveSelectorConfig({})`.\n */\nexport const DEFAULT_RESOLVED_CONFIG: Readonly<NormalizedSelectorConfig> = Object.freeze({\n // v1 ships disabled — autocapture only flips to the new engine when the\n // remote config explicitly enables it for an org.\n enabled: false,\n explicitTrackingAttribute: 'data-amp-track-id',\n autogeneratedIdPatterns: [...DEFAULT_AUTOGENERATED_ID_PATTERNS],\n unstableClassPatterns: [...DEFAULT_UNSTABLE_CLASS_PATTERNS],\n maxAncestorWalkDepth: undefined,\n shadowDomEnabled: DEFAULT_SHADOW_DOM_ENABLED,\n maxShadowDomDepth: DEFAULT_MAX_SHADOW_DOM_DEPTH,\n});\n\n/**\n * Resolve a (possibly partial, possibly absent) remote-config payload into a\n * fully-typed runtime config. Always returns a fresh object; never mutates the\n * input.\n *\n * Field-by-field semantics:\n *\n * - `enabled`: defaults to false (the engine ships dormant). Any boolean in\n * the payload — including `false` — wins.\n * - `explicitTrackingAttribute`: defaults to `data-amp-track-id`. Empty\n * strings are rejected (they'd make the strategy match every element);\n * fall back to the default in that case.\n * - `autogeneratedIdPatterns` / `unstableClassPatterns`: present → compile\n * the strings (skipping invalid regexes), use the compiled list as-is.\n * Absent → use the defaults.\n * - `maxAncestorWalkDepth`: positive finite integer → use as-is. Anything\n * else (zero, negative, NaN, Infinity) → `undefined` (no limit).\n */\n/**\n * Apply shadow-field defaults to a resolved config object. Callers that\n * construct a `ResolvedSelectorConfig` manually (dashboard, extension, tests)\n * may omit the shadow fields added after the initial API ship; the engine\n * normalizes through this before reading them.\n */\nexport function normalizeResolvedConfig(config: ResolvedSelectorConfig): NormalizedSelectorConfig {\n return {\n ...config,\n shadowDomEnabled: config.shadowDomEnabled ?? DEFAULT_SHADOW_DOM_ENABLED,\n maxShadowDomDepth: clampShadowDepth(config.maxShadowDomDepth),\n };\n}\n\nexport function resolveSelectorConfig(\n remote?: ElementSelectorRemoteConfig,\n logger?: ElementSelectorLogger,\n): NormalizedSelectorConfig {\n if (!remote) {\n // Return a fresh copy so callers can safely mutate the result without\n // poisoning the frozen defaults singleton.\n return cloneDefaults();\n }\n\n const resolved: NormalizedSelectorConfig = cloneDefaults();\n\n if (typeof remote.enabled === 'boolean') {\n resolved.enabled = remote.enabled;\n }\n\n if (typeof remote.explicitTrackingAttribute === 'string' && remote.explicitTrackingAttribute !== '') {\n resolved.explicitTrackingAttribute = remote.explicitTrackingAttribute;\n }\n\n if (Array.isArray(remote.autogeneratedIdPatterns)) {\n resolved.autogeneratedIdPatterns = compileAutogeneratedIdPatterns(remote.autogeneratedIdPatterns, logger);\n }\n\n if (Array.isArray(remote.unstableClassPatterns)) {\n resolved.unstableClassPatterns = compileUnstableClassPatterns(remote.unstableClassPatterns, logger);\n }\n\n resolved.maxAncestorWalkDepth = clampDepth(remote.maxAncestorWalkDepth);\n\n if (typeof remote.shadowDomEnabled === 'boolean') {\n resolved.shadowDomEnabled = remote.shadowDomEnabled;\n }\n\n resolved.maxShadowDomDepth = clampShadowDepth(remote.maxShadowDomDepth);\n\n return normalizeResolvedConfig(resolved);\n}\n\n/**\n * Coerce a remote-supplied depth value into the runtime contract:\n * - undefined / non-number / NaN / Infinity / <= 0 → undefined (no limit)\n * - positive finite number → floor()'d integer\n */\nfunction clampDepth(depth: number | undefined): number | undefined {\n if (typeof depth !== 'number') return undefined;\n if (!Number.isFinite(depth)) return undefined;\n if (depth <= 0) return undefined;\n return Math.floor(depth);\n}\n\n/**\n * Coerce a remote-supplied shadow depth into the runtime contract:\n * - undefined / non-number / NaN / Infinity → default (1)\n * - otherwise → floor()'d, then clamped into [1, MAX_SHADOW_DOM_DEPTH]\n *\n * Unlike `maxAncestorWalkDepth`, this never resolves to \"no limit\" — shadow\n * piercing is always bounded by the hard cap to keep traversal and selector\n * length under control.\n */\nfunction clampShadowDepth(depth: number | undefined): number {\n if (typeof depth !== 'number' || !Number.isFinite(depth)) {\n return DEFAULT_MAX_SHADOW_DOM_DEPTH;\n }\n return Math.min(Math.max(Math.floor(depth), 1), MAX_SHADOW_DOM_DEPTH);\n}\n\nfunction cloneDefaults(): NormalizedSelectorConfig {\n return {\n enabled: DEFAULT_RESOLVED_CONFIG.enabled,\n explicitTrackingAttribute: DEFAULT_RESOLVED_CONFIG.explicitTrackingAttribute,\n autogeneratedIdPatterns: [...DEFAULT_RESOLVED_CONFIG.autogeneratedIdPatterns],\n unstableClassPatterns: [...DEFAULT_RESOLVED_CONFIG.unstableClassPatterns],\n maxAncestorWalkDepth: DEFAULT_RESOLVED_CONFIG.maxAncestorWalkDepth,\n shadowDomEnabled: DEFAULT_RESOLVED_CONFIG.shadowDomEnabled,\n maxShadowDomDepth: DEFAULT_RESOLVED_CONFIG.maxShadowDomDepth,\n };\n}\n"]}
@@ -1 +1 @@
1
- {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EAAmB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAItE,MAAM,WAAW,2BAA2B;IAC1C,gHAAgH;IAChH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,sBAAsB,EACrC,OAAO,GAAE,2BAAgC,GACxC,cAAc,CAqEhB"}
1
+ {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,qBAAqB,EAA4B,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAClH,OAAO,EAAmB,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAkBtE,MAAM,WAAW,2BAA2B;IAC1C,gHAAgH;IAChH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,sBAAsB,EACrC,OAAO,GAAE,2BAAgC,GACxC,cAAc,CAwGhB"}