@amplitude/element-selector 0.0.1 → 0.1.1-featelement-selector-v1.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 (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +162 -0
  3. package/lib/cjs/config/resolve-config.d.ts +56 -0
  4. package/lib/cjs/config/resolve-config.d.ts.map +1 -0
  5. package/lib/cjs/config/resolve-config.js +114 -0
  6. package/lib/cjs/config/resolve-config.js.map +1 -0
  7. package/lib/cjs/engine.d.ts +54 -0
  8. package/lib/cjs/engine.d.ts.map +1 -0
  9. package/lib/cjs/engine.js +139 -0
  10. package/lib/cjs/engine.js.map +1 -0
  11. package/lib/cjs/fallback-css-path.d.ts +53 -0
  12. package/lib/cjs/fallback-css-path.d.ts.map +1 -0
  13. package/lib/cjs/fallback-css-path.js +124 -0
  14. package/lib/cjs/fallback-css-path.js.map +1 -0
  15. package/lib/cjs/generate-selector.d.ts +54 -0
  16. package/lib/cjs/generate-selector.d.ts.map +1 -0
  17. package/lib/cjs/generate-selector.js +76 -0
  18. package/lib/cjs/generate-selector.js.map +1 -0
  19. package/lib/cjs/helpers/describe-relative.d.ts +28 -0
  20. package/lib/cjs/helpers/describe-relative.d.ts.map +1 -0
  21. package/lib/cjs/helpers/describe-relative.js +60 -0
  22. package/lib/cjs/helpers/describe-relative.js.map +1 -0
  23. package/lib/cjs/helpers/escape-css-identifier.d.ts +8 -0
  24. package/lib/cjs/helpers/escape-css-identifier.d.ts.map +1 -0
  25. package/lib/cjs/helpers/escape-css-identifier.js +50 -0
  26. package/lib/cjs/helpers/escape-css-identifier.js.map +1 -0
  27. package/lib/cjs/helpers/escape-id.d.ts +3 -0
  28. package/lib/cjs/helpers/escape-id.d.ts.map +1 -0
  29. package/lib/cjs/helpers/escape-id.js +10 -0
  30. package/lib/cjs/helpers/escape-id.js.map +1 -0
  31. package/lib/cjs/helpers/get-stable-id.d.ts +23 -0
  32. package/lib/cjs/helpers/get-stable-id.d.ts.map +1 -0
  33. package/lib/cjs/helpers/get-stable-id.js +44 -0
  34. package/lib/cjs/helpers/get-stable-id.js.map +1 -0
  35. package/lib/cjs/index.d.ts +31 -0
  36. package/lib/cjs/index.d.ts.map +1 -0
  37. package/lib/cjs/index.js +71 -0
  38. package/lib/cjs/index.js.map +1 -0
  39. package/lib/cjs/legacy-css-path.d.ts +84 -0
  40. package/lib/cjs/legacy-css-path.d.ts.map +1 -0
  41. package/lib/cjs/legacy-css-path.js +230 -0
  42. package/lib/cjs/legacy-css-path.js.map +1 -0
  43. package/lib/cjs/orchestrator.d.ts +61 -0
  44. package/lib/cjs/orchestrator.d.ts.map +1 -0
  45. package/lib/cjs/orchestrator.js +140 -0
  46. package/lib/cjs/orchestrator.js.map +1 -0
  47. package/lib/cjs/patterns/autogenerated-ids.d.ts +37 -0
  48. package/lib/cjs/patterns/autogenerated-ids.d.ts.map +1 -0
  49. package/lib/cjs/patterns/autogenerated-ids.js +102 -0
  50. package/lib/cjs/patterns/autogenerated-ids.js.map +1 -0
  51. package/lib/cjs/patterns/unstable-classes.d.ts +48 -0
  52. package/lib/cjs/patterns/unstable-classes.d.ts.map +1 -0
  53. package/lib/cjs/patterns/unstable-classes.js +155 -0
  54. package/lib/cjs/patterns/unstable-classes.js.map +1 -0
  55. package/lib/cjs/strategies/explicit-tracking-attribute.d.ts +22 -0
  56. package/lib/cjs/strategies/explicit-tracking-attribute.d.ts.map +1 -0
  57. package/lib/cjs/strategies/explicit-tracking-attribute.js +36 -0
  58. package/lib/cjs/strategies/explicit-tracking-attribute.js.map +1 -0
  59. package/lib/cjs/strategies/stable-id.d.ts +14 -0
  60. package/lib/cjs/strategies/stable-id.d.ts.map +1 -0
  61. package/lib/cjs/strategies/stable-id.js +27 -0
  62. package/lib/cjs/strategies/stable-id.js.map +1 -0
  63. package/lib/cjs/types.d.ts +100 -0
  64. package/lib/cjs/types.d.ts.map +1 -0
  65. package/lib/cjs/types.js +13 -0
  66. package/lib/cjs/types.js.map +1 -0
  67. package/lib/esm/config/resolve-config.d.ts +56 -0
  68. package/lib/esm/config/resolve-config.d.ts.map +1 -0
  69. package/lib/esm/config/resolve-config.js +110 -0
  70. package/lib/esm/config/resolve-config.js.map +1 -0
  71. package/lib/esm/engine.d.ts +54 -0
  72. package/lib/esm/engine.d.ts.map +1 -0
  73. package/lib/esm/engine.js +135 -0
  74. package/lib/esm/engine.js.map +1 -0
  75. package/lib/esm/fallback-css-path.d.ts +53 -0
  76. package/lib/esm/fallback-css-path.d.ts.map +1 -0
  77. package/lib/esm/fallback-css-path.js +120 -0
  78. package/lib/esm/fallback-css-path.js.map +1 -0
  79. package/lib/esm/generate-selector.d.ts +54 -0
  80. package/lib/esm/generate-selector.d.ts.map +1 -0
  81. package/lib/esm/generate-selector.js +72 -0
  82. package/lib/esm/generate-selector.js.map +1 -0
  83. package/lib/esm/helpers/describe-relative.d.ts +28 -0
  84. package/lib/esm/helpers/describe-relative.d.ts.map +1 -0
  85. package/lib/esm/helpers/describe-relative.js +56 -0
  86. package/lib/esm/helpers/describe-relative.js.map +1 -0
  87. package/lib/esm/helpers/escape-css-identifier.d.ts +8 -0
  88. package/lib/esm/helpers/escape-css-identifier.d.ts.map +1 -0
  89. package/lib/esm/helpers/escape-css-identifier.js +46 -0
  90. package/lib/esm/helpers/escape-css-identifier.js.map +1 -0
  91. package/lib/esm/helpers/escape-id.d.ts +3 -0
  92. package/lib/esm/helpers/escape-id.d.ts.map +1 -0
  93. package/lib/esm/helpers/escape-id.js +6 -0
  94. package/lib/esm/helpers/escape-id.js.map +1 -0
  95. package/lib/esm/helpers/get-stable-id.d.ts +23 -0
  96. package/lib/esm/helpers/get-stable-id.d.ts.map +1 -0
  97. package/lib/esm/helpers/get-stable-id.js +40 -0
  98. package/lib/esm/helpers/get-stable-id.js.map +1 -0
  99. package/lib/esm/index.d.ts +31 -0
  100. package/lib/esm/index.d.ts.map +1 -0
  101. package/lib/esm/index.js +50 -0
  102. package/lib/esm/index.js.map +1 -0
  103. package/lib/esm/legacy-css-path.d.ts +84 -0
  104. package/lib/esm/legacy-css-path.d.ts.map +1 -0
  105. package/lib/esm/legacy-css-path.js +226 -0
  106. package/lib/esm/legacy-css-path.js.map +1 -0
  107. package/lib/esm/orchestrator.d.ts +61 -0
  108. package/lib/esm/orchestrator.d.ts.map +1 -0
  109. package/lib/esm/orchestrator.js +136 -0
  110. package/lib/esm/orchestrator.js.map +1 -0
  111. package/lib/esm/patterns/autogenerated-ids.d.ts +37 -0
  112. package/lib/esm/patterns/autogenerated-ids.d.ts.map +1 -0
  113. package/lib/esm/patterns/autogenerated-ids.js +97 -0
  114. package/lib/esm/patterns/autogenerated-ids.js.map +1 -0
  115. package/lib/esm/patterns/unstable-classes.d.ts +48 -0
  116. package/lib/esm/patterns/unstable-classes.d.ts.map +1 -0
  117. package/lib/esm/patterns/unstable-classes.js +150 -0
  118. package/lib/esm/patterns/unstable-classes.js.map +1 -0
  119. package/lib/esm/strategies/explicit-tracking-attribute.d.ts +22 -0
  120. package/lib/esm/strategies/explicit-tracking-attribute.d.ts.map +1 -0
  121. package/lib/esm/strategies/explicit-tracking-attribute.js +33 -0
  122. package/lib/esm/strategies/explicit-tracking-attribute.js.map +1 -0
  123. package/lib/esm/strategies/stable-id.d.ts +14 -0
  124. package/lib/esm/strategies/stable-id.d.ts.map +1 -0
  125. package/lib/esm/strategies/stable-id.js +24 -0
  126. package/lib/esm/strategies/stable-id.js.map +1 -0
  127. package/lib/esm/types.d.ts +100 -0
  128. package/lib/esm/types.d.ts.map +1 -0
  129. package/lib/esm/types.js +12 -0
  130. package/lib/esm/types.js.map +1 -0
  131. package/package.json +40 -5
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Top-level chokepoint for "generate a selector for this element."
3
+ *
4
+ * Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard
5
+ * (`session-replay-ui`) used to maintain their own copy of this routing logic:
6
+ *
7
+ * if (config.enabled && engine) return engine.generate(el);
8
+ * else return cssPath(el, false);
9
+ *
10
+ * Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon
11
+ * as we considered a third consumer (Chrome extension visual tagger, future
12
+ * tagging surfaces) the duplication became untenable — bug fixes had to land
13
+ * three places and the kill-switch semantics could drift between them.
14
+ *
15
+ * Moving the kill switch inside `engine.generate` covered the "engine present"
16
+ * case. This helper covers the remaining "engine is null" case that some
17
+ * consumers genuinely have:
18
+ *
19
+ * - dashboard's `useElementSelectorEngineContext()` returns
20
+ * `{ engine: null }` when no provider is mounted (tests, content-renderer
21
+ * paths, future call sites outside the canonical mount tree).
22
+ * - Chrome extension boots before the customer's SDK has stood up an engine
23
+ * on the page; reads `null` from `window.amplitude.elementSelector` until
24
+ * the SDK init finishes.
25
+ *
26
+ * In those cases, callers want the legacy `cssPath` selector — same shape the
27
+ * SDK is emitting in production for orgs without the engine. This helper makes
28
+ * that explicit and centralizes the rule so future consumers don't reinvent
29
+ * it.
30
+ */
31
+ import { ResolvedSelectorConfig, SelectorEngine } from './types';
32
+ /**
33
+ * Generate a selector for `el`, transparently routing to the legacy
34
+ * `cssPath` walker when no engine is available.
35
+ *
36
+ * Why this signature (engine + config separately, rather than just engine):
37
+ * the dashboard's inert context has `engine: null` but still carries a
38
+ * resolved config. Both `null`-engine and engine-with-`enabled: false`
39
+ * collapse to "legacy `cssPath`", and we want the same one-line call site
40
+ * to handle both. When the engine *is* present, this just delegates — the
41
+ * engine's own kill switch handles `enabled === false`.
42
+ *
43
+ * Never throws. Returns the empty string in the pathological case where the
44
+ * legacy walker itself can't produce one (non-element nodes; environments
45
+ * missing `CSS.escape`).
46
+ *
47
+ * @param el DOM element to identify.
48
+ * @param engine Live `SelectorEngine`, or `null` when no engine is mounted.
49
+ * @param config Resolved selector config. Only consulted in the null-engine
50
+ * branch; when `engine` is present, the engine consults its
51
+ * own internal config.
52
+ */
53
+ export declare const generateSelector: (el: Element, engine: SelectorEngine | null, config: ResolvedSelectorConfig) => string;
54
+ //# sourceMappingURL=generate-selector.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-selector.d.ts","sourceRoot":"","sources":["../../src/generate-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,OACvB,OAAO,UACH,cAAc,GAAG,IAAI,UACrB,sBAAsB,KAC7B,MAiBF,CAAC"}
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Top-level chokepoint for "generate a selector for this element."
3
+ *
4
+ * Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard
5
+ * (`session-replay-ui`) used to maintain their own copy of this routing logic:
6
+ *
7
+ * if (config.enabled && engine) return engine.generate(el);
8
+ * else return cssPath(el, false);
9
+ *
10
+ * Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon
11
+ * as we considered a third consumer (Chrome extension visual tagger, future
12
+ * tagging surfaces) the duplication became untenable — bug fixes had to land
13
+ * three places and the kill-switch semantics could drift between them.
14
+ *
15
+ * Moving the kill switch inside `engine.generate` covered the "engine present"
16
+ * case. This helper covers the remaining "engine is null" case that some
17
+ * consumers genuinely have:
18
+ *
19
+ * - dashboard's `useElementSelectorEngineContext()` returns
20
+ * `{ engine: null }` when no provider is mounted (tests, content-renderer
21
+ * paths, future call sites outside the canonical mount tree).
22
+ * - Chrome extension boots before the customer's SDK has stood up an engine
23
+ * on the page; reads `null` from `window.amplitude.elementSelector` until
24
+ * the SDK init finishes.
25
+ *
26
+ * In those cases, callers want the legacy `cssPath` selector — same shape the
27
+ * SDK is emitting in production for orgs without the engine. This helper makes
28
+ * that explicit and centralizes the rule so future consumers don't reinvent
29
+ * it.
30
+ */
31
+ import { legacyCssPath } from './legacy-css-path';
32
+ /**
33
+ * Generate a selector for `el`, transparently routing to the legacy
34
+ * `cssPath` walker when no engine is available.
35
+ *
36
+ * Why this signature (engine + config separately, rather than just engine):
37
+ * the dashboard's inert context has `engine: null` but still carries a
38
+ * resolved config. Both `null`-engine and engine-with-`enabled: false`
39
+ * collapse to "legacy `cssPath`", and we want the same one-line call site
40
+ * to handle both. When the engine *is* present, this just delegates — the
41
+ * engine's own kill switch handles `enabled === false`.
42
+ *
43
+ * Never throws. Returns the empty string in the pathological case where the
44
+ * legacy walker itself can't produce one (non-element nodes; environments
45
+ * missing `CSS.escape`).
46
+ *
47
+ * @param el DOM element to identify.
48
+ * @param engine Live `SelectorEngine`, or `null` when no engine is mounted.
49
+ * @param config Resolved selector config. Only consulted in the null-engine
50
+ * branch; when `engine` is present, the engine consults its
51
+ * own internal config.
52
+ */
53
+ export var generateSelector = function (el, engine, config) {
54
+ if (engine) {
55
+ // The engine has its own kill switch (`config.enabled === false` →
56
+ // legacy cssPath) and its own try/catch safety net. Trust it.
57
+ return engine.generate(el);
58
+ }
59
+ // Engine-null branch. We don't have a live engine to consult, so we route
60
+ // straight to the legacy walker — the same selector the SDK would be
61
+ // emitting if `config.enabled === false`. `config` is accepted for symmetry
62
+ // with the engine signature and so future versions can extend behavior
63
+ // without a breaking change.
64
+ void config;
65
+ try {
66
+ return legacyCssPath(el);
67
+ }
68
+ catch (_a) {
69
+ return '';
70
+ }
71
+ };
72
+ //# sourceMappingURL=generate-selector.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-selector.js","sourceRoot":"","sources":["../../src/generate-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,IAAM,gBAAgB,GAAG,UAC9B,EAAW,EACX,MAA6B,EAC7B,MAA8B;IAE9B,IAAI,MAAM,EAAE;QACV,mEAAmE;QACnE,8DAA8D;QAC9D,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;KAC5B;IACD,0EAA0E;IAC1E,qEAAqE;IACrE,4EAA4E;IAC5E,uEAAuE;IACvE,6BAA6B;IAC7B,KAAK,MAAM,CAAC;IACZ,IAAI;QACF,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC;KAC1B;IAAC,WAAM;QACN,OAAO,EAAE,CAAC;KACX;AACH,CAAC,CAAC","sourcesContent":["/**\n * Top-level chokepoint for \"generate a selector for this element.\"\n *\n * Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard\n * (`session-replay-ui`) used to maintain their own copy of this routing logic:\n *\n * if (config.enabled && engine) return engine.generate(el);\n * else return cssPath(el, false);\n *\n * Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon\n * as we considered a third consumer (Chrome extension visual tagger, future\n * tagging surfaces) the duplication became untenable — bug fixes had to land\n * three places and the kill-switch semantics could drift between them.\n *\n * Moving the kill switch inside `engine.generate` covered the \"engine present\"\n * case. This helper covers the remaining \"engine is null\" case that some\n * consumers genuinely have:\n *\n * - dashboard's `useElementSelectorEngineContext()` returns\n * `{ engine: null }` when no provider is mounted (tests, content-renderer\n * paths, future call sites outside the canonical mount tree).\n * - Chrome extension boots before the customer's SDK has stood up an engine\n * on the page; reads `null` from `window.amplitude.elementSelector` until\n * the SDK init finishes.\n *\n * In those cases, callers want the legacy `cssPath` selector — same shape the\n * SDK is emitting in production for orgs without the engine. This helper makes\n * that explicit and centralizes the rule so future consumers don't reinvent\n * it.\n */\n\nimport { ResolvedSelectorConfig, SelectorEngine } from './types';\nimport { legacyCssPath } from './legacy-css-path';\n\n/**\n * Generate a selector for `el`, transparently routing to the legacy\n * `cssPath` walker when no engine is available.\n *\n * Why this signature (engine + config separately, rather than just engine):\n * the dashboard's inert context has `engine: null` but still carries a\n * resolved config. Both `null`-engine and engine-with-`enabled: false`\n * collapse to \"legacy `cssPath`\", and we want the same one-line call site\n * to handle both. When the engine *is* present, this just delegates — the\n * engine's own kill switch handles `enabled === false`.\n *\n * Never throws. Returns the empty string in the pathological case where the\n * legacy walker itself can't produce one (non-element nodes; environments\n * missing `CSS.escape`).\n *\n * @param el DOM element to identify.\n * @param engine Live `SelectorEngine`, or `null` when no engine is mounted.\n * @param config Resolved selector config. Only consulted in the null-engine\n * branch; when `engine` is present, the engine consults its\n * own internal config.\n */\nexport const generateSelector = (\n el: Element,\n engine: SelectorEngine | null,\n config: ResolvedSelectorConfig,\n): string => {\n if (engine) {\n // The engine has its own kill switch (`config.enabled === false` →\n // legacy cssPath) and its own try/catch safety net. Trust it.\n return engine.generate(el);\n }\n // Engine-null branch. We don't have a live engine to consult, so we route\n // straight to the legacy walker — the same selector the SDK would be\n // emitting if `config.enabled === false`. `config` is accepted for symmetry\n // with the engine signature and so future versions can extend behavior\n // without a breaking change.\n void config;\n try {\n return legacyCssPath(el);\n } catch {\n return '';\n }\n};\n"]}
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Positional descent builder.
3
+ *
4
+ * Given an anchor element (the result of pass 2's walk in the orchestration PR)
5
+ * and the trail of intermediate elements between the anchor and the original
6
+ * click target, produce the CSS-selector descent string. Each step in the
7
+ * descent uses `tag:nth-of-type(n)` so the resulting selector resolves
8
+ * unambiguously to the original target regardless of class-state churn.
9
+ *
10
+ * Matches ContentSquare's "position within identical markers" convention.
11
+ *
12
+ * Example:
13
+ *
14
+ * describeRelative(anchor, [<section>, <ul>, <li>])
15
+ * → "section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
16
+ *
17
+ * Combined with the anchor selector (`anchor#some-id`) by the orchestrator:
18
+ *
19
+ * "anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
20
+ *
21
+ * The `anchor` parameter is accepted for symmetry with the orchestrator's call
22
+ * site but isn't currently used — the function only needs each trail element's
23
+ * own parent context. We keep the signature so subsequent work can reference
24
+ * the anchor when extending the descent format (e.g., to optimize bare
25
+ * `:nth-of-type(1)` away when there's only one of that type).
26
+ */
27
+ export declare function describeRelative(_anchor: Element, trail: Element[]): string;
28
+ //# sourceMappingURL=describe-relative.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"describe-relative.d.ts","sourceRoot":"","sources":["../../../src/helpers/describe-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAE3E"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Positional descent builder.
3
+ *
4
+ * Given an anchor element (the result of pass 2's walk in the orchestration PR)
5
+ * and the trail of intermediate elements between the anchor and the original
6
+ * click target, produce the CSS-selector descent string. Each step in the
7
+ * descent uses `tag:nth-of-type(n)` so the resulting selector resolves
8
+ * unambiguously to the original target regardless of class-state churn.
9
+ *
10
+ * Matches ContentSquare's "position within identical markers" convention.
11
+ *
12
+ * Example:
13
+ *
14
+ * describeRelative(anchor, [<section>, <ul>, <li>])
15
+ * → "section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
16
+ *
17
+ * Combined with the anchor selector (`anchor#some-id`) by the orchestrator:
18
+ *
19
+ * "anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
20
+ *
21
+ * The `anchor` parameter is accepted for symmetry with the orchestrator's call
22
+ * site but isn't currently used — the function only needs each trail element's
23
+ * own parent context. We keep the signature so subsequent work can reference
24
+ * the anchor when extending the descent format (e.g., to optimize bare
25
+ * `:nth-of-type(1)` away when there's only one of that type).
26
+ */
27
+ export function describeRelative(_anchor, trail) {
28
+ return trail.map(stepFor).join(' > ');
29
+ }
30
+ function stepFor(el) {
31
+ var tag = el.tagName.toLowerCase();
32
+ var parent = el.parentElement;
33
+ if (parent === null) {
34
+ // Detached element or root — emit just the tag. The orchestrator shouldn't
35
+ // call us with a detached trail, but we don't want to crash if it does.
36
+ return tag;
37
+ }
38
+ var index = sameTypeIndex(el, parent);
39
+ return "".concat(tag, ":nth-of-type(").concat(index, ")");
40
+ }
41
+ function sameTypeIndex(el, parent) {
42
+ // 1-based index among same-tag element siblings, mirroring :nth-of-type semantics.
43
+ var count = 0;
44
+ for (var i = 0; i < parent.children.length; i++) {
45
+ var sibling = parent.children[i];
46
+ if (sibling.tagName === el.tagName) {
47
+ count += 1;
48
+ if (sibling === el)
49
+ return count;
50
+ }
51
+ }
52
+ // Element wasn't found among its parent's children — shouldn't happen for a
53
+ // live element. Return 1 as a defensive fallback rather than throwing.
54
+ return 1;
55
+ }
56
+ //# sourceMappingURL=describe-relative.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"describe-relative.js","sourceRoot":"","sources":["../../../src/helpers/describe-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAgB;IACjE,OAAO,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,OAAO,CAAC,EAAW;IAC1B,IAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IACrC,IAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC;IAChC,IAAI,MAAM,KAAK,IAAI,EAAE;QACnB,2EAA2E;QAC3E,wEAAwE;QACxE,OAAO,GAAG,CAAC;KACZ;IACD,IAAM,KAAK,GAAG,aAAa,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,UAAG,GAAG,0BAAgB,KAAK,MAAG,CAAC;AACxC,CAAC;AAED,SAAS,aAAa,CAAC,EAAW,EAAE,MAAe;IACjD,mFAAmF;IACnF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QAC/C,IAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,EAAE;YAClC,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,OAAO,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;SAClC;KACF;IACD,4EAA4E;IAC5E,uEAAuE;IACvE,OAAO,CAAC,CAAC;AACX,CAAC","sourcesContent":["/**\n * Positional descent builder.\n *\n * Given an anchor element (the result of pass 2's walk in the orchestration PR)\n * and the trail of intermediate elements between the anchor and the original\n * click target, produce the CSS-selector descent string. Each step in the\n * descent uses `tag:nth-of-type(n)` so the resulting selector resolves\n * unambiguously to the original target regardless of class-state churn.\n *\n * Matches ContentSquare's \"position within identical markers\" convention.\n *\n * Example:\n *\n * describeRelative(anchor, [<section>, <ul>, <li>])\n * → \"section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)\"\n *\n * Combined with the anchor selector (`anchor#some-id`) by the orchestrator:\n *\n * \"anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)\"\n *\n * The `anchor` parameter is accepted for symmetry with the orchestrator's call\n * site but isn't currently used — the function only needs each trail element's\n * own parent context. We keep the signature so subsequent work can reference\n * the anchor when extending the descent format (e.g., to optimize bare\n * `:nth-of-type(1)` away when there's only one of that type).\n */\nexport function describeRelative(_anchor: Element, trail: Element[]): string {\n return trail.map(stepFor).join(' > ');\n}\n\nfunction stepFor(el: Element): string {\n const tag = el.tagName.toLowerCase();\n const parent = el.parentElement;\n if (parent === null) {\n // Detached element or root — emit just the tag. The orchestrator shouldn't\n // call us with a detached trail, but we don't want to crash if it does.\n return tag;\n }\n const index = sameTypeIndex(el, parent);\n return `${tag}:nth-of-type(${index})`;\n}\n\nfunction sameTypeIndex(el: Element, parent: Element): number {\n // 1-based index among same-tag element siblings, mirroring :nth-of-type semantics.\n let count = 0;\n for (let i = 0; i < parent.children.length; i++) {\n const sibling = parent.children[i];\n if (sibling.tagName === el.tagName) {\n count += 1;\n if (sibling === el) return count;\n }\n }\n // Element wasn't found among its parent's children — shouldn't happen for a\n // live element. Return 1 as a defensive fallback rather than throwing.\n return 1;\n}\n"]}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Escape a string for use as a CSS identifier.
3
+ *
4
+ * Uses the native CSS.escape implementation when available, with the CSSOM
5
+ * algorithm inlined for runtimes that do not expose it (notably jsdom).
6
+ */
7
+ export declare function escapeCssIdentifier(value: string): string;
8
+ //# sourceMappingURL=escape-css-identifier.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escape-css-identifier.d.ts","sourceRoot":"","sources":["../../../src/helpers/escape-css-identifier.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiDzD"}
@@ -0,0 +1,46 @@
1
+ /* eslint-disable no-restricted-globals */
2
+ /**
3
+ * Escape a string for use as a CSS identifier.
4
+ *
5
+ * Uses the native CSS.escape implementation when available, with the CSSOM
6
+ * algorithm inlined for runtimes that do not expose it (notably jsdom).
7
+ */
8
+ export function escapeCssIdentifier(value) {
9
+ var css = globalThis.CSS;
10
+ if (css && typeof css.escape === 'function') {
11
+ return css.escape(value);
12
+ }
13
+ var string = String(value);
14
+ var length = string.length;
15
+ var result = '';
16
+ for (var index = 0; index < length; index++) {
17
+ var codeUnit = string.charCodeAt(index);
18
+ if (codeUnit === 0x0000) {
19
+ result += '\uFFFD';
20
+ continue;
21
+ }
22
+ if ((codeUnit >= 0x0001 && codeUnit <= 0x001f) ||
23
+ codeUnit === 0x007f ||
24
+ (index === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
25
+ (index === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && string.charCodeAt(0) === 0x002d)) {
26
+ result += "\\".concat(codeUnit.toString(16), " ");
27
+ continue;
28
+ }
29
+ if (index === 0 && length === 1 && codeUnit === 0x002d) {
30
+ result += '\\-';
31
+ continue;
32
+ }
33
+ if (codeUnit >= 0x0080 ||
34
+ codeUnit === 0x002d ||
35
+ codeUnit === 0x005f ||
36
+ (codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
37
+ (codeUnit >= 0x0041 && codeUnit <= 0x005a) ||
38
+ (codeUnit >= 0x0061 && codeUnit <= 0x007a)) {
39
+ result += string.charAt(index);
40
+ continue;
41
+ }
42
+ result += "\\".concat(string.charAt(index));
43
+ }
44
+ return result;
45
+ }
46
+ //# sourceMappingURL=escape-css-identifier.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escape-css-identifier.js","sourceRoot":"","sources":["../../../src/helpers/escape-css-identifier.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAQ1C;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAM,GAAG,GAAI,UAA8B,CAAC,GAAG,CAAC;IAChD,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE;QAC3C,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC1B;IAED,IAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;QAC3C,IAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAE1C,IAAI,QAAQ,KAAK,MAAM,EAAE;YACvB,MAAM,IAAI,QAAQ,CAAC;YACnB,SAAS;SACV;QAED,IACE,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,QAAQ,KAAK,MAAM;YACnB,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YACzD,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,EAC5F;YACA,MAAM,IAAI,YAAK,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAG,CAAC;YACxC,SAAS;SACV;QAED,IAAI,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,QAAQ,KAAK,MAAM,EAAE;YACtD,MAAM,IAAI,KAAK,CAAC;YAChB,SAAS;SACV;QAED,IACE,QAAQ,IAAI,MAAM;YAClB,QAAQ,KAAK,MAAM;YACnB,QAAQ,KAAK,MAAM;YACnB,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC,EAC1C;YACA,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,SAAS;SACV;QAED,MAAM,IAAI,YAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAE,CAAC;KACvC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/* eslint-disable no-restricted-globals */\n\ntype CssEscapeGlobal = {\n CSS?: {\n escape?: (value: string) => string;\n };\n};\n\n/**\n * Escape a string for use as a CSS identifier.\n *\n * Uses the native CSS.escape implementation when available, with the CSSOM\n * algorithm inlined for runtimes that do not expose it (notably jsdom).\n */\nexport function escapeCssIdentifier(value: string): string {\n const css = (globalThis as CssEscapeGlobal).CSS;\n if (css && typeof css.escape === 'function') {\n return css.escape(value);\n }\n\n const string = String(value);\n const length = string.length;\n let result = '';\n\n for (let index = 0; index < length; index++) {\n const codeUnit = string.charCodeAt(index);\n\n if (codeUnit === 0x0000) {\n result += '\\uFFFD';\n continue;\n }\n\n if (\n (codeUnit >= 0x0001 && codeUnit <= 0x001f) ||\n codeUnit === 0x007f ||\n (index === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||\n (index === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && string.charCodeAt(0) === 0x002d)\n ) {\n result += `\\\\${codeUnit.toString(16)} `;\n continue;\n }\n\n if (index === 0 && length === 1 && codeUnit === 0x002d) {\n result += '\\\\-';\n continue;\n }\n\n if (\n codeUnit >= 0x0080 ||\n codeUnit === 0x002d ||\n codeUnit === 0x005f ||\n (codeUnit >= 0x0030 && codeUnit <= 0x0039) ||\n (codeUnit >= 0x0041 && codeUnit <= 0x005a) ||\n (codeUnit >= 0x0061 && codeUnit <= 0x007a)\n ) {\n result += string.charAt(index);\n continue;\n }\n\n result += `\\\\${string.charAt(index)}`;\n }\n\n return result;\n}\n"]}
@@ -0,0 +1,3 @@
1
+ /** Escape an element id for the `tag#<id>` selector form shared by strategies and fallback. */
2
+ export declare function escapeIdForCss(id: string): string;
3
+ //# sourceMappingURL=escape-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escape-id.d.ts","sourceRoot":"","sources":["../../../src/helpers/escape-id.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjD"}
@@ -0,0 +1,6 @@
1
+ import { escapeCssIdentifier } from './escape-css-identifier';
2
+ /** Escape an element id for the `tag#<id>` selector form shared by strategies and fallback. */
3
+ export function escapeIdForCss(id) {
4
+ return escapeCssIdentifier(id);
5
+ }
6
+ //# sourceMappingURL=escape-id.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escape-id.js","sourceRoot":"","sources":["../../../src/helpers/escape-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAO,mBAAmB,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC","sourcesContent":["import { escapeCssIdentifier } from './escape-css-identifier';\n\n/** Escape an element id for the `tag#<id>` selector form shared by strategies and fallback. */\nexport function escapeIdForCss(id: string): string {\n return escapeCssIdentifier(id);\n}\n"]}
@@ -0,0 +1,23 @@
1
+ import { ResolvedSelectorConfig } from '../types';
2
+ /**
3
+ * Shared helper that the `stableId` strategy (in this PR) and the
4
+ * `fallback-css-path` walker (in the orchestration PR) both consult to decide
5
+ * whether an element's id is usable as a selector anchor.
6
+ *
7
+ * Resolution order:
8
+ *
9
+ * 1. Check the customer's explicit-tracking attribute. If set with an empty
10
+ * value (e.g. `data-amp-track-id=""`), that's an explicit suppression
11
+ * signal — the customer is telling us to ignore this element's id even
12
+ * if it would otherwise look stable. Return null.
13
+ * 2. Read the element's id. If absent or empty, return null.
14
+ * 3. Check the id against the autogenerated-id pattern pack. If matched,
15
+ * return null (the algorithm should walk past this element).
16
+ * 4. Otherwise return the id.
17
+ *
18
+ * The single point of consultation means the strategy and the fallback always
19
+ * agree on what's a usable id — no chance of one component filtering an id
20
+ * while another uses it anyway.
21
+ */
22
+ export declare function getStableId(el: Element, cfg: ResolvedSelectorConfig): string | null;
23
+ //# sourceMappingURL=get-stable-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"get-stable-id.d.ts","sourceRoot":"","sources":["../../../src/helpers/get-stable-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAoBnF"}
@@ -0,0 +1,40 @@
1
+ import { isStableId } from '../patterns/autogenerated-ids';
2
+ /**
3
+ * Shared helper that the `stableId` strategy (in this PR) and the
4
+ * `fallback-css-path` walker (in the orchestration PR) both consult to decide
5
+ * whether an element's id is usable as a selector anchor.
6
+ *
7
+ * Resolution order:
8
+ *
9
+ * 1. Check the customer's explicit-tracking attribute. If set with an empty
10
+ * value (e.g. `data-amp-track-id=""`), that's an explicit suppression
11
+ * signal — the customer is telling us to ignore this element's id even
12
+ * if it would otherwise look stable. Return null.
13
+ * 2. Read the element's id. If absent or empty, return null.
14
+ * 3. Check the id against the autogenerated-id pattern pack. If matched,
15
+ * return null (the algorithm should walk past this element).
16
+ * 4. Otherwise return the id.
17
+ *
18
+ * The single point of consultation means the strategy and the fallback always
19
+ * agree on what's a usable id — no chance of one component filtering an id
20
+ * while another uses it anyway.
21
+ */
22
+ export function getStableId(el, cfg) {
23
+ // 1. Suppression signal: empty explicit-tracking attribute on this element.
24
+ var trackAttr = el.getAttribute(cfg.explicitTrackingAttribute);
25
+ if (trackAttr !== null && trackAttr === '') {
26
+ return null;
27
+ }
28
+ // 2. Id presence.
29
+ var id = el.getAttribute('id');
30
+ if (id === null || id === '') {
31
+ return null;
32
+ }
33
+ // 3. Autogenerated-pattern filter.
34
+ if (!isStableId(id, cfg.autogeneratedIdPatterns)) {
35
+ return null;
36
+ }
37
+ // 4. Stable.
38
+ return id;
39
+ }
40
+ //# sourceMappingURL=get-stable-id.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"get-stable-id.js","sourceRoot":"","sources":["../../../src/helpers/get-stable-id.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,EAAW,EAAE,GAA2B;IAClE,4EAA4E;IAC5E,IAAM,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACjE,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE;QAC1C,OAAO,IAAI,CAAC;KACb;IAED,kBAAkB;IAClB,IAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,EAAE,EAAE;QAC5B,OAAO,IAAI,CAAC;KACb;IAED,mCAAmC;IACnC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,uBAAuB,CAAC,EAAE;QAChD,OAAO,IAAI,CAAC;KACb;IAED,aAAa;IACb,OAAO,EAAE,CAAC;AACZ,CAAC","sourcesContent":["import { ResolvedSelectorConfig } from '../types';\nimport { isStableId } from '../patterns/autogenerated-ids';\n\n/**\n * Shared helper that the `stableId` strategy (in this PR) and the\n * `fallback-css-path` walker (in the orchestration PR) both consult to decide\n * whether an element's id is usable as a selector anchor.\n *\n * Resolution order:\n *\n * 1. Check the customer's explicit-tracking attribute. If set with an empty\n * value (e.g. `data-amp-track-id=\"\"`), that's an explicit suppression\n * signal — the customer is telling us to ignore this element's id even\n * if it would otherwise look stable. Return null.\n * 2. Read the element's id. If absent or empty, return null.\n * 3. Check the id against the autogenerated-id pattern pack. If matched,\n * return null (the algorithm should walk past this element).\n * 4. Otherwise return the id.\n *\n * The single point of consultation means the strategy and the fallback always\n * agree on what's a usable id — no chance of one component filtering an id\n * while another uses it anyway.\n */\nexport function getStableId(el: Element, cfg: ResolvedSelectorConfig): string | null {\n // 1. Suppression signal: empty explicit-tracking attribute on this element.\n const trackAttr = el.getAttribute(cfg.explicitTrackingAttribute);\n if (trackAttr !== null && trackAttr === '') {\n return null;\n }\n\n // 2. Id presence.\n const id = el.getAttribute('id');\n if (id === null || id === '') {\n return null;\n }\n\n // 3. Autogenerated-pattern filter.\n if (!isStableId(id, cfg.autogeneratedIdPatterns)) {\n return null;\n }\n\n // 4. Stable.\n return id;\n}\n"]}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * @amplitude/element-selector
3
+ *
4
+ * Shared element-selector algorithm consumed by autocapture, the
5
+ * app.amplitude.com tagging UI, and the Chrome extension visual tagger.
6
+ *
7
+ * This file is the package's public API surface. The orchestrator, fallback,
8
+ * config resolver, and engine factory compose on top of the primitives
9
+ * (types, pattern packs, helpers, strategies) to produce the runtime engine
10
+ * consumers actually call.
11
+ *
12
+ * See the design doc:
13
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
14
+ */
15
+ export declare const PACKAGE_NAME = "@amplitude/element-selector";
16
+ export type { Strategy, StrategyContext, ResolvedSelectorConfig, ElementSelectorRemoteConfig, ElementSelectorLogger, SelectorEngine, } from './types';
17
+ export { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, isStableId, } from './patterns/autogenerated-ids';
18
+ export { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns, filterClasses, } from './patterns/unstable-classes';
19
+ export { getStableId } from './helpers/get-stable-id';
20
+ export { describeRelative } from './helpers/describe-relative';
21
+ export { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';
22
+ export { stableId as stableIdStrategy } from './strategies/stable-id';
23
+ export { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';
24
+ export type { OrchestratorOptions } from './orchestrator';
25
+ export { fallbackCssPath } from './fallback-css-path';
26
+ export { legacyCssPath } from './legacy-css-path';
27
+ export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
28
+ export { createSelectorEngine } from './engine';
29
+ export type { CreateSelectorEngineOptions } from './engine';
30
+ export { generateSelector } from './generate-selector';
31
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,50 @@
1
+ /**
2
+ * @amplitude/element-selector
3
+ *
4
+ * Shared element-selector algorithm consumed by autocapture, the
5
+ * app.amplitude.com tagging UI, and the Chrome extension visual tagger.
6
+ *
7
+ * This file is the package's public API surface. The orchestrator, fallback,
8
+ * config resolver, and engine factory compose on top of the primitives
9
+ * (types, pattern packs, helpers, strategies) to produce the runtime engine
10
+ * consumers actually call.
11
+ *
12
+ * See the design doc:
13
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
14
+ */
15
+ export var PACKAGE_NAME = '@amplitude/element-selector';
16
+ // ===== Pattern packs =====
17
+ export { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, isStableId, } from './patterns/autogenerated-ids';
18
+ export { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns, filterClasses, } from './patterns/unstable-classes';
19
+ // ===== Helpers =====
20
+ export { getStableId } from './helpers/get-stable-id';
21
+ export { describeRelative } from './helpers/describe-relative';
22
+ // ===== Strategies =====
23
+ export { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';
24
+ export { stableId as stableIdStrategy } from './strategies/stable-id';
25
+ // ===== Orchestrator + fallback =====
26
+ // Exposed publicly so the dashboard / Chrome extension can call them ad-hoc
27
+ // without instantiating a full engine — useful for preview / debugging flows.
28
+ export { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';
29
+ export { fallbackCssPath } from './fallback-css-path';
30
+ // ===== Legacy walker =====
31
+ // Canonical home for the Chromium-DevTools-derived `cssPath` algorithm.
32
+ // Both `plugin-autocapture-browser` and `session-replay-ui` historically
33
+ // shipped their own copies kept in sync by comment; both will switch to
34
+ // re-exporting from here so the two can never drift again. End consumers
35
+ // rarely need to call this directly — `engine.generate` and
36
+ // `generateSelector` route through it automatically — but it's exported so
37
+ // the SDK and dashboard can drop their local copies without breaking
38
+ // downstream imports.
39
+ export { legacyCssPath } from './legacy-css-path';
40
+ // ===== Config resolver =====
41
+ export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
42
+ // ===== Engine factory =====
43
+ export { createSelectorEngine } from './engine';
44
+ // ===== Top-level selector entry point =====
45
+ // Use this from React contexts / boot-time call sites where the engine may
46
+ // not yet be available. When the engine *is* present, just call
47
+ // `engine.generate(el)` directly — it has the same kill-switch semantics
48
+ // baked in.
49
+ export { generateSelector } from './generate-selector';
50
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,IAAM,YAAY,GAAG,6BAA6B,CAAC;AAY1D,4BAA4B;AAC5B,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;AAErC,sBAAsB;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,yBAAyB;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,sCAAsC;AACtC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,4BAA4B;AAC5B,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,4DAA4D;AAC5D,2EAA2E;AAC3E,qEAAqE;AACrE,sBAAsB;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,8BAA8B;AAC9B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD,6CAA6C;AAC7C,2EAA2E;AAC3E,gEAAgE;AAChE,yEAAyE;AACzE,YAAY;AACZ,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC","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"]}
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Canonical legacy CSS-path walker.
3
+ *
4
+ * This is the Chromium-DevTools-derived `cssPath` algorithm that was the only
5
+ * selector source autocapture used before the strategy engine existed. It still
6
+ * matters in two situations:
7
+ *
8
+ * 1. The kill switch: when `ResolvedSelectorConfig.enabled === false`, the
9
+ * engine routes here so a customer who flips the engine off mid-session
10
+ * keeps emitting the same selectors their downstream zones and cohorts
11
+ * were built against.
12
+ * 2. The safety net: when the strategy chain or its internal walker throws
13
+ * anything unexpected, the engine catches and falls back here. The
14
+ * autocapture click handler must always produce *some* selector — a
15
+ * runtime exception in selector generation is a worse outcome than a
16
+ * slightly less stable selector.
17
+ *
18
+ * Until this file existed, the algorithm was duplicated in two places kept
19
+ * "in sync by comment":
20
+ *
21
+ * - `packages/plugin-autocapture-browser/src/libs/element-path.ts`
22
+ * - `javascript/packages/session-replay-ui/src/utils/element-path.ts`
23
+ *
24
+ * Both will eventually re-export from here so divergence becomes impossible.
25
+ *
26
+ * Behavior is byte-identical to those two copies — selectors emitted by this
27
+ * function for a given element MUST match what the SDK has been emitting in
28
+ * production. Do not "fix" the selector format without an explicit version
29
+ * bump and a coordinated dashboard rollout.
30
+ *
31
+ * **Why this lives in the package, not as an optional consumer concern:**
32
+ *
33
+ * Every consumer that uses `engine.generate(el)` benefits from the kill
34
+ * switch and the safety net automatically. Without this, each new consumer
35
+ * (Chrome extension visual tagger, future tagging surfaces) has to
36
+ * reimplement the same router and the same legacy walker. We learned that
37
+ * the hard way — by writing the same `if (config.enabled && engine) ...
38
+ * else cssPath()` block in two repositories with two copies of cssPath.
39
+ *
40
+ * Code is adapted from The Chromium Authors.
41
+ * Source: https://github.com/ChromeDevTools/devtools-frontend/blob/main/front_end/panels/elements/DOMPath.ts#L14
42
+ * License: BSD-style license
43
+ *
44
+ * Copyright 2014 The Chromium Authors
45
+ *
46
+ * Redistribution and use in source and binary forms, with or without
47
+ * modification, are permitted provided that the following conditions are
48
+ * met:
49
+ *
50
+ * * Redistributions of source code must retain the above copyright
51
+ * notice, this list of conditions and the following disclaimer.
52
+ * * Redistributions in binary form must reproduce the above
53
+ * copyright notice, this list of conditions and the following
54
+ * disclaimer in the documentation and/or other materials provided
55
+ * with the distribution.
56
+ * * Neither the name of Google Inc. nor the names of its
57
+ * contributors may be used to endorse or promote products derived
58
+ * from this software without specific prior written permission.
59
+ *
60
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
61
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
62
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
63
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
64
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
65
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
66
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
67
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
68
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
69
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
70
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
71
+ */
72
+ /**
73
+ * Produce a CSS selector string for `node` using the legacy positional walker.
74
+ *
75
+ * Returns the empty string for non-element nodes — same shape every existing
76
+ * caller depends on. Never throws for well-formed Element inputs.
77
+ *
78
+ * @param node Element to identify.
79
+ * @param optimized When `true`, short-circuits at the nearest unique-ish step
80
+ * (id or `<body>` / `<head>` / `<html>`). Default `false`,
81
+ * which matches what autocapture has always passed.
82
+ */
83
+ export declare const legacyCssPath: (node: Element, optimized?: boolean) => string;
84
+ //# sourceMappingURL=legacy-css-path.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"legacy-css-path.d.ts","sourceRoot":"","sources":["../../src/legacy-css-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAgBH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,OAAO,cAAc,OAAO,KAAG,MAuBlE,CAAC"}