chore(element-selector): scaffold element selector types

[jxiwang]

Summary

Second PR in the v1 element-selector groundwork chain. Lands the static + primitive pieces of @amplitude/element-selector: type definitions, both regex pattern packs, helper functions, and the two v1 strategies. Each piece is independently unit-tested — nothing drives them together yet. The orchestrator, fallback, config resolver, and engine factory land in the follow-up PR (SR-4609).

Closes SR-4608.

What's in this PR

Types (src/types.ts)

• Strategy, StrategyContext — pluggable-strategy interface
• ResolvedSelectorConfig — runtime config consumed by strategies / orchestrator / fallback
• ElementSelectorRemoteConfig — remote-config payload shape (every field optional)
• SelectorEngine — public engine interface (implementation lands in the orchestration PR)

Pattern packs

• patterns/autogenerated-ids.ts — DEFAULT_AUTOGENERATED_ID_PATTERNS (React useId, Radix, Headless UI, MUI, hex hashes, trailing-digit timestamps, 4+ consecutive digits) + compile() + isStableId()
• patterns/unstable-classes.ts — DEFAULT_UNSTABLE_CLASS_PATTERNS (Tailwind utilities + variants, CSS-in-JS / build hashes, Swiper / MUI / Radix runtime state classes) + compile() + filterClasses()

Helpers

• helpers/get-stable-id.ts — single source of truth for "is this element's id usable?" (honors the explicit-tracking-attribute suppression signal + the autogen filter)
• helpers/describe-relative.ts — positional descent builder, emits tag:nth-of-type(n)

Strategies

• strategies/explicit-tracking-attribute.ts — anchor on data-amp-track-id (or the customer-configured attribute name)
• strategies/stable-id.ts — anchor on tag#id when the id survives getStableId

Tests — one file per source file, all running on jsdom; pattern packs are table-driven with positive and negative cases drawn from real React / Radix / Headless UI / MUI / Swiper / Tailwind / CSS-modules / Emotion / styled-components samples.

What's NOT in this PR

• Orchestrator with ancestor walk → SR-4609
• fallbackCssPath → SR-4609
• resolveSelectorConfig → SR-4609
• createSelectorEngine factory + the runtime SelectorEngine instance → SR-4609
• Logger integration with @amplitude/analytics-core → SR-4641 (verification PR)
• Property tests, scenarios corpus, JSON schema, README → SR-4641

Why a separate package

The selector algorithm needs to be consumed by three surfaces — the autocapture SDK plugin, the app.amplitude.com tagging UI, and the Chrome extension visual tagger. Standing it up as a shared package now avoids the "copy the algorithm into each consumer" pattern currently in place with the legacy cssPath. Design doc at packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md.

Stack

Branches off SR-4560 (scaffolding, already merged). The next PR (SR-4609, orchestration) branches off this one.

Test plan

• pnpm --filter @amplitude/element-selector test passes
• pnpm --filter @amplitude/element-selector lint passes
• pnpm --filter @amplitude/element-selector build produces both ESM + CJS output
• No runtime dependencies added beyond tslib (logger integration arrives in SR-4641)
• No exports added to src/index.ts that aren't documented in the design doc

Checklist

• Does your PR title have the correct title format?
• Does your PR have a breaking change?:

---

Note

Low Risk
New library code and exports only; no runtime wiring to autocapture yet, and behavior is covered by unit tests.

Overview
This PR expands @amplitude/element-selector from a placeholder entry point into the v1 foundation: public types (Strategy, ResolvedSelectorConfig, ElementSelectorRemoteConfig, SelectorEngine), default autogenerated-id and unstable-class regex packs with compile / isStableId / filterClasses, helpers (getStableId, describeRelative, internal escapeCssIdentifier), and the first two strategies (explicit tracking attribute, stable tag#id). index.ts now re-exports that surface for SDK, dashboard, and extension consumers.

Orchestrator, fallback walker, config resolver, and SelectorEngine implementation are intentionally out of scope (follow-up PR). Each new module ships with jsdom unit tests, including table-driven pattern coverage.

^{Reviewed by Cursor Bugbot for commit 9758d21. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

SR-4608

[github-actions]

size-limit report 📦

Path	Size
packages/analytics-browser/lib/scripts/amplitude-min.js.gz	58.38 KB (0%)
packages/session-replay-browser/lib/scripts/session-replay-browser-min.js.gz	132.01 KB (0%)
packages/unified/lib/scripts/amplitude-min.umd.js.gz	209.43 KB (0%)