@amplitude/element-selector 0.2.1 → 0.3.1-video-analytics-2.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,196 @@
1
+ /**
2
+ * Shadow-DOM traversal + re-resolution helpers.
3
+ *
4
+ * CSS selectors cannot pierce shadow boundaries: `document.querySelector` never
5
+ * matches an element that lives inside a shadow root. So a selector that needs
6
+ * to reach into shadow DOM can't be a single flat string — it has to be a
7
+ * sequence of per-tree selectors, one per shadow tree, each resolvable within
8
+ * its own root. We join those segments with `SHADOW_BOUNDARY_DELIMITER` and
9
+ * re-resolve them with `resolveSelector`, descending one `shadowRoot` per
10
+ * boundary.
11
+ *
12
+ * This module owns the primitives that knowledge lives in:
13
+ *
14
+ * - `composedParent` / `rootOf` — walk *out* of a shadow tree (the light-DOM
15
+ * `parentElement` chain dead-ends at a shadow root; `getRootNode().host`
16
+ * crosses the boundary).
17
+ * - `segmentWalk` — split the outward walk into per-tree segments, honoring
18
+ * the configured max shadow depth.
19
+ * - `resolveSelector` — the symmetric inverse of the engine's output: split
20
+ * on the delimiter and pierce open shadow roots to re-find the element.
21
+ * - `walkComposedAncestors` — yield ancestors up the composed tree, honoring a
22
+ * shadow-boundary crossing budget (shared by capture and selector layers).
23
+ * - `collectOpenShadowRoots` — DFS collection of open shadow roots for
24
+ * observer fan-out and deep `querySelectorAll`.
25
+ * - `positionalStep` — a shadow-aware `tag:nth-of-type(n)` builder shared by
26
+ * the orchestrator's descent and the fallback walker, so a shadow-root-top
27
+ * element is still disambiguated against its `ShadowRoot` siblings.
28
+ *
29
+ * See the design doc:
30
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
31
+ */
32
+ /**
33
+ * Delimiter that separates per-shadow-tree segments in a generated selector.
34
+ *
35
+ * Chosen to be visually distinct and trivially splittable, and to be invalid as
36
+ * a real CSS combinator so it can never be confused with a `>` child combinator
37
+ * the engine emits inside a single tree. Example output:
38
+ *
39
+ * `div#host >>> button:nth-of-type(1)`
40
+ *
41
+ * which `resolveSelector` re-resolves as
42
+ * `document.querySelector('div#host').shadowRoot.querySelector('button:nth-of-type(1)')`.
43
+ */
44
+ export declare const SHADOW_BOUNDARY_DELIMITER = " >>> ";
45
+ /**
46
+ * Marker prefix for a "direct child from the root" chain inside a shadow tree.
47
+ *
48
+ * A positional chain scoped to a `ShadowRoot` (e.g. `div:nth-of-type(2)`) is not
49
+ * anchored: `querySelector` matches it tree-wide, and `:scope` matches nothing
50
+ * on a `ShadowRoot` (it isn't an element), so there is no CSS way to express
51
+ * "direct child of the root." The generator therefore prefixes such chains with
52
+ * this marker and `resolveSelector` resolves them by strict direct-child descent
53
+ * instead of `querySelector`. Keying off this explicit marker — rather than
54
+ * sniffing a segment for the absence of `#`/`[` — keeps the round-trip correct
55
+ * no matter what the steps contain (tag, `:nth-of-type`, classes, …).
56
+ *
57
+ * `:scope > ` is deliberately valid CSS syntax so a generated selector stays a
58
+ * syntactically legal string; its meaning here is purely the descent signal.
59
+ */
60
+ export declare const SHADOW_CHILD_CHAIN_PREFIX = ":scope > ";
61
+ /** Narrowing guard that tolerates environments without a `ShadowRoot` global. */
62
+ export declare function isShadowRoot(node: Node): node is ShadowRoot;
63
+ /**
64
+ * Anchor a per-tree segment so it re-resolves within a `ShadowRoot`.
65
+ *
66
+ * Both selector algorithms (the strategy-chain fallback and the legacy Chromium
67
+ * `cssPath`) can emit a segment that is only *positionally* specified — a chain
68
+ * of `tag:nth-*` / class steps with no id or attribute to pin it. In the light
69
+ * DOM the chain is implicitly anchored by the unique `<html>` root; inside a
70
+ * shadow root there is no such root element, so `querySelector` matches the
71
+ * chain tree-wide and can resolve to the wrong element (or none).
72
+ *
73
+ * When `segment` is such a root-anchored positional chain inside a shadow root,
74
+ * we prefix it with {@link SHADOW_CHILD_CHAIN_PREFIX} so `resolveSelector`
75
+ * descends by strict direct-child matching instead of `querySelector`. An
76
+ * id/attribute-anchored segment is already resolvable tree-wide and is returned
77
+ * untouched. `isRootAnchored` is the caller's decision (each generator knows
78
+ * whether its own output reached the tree top vs. short-circuited on an id), so
79
+ * this stays correct regardless of what the steps contain.
80
+ */
81
+ export declare function anchorSegmentToShadowScope(segment: string, scope: ParentNode, isRootAnchored: boolean): string;
82
+ /**
83
+ * Whether the legacy `cssPath` output for `el` is a root-anchored positional
84
+ * chain rather than one anchored by an id.
85
+ *
86
+ * `legacyCssPath` short-circuits at the first element — inclusive of `el` —
87
+ * that carries an `id`, emitting `tag#id > …` from there. If some element in
88
+ * `el`'s ancestor chain has an id the emitted selector is id-anchored (a plain,
89
+ * tree-wide-resolvable `querySelector`); if none does, the chain spans the tree
90
+ * top down to `el` via positional steps and must be marked for direct-child
91
+ * descent inside a shadow root. This walks the same `parentElement` chain the
92
+ * legacy walker does, so the two stay in lockstep.
93
+ */
94
+ export declare function legacyPathIsRootAnchored(el: Element): boolean;
95
+ /**
96
+ * The queryable root for `el`'s own tree: the enclosing `ShadowRoot` when `el`
97
+ * lives inside shadow DOM, otherwise the owner document. Both support
98
+ * `querySelectorAll`, so uniqueness checks can be scoped to the correct tree.
99
+ *
100
+ * Preserves the legacy default for non-shadow elements (`ownerDocument`), so
101
+ * nothing changes for the common flat-document case.
102
+ */
103
+ export declare function rootOf(el: Element): ParentNode;
104
+ /**
105
+ * The next element up, crossing shadow boundaries: `parentElement` within a
106
+ * tree, or the shadow host when `el` is at the top of a shadow tree. Returns
107
+ * `null` only at the document root (or a detached non-shadow root).
108
+ */
109
+ export declare function composedParent(el: Element): Element | null;
110
+ /** One tree's contribution to a piercing selector. */
111
+ export interface TreeSegment {
112
+ /** Queryable root for this tree — a `Document` or `ShadowRoot`. */
113
+ root: ParentNode;
114
+ /** Element to locate within `root`: the host of the next inner tree, or the original target. */
115
+ target: Element;
116
+ }
117
+ export interface SegmentWalkResult {
118
+ /** Tree segments, outermost (document) first — the order they're joined for output. */
119
+ segments: TreeSegment[];
120
+ /**
121
+ * True when the target sat deeper than `maxShadowDepth` allowed, so inner
122
+ * trees were dropped and the innermost emitted segment targets the shadow
123
+ * host at the depth limit rather than the original target.
124
+ */
125
+ truncated: boolean;
126
+ }
127
+ /**
128
+ * Defensive bound on composed-ancestor walks (host-chain iteration in
129
+ * `walkComposedAncestors` and `segmentWalk`). Far above any real shadow nesting
130
+ * (the resolver caps effective depth at `MAX_SHADOW_DOM_DEPTH`). See also
131
+ * {@link MAX_SHADOW_DOM_TRAVERSAL_NODES} for the DFS collection cap.
132
+ */
133
+ export declare const MAX_SHADOW_COMPOSED_WALK_ITERATIONS = 1024;
134
+ /**
135
+ * Defensive bound on node visits when collecting open shadow roots via DFS.
136
+ * Caps synchronous work inside MutationObserver callbacks on pathologically
137
+ * large trees. See also {@link MAX_SHADOW_COMPOSED_WALK_ITERATIONS} for the
138
+ * ancestor-walk cap.
139
+ */
140
+ export declare const MAX_SHADOW_DOM_TRAVERSAL_NODES = 50000;
141
+ export interface OpenShadowRootEntry {
142
+ root: ShadowRoot;
143
+ /** 1-based shadow-boundary depth relative to the collection `root`. */
144
+ depth: number;
145
+ }
146
+ /**
147
+ * Yield `start` and each ancestor up the composed tree. Within a tree the walk
148
+ * follows `parentElement`; at the top of a shadow tree it crosses to the host
149
+ * when `crossings < maxShadowDepth`. Yields every element including detached
150
+ * nodes at the top of their tree (where `parentElement` is null).
151
+ */
152
+ export declare function walkComposedAncestors(start: Element, maxShadowDepth: number): Generator<Element>;
153
+ /**
154
+ * Collect the OPEN shadow roots within `root`'s composed subtree (its own light
155
+ * children and any nested shadow trees), each paired with how many shadow
156
+ * boundary crossings deep it sits relative to `root` (1-based). Bounded by
157
+ * `maxShadowDepth` crossings and by {@link MAX_SHADOW_DOM_TRAVERSAL_NODES}
158
+ * total nodes. Closed roots are invisible (`el.shadowRoot` is null) and skipped.
159
+ */
160
+ export declare function collectOpenShadowRoots(root: Element, maxShadowDepth: number): OpenShadowRootEntry[];
161
+ /**
162
+ * Split the outward composed walk from `el` into per-tree segments.
163
+ *
164
+ * Always walks fully out to the document so the outermost segment is
165
+ * document-rooted and therefore re-resolvable. `maxShadowDepth` caps how many
166
+ * shadow boundaries the *emitted* selector descends through: when the target is
167
+ * nested deeper than the budget, the innermost (over-budget) trees are dropped
168
+ * and the result is flagged `truncated` — the innermost kept segment then
169
+ * targets the shadow host at the depth limit (a best-effort, still-resolvable
170
+ * selector for an ancestor of the true target).
171
+ */
172
+ export declare function segmentWalk(el: Element, maxShadowDepth: number): SegmentWalkResult;
173
+ /**
174
+ * Re-resolve a generated selector back to its element, piercing open shadow
175
+ * roots at each boundary. The symmetric inverse of `engine.generate`.
176
+ *
177
+ * Returns `null` when any segment fails to match, or when a boundary crossing
178
+ * hits a *closed* shadow root (`host.shadowRoot === null`) — closed roots are
179
+ * opaque from outside, so such selectors cannot round-trip (a documented
180
+ * limitation). Never throws on a malformed segment.
181
+ *
182
+ * @param root Root to resolve against — almost always `document`.
183
+ * @param selector A selector produced by the engine (may contain boundary delimiters).
184
+ */
185
+ export declare function resolveSelector(root: ParentNode, selector: string): Element | null;
186
+ /**
187
+ * Build a single positional step for `el`: `tag:nth-of-type(n)`, indexed among
188
+ * its same-tag siblings. A parentless element emits the bare tag.
189
+ *
190
+ * `shadowAware` extends the parentless case: an element at the top of a shadow
191
+ * tree has a null `parentElement` but can still have same-tag peers among the
192
+ * `ShadowRoot`'s children, so it is indexed against those instead. When
193
+ * `shadowAware` is false every parentless element emits the bare tag.
194
+ */
195
+ export declare function positionalStep(el: Element, shadowAware: boolean): string;
196
+ //# sourceMappingURL=shadow.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/helpers/shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,UAAU,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,CAK9G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAO7D;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,CAM9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAS1D;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,gGAAgG;IAChG,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,OAAO,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,QAAQ,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAiB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAuBjG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwBnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,iBAAiB,CAgClF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0BlF;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAgBxE"}
@@ -0,0 +1,415 @@
1
+ "use strict";
2
+ /**
3
+ * Shadow-DOM traversal + re-resolution helpers.
4
+ *
5
+ * CSS selectors cannot pierce shadow boundaries: `document.querySelector` never
6
+ * matches an element that lives inside a shadow root. So a selector that needs
7
+ * to reach into shadow DOM can't be a single flat string — it has to be a
8
+ * sequence of per-tree selectors, one per shadow tree, each resolvable within
9
+ * its own root. We join those segments with `SHADOW_BOUNDARY_DELIMITER` and
10
+ * re-resolve them with `resolveSelector`, descending one `shadowRoot` per
11
+ * boundary.
12
+ *
13
+ * This module owns the primitives that knowledge lives in:
14
+ *
15
+ * - `composedParent` / `rootOf` — walk *out* of a shadow tree (the light-DOM
16
+ * `parentElement` chain dead-ends at a shadow root; `getRootNode().host`
17
+ * crosses the boundary).
18
+ * - `segmentWalk` — split the outward walk into per-tree segments, honoring
19
+ * the configured max shadow depth.
20
+ * - `resolveSelector` — the symmetric inverse of the engine's output: split
21
+ * on the delimiter and pierce open shadow roots to re-find the element.
22
+ * - `walkComposedAncestors` — yield ancestors up the composed tree, honoring a
23
+ * shadow-boundary crossing budget (shared by capture and selector layers).
24
+ * - `collectOpenShadowRoots` — DFS collection of open shadow roots for
25
+ * observer fan-out and deep `querySelectorAll`.
26
+ * - `positionalStep` — a shadow-aware `tag:nth-of-type(n)` builder shared by
27
+ * the orchestrator's descent and the fallback walker, so a shadow-root-top
28
+ * element is still disambiguated against its `ShadowRoot` siblings.
29
+ *
30
+ * See the design doc:
31
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
32
+ */
33
+ Object.defineProperty(exports, "__esModule", { value: true });
34
+ exports.positionalStep = exports.resolveSelector = exports.segmentWalk = exports.collectOpenShadowRoots = exports.walkComposedAncestors = exports.MAX_SHADOW_DOM_TRAVERSAL_NODES = exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS = exports.composedParent = exports.rootOf = exports.legacyPathIsRootAnchored = exports.anchorSegmentToShadowScope = exports.isShadowRoot = exports.SHADOW_CHILD_CHAIN_PREFIX = exports.SHADOW_BOUNDARY_DELIMITER = void 0;
35
+ var tslib_1 = require("tslib");
36
+ /**
37
+ * Delimiter that separates per-shadow-tree segments in a generated selector.
38
+ *
39
+ * Chosen to be visually distinct and trivially splittable, and to be invalid as
40
+ * a real CSS combinator so it can never be confused with a `>` child combinator
41
+ * the engine emits inside a single tree. Example output:
42
+ *
43
+ * `div#host >>> button:nth-of-type(1)`
44
+ *
45
+ * which `resolveSelector` re-resolves as
46
+ * `document.querySelector('div#host').shadowRoot.querySelector('button:nth-of-type(1)')`.
47
+ */
48
+ exports.SHADOW_BOUNDARY_DELIMITER = ' >>> ';
49
+ /**
50
+ * Marker prefix for a "direct child from the root" chain inside a shadow tree.
51
+ *
52
+ * A positional chain scoped to a `ShadowRoot` (e.g. `div:nth-of-type(2)`) is not
53
+ * anchored: `querySelector` matches it tree-wide, and `:scope` matches nothing
54
+ * on a `ShadowRoot` (it isn't an element), so there is no CSS way to express
55
+ * "direct child of the root." The generator therefore prefixes such chains with
56
+ * this marker and `resolveSelector` resolves them by strict direct-child descent
57
+ * instead of `querySelector`. Keying off this explicit marker — rather than
58
+ * sniffing a segment for the absence of `#`/`[` — keeps the round-trip correct
59
+ * no matter what the steps contain (tag, `:nth-of-type`, classes, …).
60
+ *
61
+ * `:scope > ` is deliberately valid CSS syntax so a generated selector stays a
62
+ * syntactically legal string; its meaning here is purely the descent signal.
63
+ */
64
+ exports.SHADOW_CHILD_CHAIN_PREFIX = ':scope > ';
65
+ /** Narrowing guard that tolerates environments without a `ShadowRoot` global. */
66
+ function isShadowRoot(node) {
67
+ return typeof ShadowRoot !== 'undefined' && node instanceof ShadowRoot;
68
+ }
69
+ exports.isShadowRoot = isShadowRoot;
70
+ /**
71
+ * Anchor a per-tree segment so it re-resolves within a `ShadowRoot`.
72
+ *
73
+ * Both selector algorithms (the strategy-chain fallback and the legacy Chromium
74
+ * `cssPath`) can emit a segment that is only *positionally* specified — a chain
75
+ * of `tag:nth-*` / class steps with no id or attribute to pin it. In the light
76
+ * DOM the chain is implicitly anchored by the unique `<html>` root; inside a
77
+ * shadow root there is no such root element, so `querySelector` matches the
78
+ * chain tree-wide and can resolve to the wrong element (or none).
79
+ *
80
+ * When `segment` is such a root-anchored positional chain inside a shadow root,
81
+ * we prefix it with {@link SHADOW_CHILD_CHAIN_PREFIX} so `resolveSelector`
82
+ * descends by strict direct-child matching instead of `querySelector`. An
83
+ * id/attribute-anchored segment is already resolvable tree-wide and is returned
84
+ * untouched. `isRootAnchored` is the caller's decision (each generator knows
85
+ * whether its own output reached the tree top vs. short-circuited on an id), so
86
+ * this stays correct regardless of what the steps contain.
87
+ */
88
+ function anchorSegmentToShadowScope(segment, scope, isRootAnchored) {
89
+ if (segment && isRootAnchored && isShadowRoot(scope)) {
90
+ return "".concat(exports.SHADOW_CHILD_CHAIN_PREFIX).concat(segment);
91
+ }
92
+ return segment;
93
+ }
94
+ exports.anchorSegmentToShadowScope = anchorSegmentToShadowScope;
95
+ /**
96
+ * Whether the legacy `cssPath` output for `el` is a root-anchored positional
97
+ * chain rather than one anchored by an id.
98
+ *
99
+ * `legacyCssPath` short-circuits at the first element — inclusive of `el` —
100
+ * that carries an `id`, emitting `tag#id > …` from there. If some element in
101
+ * `el`'s ancestor chain has an id the emitted selector is id-anchored (a plain,
102
+ * tree-wide-resolvable `querySelector`); if none does, the chain spans the tree
103
+ * top down to `el` via positional steps and must be marked for direct-child
104
+ * descent inside a shadow root. This walks the same `parentElement` chain the
105
+ * legacy walker does, so the two stay in lockstep.
106
+ */
107
+ function legacyPathIsRootAnchored(el) {
108
+ for (var node = el; node !== null; node = node.parentElement) {
109
+ if (node.getAttribute('id')) {
110
+ return false;
111
+ }
112
+ }
113
+ return true;
114
+ }
115
+ exports.legacyPathIsRootAnchored = legacyPathIsRootAnchored;
116
+ /**
117
+ * The queryable root for `el`'s own tree: the enclosing `ShadowRoot` when `el`
118
+ * lives inside shadow DOM, otherwise the owner document. Both support
119
+ * `querySelectorAll`, so uniqueness checks can be scoped to the correct tree.
120
+ *
121
+ * Preserves the legacy default for non-shadow elements (`ownerDocument`), so
122
+ * nothing changes for the common flat-document case.
123
+ */
124
+ function rootOf(el) {
125
+ var _a;
126
+ var root = el.getRootNode();
127
+ if (isShadowRoot(root)) {
128
+ return root;
129
+ }
130
+ return (_a = el.ownerDocument) !== null && _a !== void 0 ? _a : document;
131
+ }
132
+ exports.rootOf = rootOf;
133
+ /**
134
+ * The next element up, crossing shadow boundaries: `parentElement` within a
135
+ * tree, or the shadow host when `el` is at the top of a shadow tree. Returns
136
+ * `null` only at the document root (or a detached non-shadow root).
137
+ */
138
+ function composedParent(el) {
139
+ if (el.parentElement) {
140
+ return el.parentElement;
141
+ }
142
+ var root = el.getRootNode();
143
+ if (isShadowRoot(root)) {
144
+ return root.host;
145
+ }
146
+ return null;
147
+ }
148
+ exports.composedParent = composedParent;
149
+ /**
150
+ * Defensive bound on composed-ancestor walks (host-chain iteration in
151
+ * `walkComposedAncestors` and `segmentWalk`). Far above any real shadow nesting
152
+ * (the resolver caps effective depth at `MAX_SHADOW_DOM_DEPTH`). See also
153
+ * {@link MAX_SHADOW_DOM_TRAVERSAL_NODES} for the DFS collection cap.
154
+ */
155
+ exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS = 1024;
156
+ /**
157
+ * Defensive bound on node visits when collecting open shadow roots via DFS.
158
+ * Caps synchronous work inside MutationObserver callbacks on pathologically
159
+ * large trees. See also {@link MAX_SHADOW_COMPOSED_WALK_ITERATIONS} for the
160
+ * ancestor-walk cap.
161
+ */
162
+ exports.MAX_SHADOW_DOM_TRAVERSAL_NODES = 50000;
163
+ /**
164
+ * Yield `start` and each ancestor up the composed tree. Within a tree the walk
165
+ * follows `parentElement`; at the top of a shadow tree it crosses to the host
166
+ * when `crossings < maxShadowDepth`. Yields every element including detached
167
+ * nodes at the top of their tree (where `parentElement` is null).
168
+ */
169
+ function walkComposedAncestors(start, maxShadowDepth) {
170
+ var node, crossings, iterations, host;
171
+ return tslib_1.__generator(this, function (_a) {
172
+ switch (_a.label) {
173
+ case 0:
174
+ node = start;
175
+ crossings = 0;
176
+ iterations = 0;
177
+ _a.label = 1;
178
+ case 1:
179
+ if (!(node !== null && iterations < exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS)) return [3 /*break*/, 3];
180
+ iterations += 1;
181
+ return [4 /*yield*/, node];
182
+ case 2:
183
+ _a.sent();
184
+ if (node.parentElement) {
185
+ node = node.parentElement;
186
+ return [3 /*break*/, 1];
187
+ }
188
+ if (crossings < maxShadowDepth && typeof node.getRootNode === 'function') {
189
+ host = composedParent(node);
190
+ if (host && host !== node) {
191
+ crossings += 1;
192
+ node = host;
193
+ return [3 /*break*/, 1];
194
+ }
195
+ }
196
+ return [3 /*break*/, 3];
197
+ case 3: return [2 /*return*/];
198
+ }
199
+ });
200
+ }
201
+ exports.walkComposedAncestors = walkComposedAncestors;
202
+ /**
203
+ * Collect the OPEN shadow roots within `root`'s composed subtree (its own light
204
+ * children and any nested shadow trees), each paired with how many shadow
205
+ * boundary crossings deep it sits relative to `root` (1-based). Bounded by
206
+ * `maxShadowDepth` crossings and by {@link MAX_SHADOW_DOM_TRAVERSAL_NODES}
207
+ * total nodes. Closed roots are invisible (`el.shadowRoot` is null) and skipped.
208
+ */
209
+ function collectOpenShadowRoots(root, maxShadowDepth) {
210
+ var found = [];
211
+ if (maxShadowDepth <= 0) {
212
+ return found;
213
+ }
214
+ var stack = [[root, 0]];
215
+ var visited = 0;
216
+ while (stack.length && visited < exports.MAX_SHADOW_DOM_TRAVERSAL_NODES) {
217
+ visited += 1;
218
+ var _a = tslib_1.__read(stack.pop(), 2), el = _a[0], depth = _a[1];
219
+ var shadowRoot = el.shadowRoot;
220
+ if (shadowRoot && depth + 1 <= maxShadowDepth) {
221
+ found.push({ root: shadowRoot, depth: depth + 1 });
222
+ var shadowChildren = shadowRoot.children;
223
+ for (var i = 0; i < shadowChildren.length; i++) {
224
+ stack.push([shadowChildren[i], depth + 1]);
225
+ }
226
+ }
227
+ var children = el.children;
228
+ for (var i = 0; i < children.length; i++) {
229
+ stack.push([children[i], depth]);
230
+ }
231
+ }
232
+ return found;
233
+ }
234
+ exports.collectOpenShadowRoots = collectOpenShadowRoots;
235
+ /**
236
+ * Split the outward composed walk from `el` into per-tree segments.
237
+ *
238
+ * Always walks fully out to the document so the outermost segment is
239
+ * document-rooted and therefore re-resolvable. `maxShadowDepth` caps how many
240
+ * shadow boundaries the *emitted* selector descends through: when the target is
241
+ * nested deeper than the budget, the innermost (over-budget) trees are dropped
242
+ * and the result is flagged `truncated` — the innermost kept segment then
243
+ * targets the shadow host at the depth limit (a best-effort, still-resolvable
244
+ * selector for an ancestor of the true target).
245
+ */
246
+ function segmentWalk(el, maxShadowDepth) {
247
+ // Build innermost-first: one segment per tree, each `target` being the
248
+ // element to locate within that tree (the inner tree's host, or `el`).
249
+ var innermostFirst = [];
250
+ var node = el;
251
+ var iterations = 0;
252
+ while (node !== null && iterations < exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS) {
253
+ iterations += 1;
254
+ var root = rootOf(node);
255
+ innermostFirst.push({ root: root, target: node });
256
+ var actualRoot = node.getRootNode();
257
+ if (!isShadowRoot(actualRoot)) {
258
+ break; // reached the document (or a detached non-shadow root)
259
+ }
260
+ node = actualRoot.host; // cross the boundary outward
261
+ }
262
+ var totalCrossings = innermostFirst.length - 1;
263
+ var truncated = false;
264
+ var kept = innermostFirst;
265
+ if (totalCrossings > maxShadowDepth) {
266
+ // Drop the innermost over-budget trees, keeping the outermost
267
+ // (maxShadowDepth + 1) trees. The new innermost kept segment's `target` is
268
+ // already the shadow host of the first dropped tree.
269
+ kept = innermostFirst.slice(totalCrossings - maxShadowDepth);
270
+ truncated = true;
271
+ }
272
+ // Reverse to outermost-first so the engine joins document → target order.
273
+ return { segments: kept.reverse(), truncated: truncated };
274
+ }
275
+ exports.segmentWalk = segmentWalk;
276
+ /**
277
+ * Re-resolve a generated selector back to its element, piercing open shadow
278
+ * roots at each boundary. The symmetric inverse of `engine.generate`.
279
+ *
280
+ * Returns `null` when any segment fails to match, or when a boundary crossing
281
+ * hits a *closed* shadow root (`host.shadowRoot === null`) — closed roots are
282
+ * opaque from outside, so such selectors cannot round-trip (a documented
283
+ * limitation). Never throws on a malformed segment.
284
+ *
285
+ * @param root Root to resolve against — almost always `document`.
286
+ * @param selector A selector produced by the engine (may contain boundary delimiters).
287
+ */
288
+ function resolveSelector(root, selector) {
289
+ var segments = selector.split(exports.SHADOW_BOUNDARY_DELIMITER);
290
+ var scope = root;
291
+ var found = null;
292
+ for (var i = 0; i < segments.length; i++) {
293
+ if (scope === null) {
294
+ return null; // previous segment's host had no (open) shadow root
295
+ }
296
+ var segment = segments[i].trim();
297
+ try {
298
+ found = resolveSegment(scope, segment);
299
+ }
300
+ catch (_a) {
301
+ return null; // malformed segment — never throw out of the resolver
302
+ }
303
+ if (found === null) {
304
+ return null;
305
+ }
306
+ if (i < segments.length - 1) {
307
+ // Descend into this host's shadow root for the next segment. `null` for a
308
+ // closed root ends resolution gracefully on the next iteration.
309
+ scope = found.shadowRoot;
310
+ }
311
+ }
312
+ return found;
313
+ }
314
+ exports.resolveSelector = resolveSelector;
315
+ /**
316
+ * Resolve a single (non-delimited) segment within `scope`.
317
+ *
318
+ * A segment marked with {@link SHADOW_CHILD_CHAIN_PREFIX} is a root-anchored
319
+ * "direct child from the root" chain (emitted by the fallback for a shadow-root
320
+ * scope, where `querySelector` can't express that anchoring). We strip the
321
+ * marker and resolve by strict direct-child descent. The marker is set
322
+ * explicitly by the generator, so this stays correct regardless of what the
323
+ * steps contain (tag, `:nth-of-type`, classes, …). Every other segment —
324
+ * id/attribute-anchored, or any document-scope segment — resolves via a plain
325
+ * `querySelector`.
326
+ */
327
+ function resolveSegment(scope, segment) {
328
+ if (segment.startsWith(exports.SHADOW_CHILD_CHAIN_PREFIX)) {
329
+ return resolveChildChain(scope, segment.slice(exports.SHADOW_CHILD_CHAIN_PREFIX.length));
330
+ }
331
+ return scope.querySelector(segment);
332
+ }
333
+ /**
334
+ * Resolve a `>`-joined chain as a strict direct-child descent from `scope`. At
335
+ * each level exactly one child matches the step (positional or otherwise via
336
+ * `matches()`), so the walk is deterministic. Returns `null` if any step matches
337
+ * no child.
338
+ */
339
+ function resolveChildChain(scope, chain) {
340
+ var e_1, _a;
341
+ var _b;
342
+ var steps = chain.split('>').map(function (s) { return s.trim(); });
343
+ var children = Array.from(scope.children);
344
+ var el = null;
345
+ var _loop_1 = function (step) {
346
+ el = (_b = children.find(function (child) { return child.matches(step); })) !== null && _b !== void 0 ? _b : null;
347
+ if (el === null) {
348
+ return { value: null };
349
+ }
350
+ children = Array.from(el.children);
351
+ };
352
+ try {
353
+ for (var steps_1 = tslib_1.__values(steps), steps_1_1 = steps_1.next(); !steps_1_1.done; steps_1_1 = steps_1.next()) {
354
+ var step = steps_1_1.value;
355
+ var state_1 = _loop_1(step);
356
+ if (typeof state_1 === "object")
357
+ return state_1.value;
358
+ }
359
+ }
360
+ catch (e_1_1) { e_1 = { error: e_1_1 }; }
361
+ finally {
362
+ try {
363
+ if (steps_1_1 && !steps_1_1.done && (_a = steps_1.return)) _a.call(steps_1);
364
+ }
365
+ finally { if (e_1) throw e_1.error; }
366
+ }
367
+ return el;
368
+ }
369
+ /**
370
+ * Build a single positional step for `el`: `tag:nth-of-type(n)`, indexed among
371
+ * its same-tag siblings. A parentless element emits the bare tag.
372
+ *
373
+ * `shadowAware` extends the parentless case: an element at the top of a shadow
374
+ * tree has a null `parentElement` but can still have same-tag peers among the
375
+ * `ShadowRoot`'s children, so it is indexed against those instead. When
376
+ * `shadowAware` is false every parentless element emits the bare tag.
377
+ */
378
+ function positionalStep(el, shadowAware) {
379
+ var tag = el.tagName.toLowerCase();
380
+ var parent = el.parentElement;
381
+ if (parent === null) {
382
+ // Parentless means the document root (`<html>`), a detached element, or the
383
+ // top of a shadow tree. Only the last has siblings worth indexing, and only
384
+ // when the caller asks for shadow-aware stepping.
385
+ var root = el.getRootNode();
386
+ if (shadowAware && isShadowRoot(root)) {
387
+ return "".concat(tag, ":nth-of-type(").concat(sameTypeIndexAmong(el, root.children), ")");
388
+ }
389
+ return tag;
390
+ }
391
+ return "".concat(tag, ":nth-of-type(").concat(sameTypeIndexAmong(el, parent.children), ")");
392
+ }
393
+ exports.positionalStep = positionalStep;
394
+ /**
395
+ * 1-based index of `el` among same-tag siblings in `siblings`, mirroring
396
+ * `:nth-of-type`. Takes an `HTMLCollection` rather than a parent `Element` so a
397
+ * `ShadowRoot`'s children can be counted too — a `ShadowRoot` is not an
398
+ * `Element` but does expose `children`.
399
+ */
400
+ function sameTypeIndexAmong(el, siblings) {
401
+ var count = 0;
402
+ for (var i = 0; i < siblings.length; i++) {
403
+ var sibling = siblings[i];
404
+ if (sibling.tagName === el.tagName) {
405
+ count += 1;
406
+ if (sibling === el) {
407
+ return count;
408
+ }
409
+ }
410
+ }
411
+ // Defensive: element not found among its parent's children (shouldn't happen
412
+ // for a live element). Return 1 rather than throwing.
413
+ return 1;
414
+ }
415
+ //# sourceMappingURL=shadow.js.map