/** * Core type definitions for the v1 element-selector algorithm. * * These are the public-API contract that consumers (autocapture SDK, dashboard * tagging UI, Chrome extension visual tagger) design against. They land before * any implementation so the contract is stable for cross-team review. * * See the design doc: * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md */ /** * A pluggable selector strategy. Given an element + context, returns a CSS * selector string candidate (which the orchestrator will then uniqueness-check) * or `null` when the strategy doesn't apply to this element. */ export interface Strategy { /** Stable identifier for the strategy. Used for diagnostics and remote-config references. */ readonly name: string; /** * Produce a candidate selector for `el`, or `null` if this strategy has * nothing to contribute for this element. Strategies are pure transforms — * they never call `querySelectorAll` themselves; uniqueness is checked by * the orchestrator in the next layer up. */ try(el: Element, ctx: StrategyContext): string | null; } /** * Context passed to every strategy invocation. `scope` is the document or * shadow root the orchestrator will use for uniqueness checks; `config` is the * resolved configuration (defaults + remote + local options merged). */ export interface StrategyContext { scope: ParentNode; config: ResolvedSelectorConfig; } /** * Logger shape accepted by element-selector diagnostics. * * This is intentionally structural so callers can pass the SDK's * `@amplitude/analytics-core` ILogger without this package needing to import * analytics-core types during standalone tests/builds. */ export interface ElementSelectorLogger { warn(...args: unknown[]): void; debug(...args: unknown[]): void; } /** * Fully-resolved configuration consumed at runtime. Produced by * `resolveSelectorConfig` (lands in the orchestration PR) from the * `ElementSelectorRemoteConfig` payload plus built-in defaults. */ export interface ResolvedSelectorConfig { /** Master kill switch. When false, autocapture reverts to legacy cssPath. */ enabled: boolean; /** Attribute name customers can use to set or suppress anchors. Default: 'data-amp-track-id'. */ explicitTrackingAttribute: string; /** Compiled regex patterns matching ids the algorithm should treat as autogenerated. */ autogeneratedIdPatterns: RegExp[]; /** Compiled regex patterns matching classes the fallback should filter from sibling disambiguation. */ unstableClassPatterns: RegExp[]; /** Optional throttle on the ancestor walk. When undefined, the walk runs to . */ maxAncestorWalkDepth?: number; } /** * Remote-config payload shape. Each field is optional; absent fields fall back * to built-in defaults. Customers see the defaults in the remote-config UI and * may add or remove patterns as needed. */ export interface ElementSelectorRemoteConfig { /** Kill switch. When set, overrides the default at resolve time. */ enabled?: boolean; /** Override the attribute name used for explicit tracking. */ explicitTrackingAttribute?: string; /** Full replacement for the autogenerated-id pattern list. When omitted, defaults apply. */ autogeneratedIdPatterns?: string[]; /** Full replacement for the unstable-class pattern list. When omitted, defaults apply. */ unstableClassPatterns?: string[]; /** Defensive throttle on the ancestor walk. Omit for unbounded walking to . */ maxAncestorWalkDepth?: number; } /** * Public interface of the runtime engine. Implementation lands in the * orchestration PR; the interface is declared here so consumers can write * against the contract before the class exists. */ export interface SelectorEngine { /** Produce a CSS selector string identifying `el` using the engine's current config. */ generate(el: Element): string; /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */ getConfig(): Readonly; /** Replace the current config. Notifies any onConfigChange subscribers. */ updateConfig(next: ResolvedSelectorConfig): void; /** * Subscribe to config-change notifications. Returns an unsubscribe function. * Used by the Chrome extension to keep its locally-hydrated engine in sync * with the customer's SDK as remote config updates flow in. */ onConfigChange(cb: (config: ResolvedSelectorConfig) => void): () => void; } //# sourceMappingURL=types.d.ts.map