@whenessel/seql-js 1.0.0

package/dist/seql-js.d.ts

@@ -0,0 +1,1215 @@
+/**
+ * Finds semantic anchor for element identification
+ * Traverses up from target to find semantic root
+ * Following SPECIFICATION.md §7
+ */
+export declare class AnchorFinder {
+    private maxDepth;
+    private cache?;
+    constructor(options: GeneratorOptions, cache?: EIDCache);
+    /**
+     * Finds the best anchor element for the target
+     * @param target - Target element to find anchor for
+     * @returns Anchor result or null if not found
+     */
+    findAnchor(target: Element): AnchorResult | null;
+    /**
+     * Scores an element as anchor candidate (without depth penalty)
+     * @param element - Element to score
+     * @returns Raw score from 0 to 1
+     */
+    scoreAnchor(element: Element): number;
+    /**
+     * Applies depth penalty to score
+     * Following SPECIFICATION.md §7: depthPenalty = (depth - threshold) * factor
+     */
+    private applyDepthPenalty;
+    /**
+     * Determines the tier of an anchor element
+     */
+    private getTier;
+}
+
+/**
+ * Anchor node - the semantic root of the EID path
+ * Following SPECIFICATION.md §7
+ */
+export declare interface AnchorNode {
+    /** HTML tag name (lowercase) */
+    tag: string;
+    /** Semantic features */
+    semantics: ElementSemantics;
+    /** Quality score 0-1 */
+    score: number;
+    /** Whether this is a degraded/fallback anchor */
+    degraded: boolean;
+}
+
+/**
+ * Result of anchor finding
+ */
+export declare interface AnchorResult {
+    element: Element;
+    score: number;
+    tier: 'A' | 'B' | 'C';
+    depth: number;
+}
+
+/**
+ * Options for batch EID generation
+ */
+export declare interface BatchGeneratorOptions {
+    /** Root element to search from (default: document.body) */
+    root?: Element | Document;
+    /** CSS selector to filter elements (default: '*') */
+    filter?: string;
+    /** Maximum number of elements to process (default: Infinity) */
+    limit?: number;
+    /** Progress callback: (current, total) => void */
+    onProgress?: (current: number, total: number) => void;
+    /** Interval for calling onProgress (default: 100) */
+    progressInterval?: number;
+    /** Skip elements without semantic features (default: true) */
+    skipNonSemantic?: boolean;
+    /** Generator options */
+    generatorOptions?: GeneratorOptions;
+    /** Optional cache instance */
+    cache?: EIDCache;
+    /** AbortController for cancellation */
+    signal?: AbortSignal;
+}
+
+/**
+ * Result of batch generation
+ */
+export declare interface BatchResult {
+    /** Successfully generated Element Identities */
+    results: Array<{
+        element: Element;
+        eid: ElementIdentity;
+        generationTimeMs: number;
+    }>;
+    /** Elements that failed to generate EID */
+    failed: Array<{
+        element: Element;
+        error: string;
+    }>;
+    /** Statistics */
+    stats: {
+        totalElements: number;
+        successful: number;
+        failed: number;
+        skipped: number;
+        totalTimeMs: number;
+        avgTimePerElementMs: number;
+        cacheHitRate: number;
+    };
+}
+
+/**
+ * Options for selector building with uniqueness control
+ */
+declare interface BuildSelectorOptions {
+    /**
+     * Enable uniqueness disambiguation for target element.
+     * When true and base selector is not unique, adds:
+     * 1. Extra stable classes (up to maxClasses)
+     * 2. :nth-of-type(N) as last resort
+     */
+    ensureUnique?: boolean;
+    /**
+     * Maximum number of additional classes to add for disambiguation
+     * @default 4
+     */
+    maxClasses?: number;
+    /**
+     * Root element for uniqueness check (defaults to document)
+     */
+    root?: Document | Element;
+}
+
+/**
+ * Result of selector building with uniqueness info
+ */
+declare interface BuildSelectorResult {
+    /** Generated CSS selector */
+    selector: string;
+    /** Whether selector is unique in the given root */
+    isUnique: boolean;
+    /** Whether nth-of-type was added for disambiguation */
+    usedNthOfType: boolean;
+    /** Number of extra classes added for disambiguation */
+    extraClassesAdded: number;
+}
+
+/**
+ * Cache statistics
+ */
+export declare interface CacheStats {
+    /** Total number of EID cache hits */
+    eidHits: number;
+    /** Total number of EID cache misses */
+    eidMisses: number;
+    /** Total number of selector cache hits */
+    selectorHits: number;
+    /** Total number of selector cache misses */
+    selectorMisses: number;
+    /** Total number of anchor cache hits */
+    anchorHits: number;
+    /** Total number of anchor cache misses */
+    anchorMisses: number;
+    /** Total number of semantics cache hits */
+    semanticsHits: number;
+    /** Total number of semantics cache misses */
+    semanticsMisses: number;
+    /** Current selector cache size */
+    selectorCacheSize: number;
+    /** Maximum selector cache size */
+    maxSelectorCacheSize: number;
+}
+
+/**
+ * Calculates overall confidence score for Element Identity
+ * Following SPECIFICATION.md §13 confidence formula
+ *
+ * @param eid - The Element Identity to score
+ * @param uniquenessBonus - Bonus for unique resolution (0-1), determined during resolution
+ * @returns Confidence score from 0 to 1
+ */
+export declare function calculateConfidence(eid: ElementIdentity, uniquenessBonus?: number): number;
+
+/**
+ * Calculates score for a single element based on its semantic features
+ * @param semanticsCount - Number of semantic features present
+ * @param hasId - Whether element has stable ID
+ * @param hasRole - Whether element has ARIA role
+ * @returns Score from 0 to 1
+ */
+export declare function calculateElementScore(semanticsCount: number, hasId: boolean, hasRole: boolean): number;
+
+/**
+ * Base constraint structure
+ */
+export declare interface Constraint {
+    /** Constraint type */
+    type: ConstraintType;
+    /** Constraint-specific parameters */
+    params: Record<string, unknown>;
+    /** Priority (0-100, higher = applied first) */
+    priority: number;
+}
+
+/**
+ * Evaluates and applies constraints to candidates
+ * Following SPECIFICATION.md §13.4
+ */
+export declare class ConstraintsEvaluator {
+    /**
+     * Applies a single constraint to candidates
+     * @param candidates - Current candidate elements
+     * @param constraint - Constraint to apply
+     * @returns Filtered candidates
+     */
+    applyConstraint(candidates: Element[], constraint: Constraint): Element[];
+    /**
+     * Applies text proximity constraint using Levenshtein distance
+     */
+    private applyTextProximity;
+    /**
+     * Applies position constraint
+     */
+    private applyPosition;
+    /**
+     * Gets the top-most element by bounding rect
+     */
+    private getTopMost;
+    /**
+     * Gets the left-most element by bounding rect
+     */
+    private getLeftMost;
+    /**
+     * Calculates Levenshtein distance between two strings
+     */
+    private levenshteinDistance;
+}
+
+/**
+ * Constraint type identifiers
+ * Following SPECIFICATION.md §13.4
+ */
+export declare type ConstraintType = 'uniqueness' | 'text-proximity' | 'position';
+
+/**
+ * Create a new EID cache instance
+ */
+export declare function createEIDCache(options?: EIDCacheOptions): EIDCache;
+
+/**
+ * Generates CSS selectors from Element Identity
+ * Following SPECIFICATION.md §13.1
+ *
+ * Priority order (highest to lowest):
+ * 1. ID (100)
+ * 2. data-testid, data-qa, data-cy (95)
+ * 3. aria-label (90)
+ * 4. name (85)
+ * 5. href, src (80) - semantic for <a>, <img>, etc.
+ * 6. role (75)
+ * 7. type (70)
+ * 8. alt, title, for (60)
+ * 9. Stable classes (35)
+ * 10. nth-of-type (last resort, added when ensureUnique=true)
+ */
+export declare class CssGenerator {
+    /**
+     * Builds CSS selector from Element Identity
+     * @param eid - Element Identity to convert
+     * @param options - Optional uniqueness control settings
+     * @returns CSS selector string (simple) or BuildSelectorResult (with options)
+     */
+    buildSelector(eid: ElementIdentity, options?: BuildSelectorOptions): string;
+    buildSelector(eid: ElementIdentity, options: BuildSelectorOptions & {
+        ensureUnique: true;
+    }): BuildSelectorResult;
+    /**
+     * Builds selector for anchor only (used in fallback)
+     * @param eid - Element Identity
+     * @returns CSS selector for anchor
+     */
+    buildAnchorSelector(eid: ElementIdentity): string;
+    /**
+     * Ensures selector uniqueness by progressively adding classes and nth-of-type
+     */
+    private ensureUniqueSelector;
+    /**
+     * Builds full DOM path selector by traversing actual DOM from anchor
+     * This handles cases where intermediate div/span elements were filtered out
+     */
+    private buildFullDomPathSelector;
+    /**
+     * Scores how well a candidate's DOM path matches the EID path
+     * Compares tags, classes, attributes, and nthChild positions
+     * @param candidate - Target element candidate
+     * @param anchor - Anchor element
+     * @param eidPath - EID path nodes
+     * @returns Score (higher = better match)
+     */
+    private scorePathMatch;
+    /**
+     * Finds target elements within an anchor by matching semantics
+     */
+    private findTargetWithinAnchor;
+    /**
+     * Disambiguates a parent element by trying attributes, classes, then nth-of-type
+     * Priority: stable attributes > one stable class > nth-of-type
+     * @param element The DOM element to disambiguate
+     * @param tag The tag name
+     * @param pathNode EID path node with semantics (if available)
+     * @param fullPath Current selector path (for uniqueness testing)
+     * @param root Root element for queries
+     * @returns Disambiguated selector part (e.g., "div[role='main']" or "div.sidebar" or "div:nth-of-type(3)")
+     */
+    private disambiguateParent;
+    /**
+     * Builds CSS selector path from anchor to target by traversing actual DOM
+     */
+    private buildPathFromAnchorToTarget;
+    /**
+     * Builds a minimal selector for a DOM element
+     * @param element The DOM element to create a selector for
+     * @returns A minimal CSS selector for the element
+     */
+    private buildElementSelector;
+    /**
+     * Checks if ID is dynamic (generated)
+     */
+    private isDynamicId;
+    /**
+     * Safe querySelectorAll that doesn't throw
+     */
+    private querySelectorSafe;
+    /**
+     * Finds element by matching text content
+     * Returns the matching element (used with getNthSelector for table-aware positioning)
+     */
+    private findNthElementByText;
+    /**
+     * Checks if selector matches exactly one element
+     */
+    private isUnique;
+    /**
+     * Gets nth-of-type index for an element
+     */
+    private getNthOfTypeIndex;
+    /**
+     * FIX 2: Ensures anchor selector is unique in the document
+     * Priority order: tag → tag.class → tag[attr] → tag:nth-of-type(N)
+     * @param eid - Element Identity with anchor information
+     * @param root - Root element for uniqueness check
+     * @returns Unique selector for anchor
+     */
+    private ensureUniqueAnchor;
+    /**
+     * FIX 2: Finds element by matching semantics
+     * @param elements - Array of candidate elements
+     * @param semantics - Semantics to match against
+     * @returns Matching element or null
+     */
+    private findElementBySemantics;
+    /**
+     * FIX 3: Gets nth selector - nth-child for tables, nth-of-type for others
+     * This method is now ACTIVELY INTEGRATED in selector generation logic
+     * to ensure table elements use position-specific nth-child selectors
+     * @param element - Element to get selector for
+     * @param tag - Tag name
+     * @returns nth selector string (e.g., ":nth-child(2)" or ":nth-of-type(2)")
+     */
+    private getNthSelector;
+    /**
+     * Gets attribute priority for sorting
+     * @param attrName - Attribute name
+     * @returns Priority number (higher = more priority)
+     */
+    private getAttributePriority;
+    /**
+     * Checks if attribute should be ignored
+     * @param attrName - Attribute name
+     * @returns True if should be ignored
+     */
+    private shouldIgnoreAttribute;
+    /**
+     * Gets attributes sorted by priority
+     * @param attributes - Attributes object
+     * @returns Sorted array of attributes with priority
+     */
+    private getSortedAttributes;
+    /**
+     * Builds selector for a single node
+     * Priority: ID → semantic attributes → role → classes
+     */
+    private buildNodeSelector;
+    /**
+     * Escapes special characters for CSS selector
+     */
+    private escapeCSS;
+    /**
+     * Escapes quotes for attribute values
+     */
+    private escapeAttr;
+    /**
+     * Checks if element tag is an SVG child element
+     * @param tag - Element tag name
+     * @returns True if element is an SVG child
+     */
+    private isSvgChildElement;
+}
+
+/**
+ * Default generator options
+ * Note: cache is optional and not included in defaults
+ */
+export declare const DEFAULT_GENERATOR_OPTIONS: Omit<Required<GeneratorOptions>, 'cache'> & Pick<GeneratorOptions, 'cache'>;
+
+/**
+ * Default resolver options
+ */
+export declare const DEFAULT_RESOLVER_OPTIONS: Required<ResolverOptions>;
+
+/**
+ * EID specification version
+ */
+export declare const EID_VERSION: EIDVersion;
+
+/**
+ * EID Cache for multi-level caching
+ * Provides caching for:
+ * - Complete EID identities (WeakMap)
+ * - Selector query results (LRU Map)
+ * - Anchor finder results (WeakMap)
+ * - Semantic extraction results (WeakMap)
+ */
+export declare class EIDCache {
+    private eidCache;
+    private selectorResultCache;
+    private anchorCache;
+    private semanticsCache;
+    private stats;
+    constructor(options?: EIDCacheOptions);
+    /**
+     * Get cached EID for element
+     */
+    getEID(element: Element): ElementIdentity | undefined;
+    /**
+     * Cache EID for element
+     */
+    setEID(element: Element, eid: ElementIdentity): void;
+    /**
+     * Get cached selector results
+     */
+    getSelectorResults(selector: string): Element[] | undefined;
+    /**
+     * Cache selector results
+     */
+    setSelectorResults(selector: string, results: Element[]): void;
+    /**
+     * Get cached anchor result
+     */
+    getAnchor(element: Element): AnchorResult | null | undefined;
+    /**
+     * Cache anchor result
+     */
+    setAnchor(element: Element, result: AnchorResult | null): void;
+    /**
+     * Get cached semantics
+     */
+    getSemantics(element: Element): ElementSemantics | undefined;
+    /**
+     * Cache semantics
+     */
+    setSemantics(element: Element, semantics: ElementSemantics): void;
+    /**
+     * Clear all caches
+     */
+    clear(): void;
+    /**
+     * Invalidate cache for a specific element
+     * Note: WeakMaps don't support deletion, but we can clear selector cache
+     * if needed. This method is mainly for future extensibility.
+     */
+    invalidateElement(_element: Element): void;
+    /**
+     * Invalidate a specific selector from cache
+     */
+    invalidateSelector(selector: string): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get cache hit rate for EID cache
+     */
+    getEIDHitRate(): number;
+    /**
+     * Get cache hit rate for selector cache
+     */
+    getSelectorHitRate(): number;
+    /**
+     * Get cache hit rate for anchor cache
+     */
+    getAnchorHitRate(): number;
+    /**
+     * Get cache hit rate for semantics cache
+     */
+    getSemanticsHitRate(): number;
+    /**
+     * Get overall cache hit rate
+     */
+    getOverallHitRate(): number;
+}
+
+/**
+ * Options for creating an EID cache
+ */
+export declare interface EIDCacheOptions {
+    /** Maximum size for selector cache (default: 1000) */
+    maxSelectorCacheSize?: number;
+}
+
+/**
+ * EID metadata
+ */
+export declare interface EIDMeta {
+    /** Overall confidence score 0-1 */
+    confidence: number;
+    /** ISO timestamp when generated */
+    generatedAt: string;
+    /** Generator identifier */
+    generator: string;
+    /** Source context (e.g., 'rrweb-recorder') */
+    source: string;
+    /** Whether EID is degraded quality */
+    degraded: boolean;
+    /** Reason for degradation if degraded */
+    degradationReason?: string;
+}
+
+/**
+ * EID version string
+ */
+export declare type EIDVersion = '1.0';
+
+/**
+ * Main Element Identity Descriptor (EID) structure - describes "what" an element is
+ * Following SPECIFICATION.md §14
+ */
+export declare interface ElementIdentity {
+    /** EID specification version */
+    version: EIDVersion;
+    /** Semantic root/context for the path */
+    anchor: AnchorNode;
+    /** Semantic path from anchor to target's parent */
+    path: PathNode[];
+    /** The target element description */
+    target: TargetNode;
+    /** Disambiguation constraints (applied during resolution) */
+    constraints: Constraint[];
+    /** Fallback behavior rules */
+    fallback: FallbackRules;
+    /** Metadata about generation */
+    meta: EIDMeta;
+}
+
+/**
+ * Semantic features for an EID node
+ * Following SPECIFICATION.md §10
+ */
+export declare interface ElementSemantics {
+    /** Stable ID (not dynamic) */
+    id?: string;
+    /** Semantic class names (utility classes filtered out) */
+    classes?: string[];
+    /** Relevant attributes (aria-*, name, type, role, etc.) */
+    attributes?: Record<string, string>;
+    /** Text content */
+    text?: TextContent;
+    /** SVG fingerprint (for SVG elements) */
+    svg?: SvgFingerprint;
+    /** ARIA role */
+    role?: string;
+}
+
+/**
+ * Handles resolution fallback scenarios
+ * Following SPECIFICATION.md §13.5
+ */
+export declare class FallbackHandler {
+    private cssGenerator;
+    constructor();
+    /**
+     * Handles fallback when resolution fails
+     * @param eid - Element Identity being resolved
+     * @param dom - Document or element to search in
+     * @returns Fallback resolution result
+     */
+    handleFallback(eid: ElementIdentity, dom: Document | Element): ResolveResult;
+    /**
+     * Attempts to find and return the anchor element as fallback
+     */
+    private fallbackToAnchor;
+    /**
+     * Handles ambiguous results (multiple matches)
+     * @param elements - All matching elements
+     * @param eid - Original Element Identity
+     * @returns Resolution result based on fallback rules
+     */
+    handleAmbiguous(elements: Element[], eid: ElementIdentity): ResolveResult;
+    /**
+     * Selects the best-scoring element from candidates
+     * Re-scores each element based on semantic match quality
+     */
+    private selectBestScoring;
+    /**
+     * Scores how well an element matches the target semantics
+     * @returns Score from 0 to 1
+     */
+    private scoreElementMatch;
+}
+
+/**
+ * Fallback rules for resolution
+ * Following SPECIFICATION.md §13.5
+ */
+export declare interface FallbackRules {
+    /** Behavior when multiple elements match */
+    onMultiple: 'allow-multiple' | 'best-score' | 'first';
+    /** Behavior when target is not found */
+    onMissing: 'anchor-only' | 'strict' | 'none';
+    /** Maximum depth for fallback search */
+    maxDepth: number;
+}
+
+/**
+ * Filters classes into semantic and utility
+ * Uses class-classifier for improved detection
+ * @param classes - Array of class names
+ * @returns Object with semantic and utility arrays
+ */
+export declare function filterClasses(classes: string[]): {
+    semantic: string[];
+    utility: string[];
+};
+
+/**
+ * Generates EID (Element Identity) for a DOM element
+ * Following SPECIFICATION.md §7-11
+ *
+ * @param target - Target DOM element
+ * @param options - Generation options
+ * @returns Element identity or null if generation failed
+ */
+export declare function generateEID(target: Element, options?: GeneratorOptions): ElementIdentity | null;
+
+/**
+ * Generate EID for all elements matching criteria
+ */
+export declare function generateEIDBatch(options?: BatchGeneratorOptions): BatchResult;
+
+/**
+ * Generate EID for specific elements
+ */
+export declare function generateEIDForElements(elements: Element[], options?: Omit<BatchGeneratorOptions, 'root' | 'filter'>): BatchResult;
+
+/**
+ * Generate SEQL Selector directly from DOM element
+ *
+ * This is a convenience function that combines generateEID() and stringifySEQL().
+ *
+ * @param element - Target DOM element
+ * @param generatorOptions - Optional generation options
+ * @param stringifyOptions - Optional stringify options
+ * @returns SEQL Selector (canonical string)
+ *
+ * @example
+ * ```typescript
+ * const button = document.querySelector('.submit-button');
+ * const selector = generateSEQL(button);
+ * // "v1: form :: div.actions > button[type="submit",text="Submit Order"]"
+ *
+ * // Send to analytics
+ * gtag('event', 'click', { element_selector: selector });
+ * ```
+ */
+export declare function generateSEQL(element: Element, generatorOptions?: GeneratorOptions, stringifyOptions?: StringifyOptions): string | null;
+
+/**
+ * Generator options
+ * Following SPECIFICATION.md §7-8
+ */
+export declare interface GeneratorOptions {
+    /** Maximum path depth (default: 10) */
+    maxPathDepth?: number;
+    /** Enable SVG fingerprinting (default: true) */
+    enableSvgFingerprint?: boolean;
+    /** Minimum confidence to return EID (default: 0.3) */
+    confidenceThreshold?: number;
+    /** Fallback to body if no anchor found (default: true) */
+    fallbackToBody?: boolean;
+    /** Include utility classes in EID (default: false) */
+    includeUtilityClasses?: boolean;
+    /** Source identifier for metadata */
+    source?: string;
+    /** Optional cache instance for performance optimization */
+    cache?: EIDCache;
+}
+
+/**
+ * Scores a class for semantic value
+ * Uses class-classifier for improved scoring
+ * @param className - Class name to score
+ * @returns Score from 0 to 1
+ */
+export declare function getClassScore(className: string): number;
+
+/**
+ * Get or create the global default cache
+ */
+export declare function getGlobalCache(): EIDCache;
+
+/**
+ * Checks if a value is a valid ElementIdentity object
+ * @param value - Value to check
+ * @returns True if valid ElementIdentity structure
+ */
+export declare function isEID(value: unknown): value is ElementIdentity;
+
+/**
+ * Checks if class is a utility/atomic CSS class
+ * Uses class-classifier for improved detection
+ * @param className - Class name to check
+ * @returns True if utility class
+ */
+export declare function isUtilityClass(className: string): boolean;
+
+/**
+ * Maximum path depth for traversal
+ * Following SPECIFICATION.md §8
+ */
+export declare const MAX_PATH_DEPTH = 10;
+
+/**
+ * Normalizes text for comparison
+ * Following SPECIFICATION.md §11
+ *
+ * - Trims whitespace
+ * - Collapses multiple spaces
+ * - Replaces newlines/tabs with spaces
+ */
+export declare function normalizeText(text: string | null | undefined): string;
+
+/**
+ * Parses SEQL Selector back to EID structure
+ *
+ * @param selector - SEQL Selector string (similar to CSS Selector)
+ * @returns Element Identity Descriptor
+ * @throws {Error} if SEQL Selector is malformed or version unsupported
+ *
+ * @example
+ * ```typescript
+ * const selector = "v1: footer :: ul > li#3 > a[href='/contact']";
+ * const eid = parseSEQL(selector);
+ * const elements = resolve(eid, document);
+ * ```
+ */
+export declare function parseSEQL(selector: string): ElementIdentity;
+
+/**
+ * Builds semantic path from anchor to target
+ * Following SPECIFICATION.md §8
+ */
+export declare class PathBuilder {
+    private maxDepth;
+    private cache?;
+    constructor(options: GeneratorOptions, cache?: EIDCache);
+    /**
+     * Builds path from anchor to target (excluding both)
+     * @param anchor - Anchor element (start)
+     * @param target - Target element (end)
+     * @param extractor - Semantic extractor instance
+     * @returns Path build result with nodes and degradation info
+     */
+    buildPath(anchor: Element, target: Element, extractor: SemanticExtractor): PathBuildResult;
+    /**
+     * Legacy method for backward compatibility
+     */
+    buildPathNodes(anchor: Element, target: Element, extractor: SemanticExtractor): PathNode[];
+    /**
+     * Ensures path uniqueness by adding nodes if needed
+     * Following SPECIFICATION.md §8 Disambiguation Algorithm
+     */
+    private ensureUniqueness;
+    /**
+     * Inserts node into path maintaining original order
+     */
+    private insertNodeInOrder;
+    /**
+     * Builds a test CSS selector from path
+     */
+    private buildTestSelector;
+    /**
+     * Converts element to basic CSS selector
+     */
+    private elementToSelector;
+    /**
+     * Filters out noise/layout elements
+     */
+    private filterNoise;
+    /**
+     * Determines if element should be included in path
+     */
+    shouldInclude(element: Element): boolean;
+    /**
+     * Checks if element has meaningful semantic features
+     */
+    private hasSemanticFeatures;
+}
+
+/**
+ * Result of path building including degradation info
+ */
+declare interface PathBuildResult {
+    path: PathNode[];
+    degraded: boolean;
+    degradationReason?: string;
+}
+
+/**
+ * Path node - intermediate element in the path
+ * Following SPECIFICATION.md §8
+ */
+export declare interface PathNode {
+    /** HTML tag name (lowercase) */
+    tag: string;
+    /** Semantic features */
+    semantics: ElementSemantics;
+    /** Quality score 0-1 */
+    score: number;
+    /** Position among siblings (1-based, for nth-child CSS selector) */
+    nthChild?: number;
+}
+
+/**
+ * Position constraint (degraded fallback)
+ */
+export declare interface PositionConstraint extends Constraint {
+    type: 'position';
+    params: {
+        strategy: 'top-most' | 'left-most' | 'first-in-dom';
+    };
+}
+
+/**
+ * Reset the global cache
+ */
+export declare function resetGlobalCache(): void;
+
+/**
+ * Resolves Element Identity back to DOM element(s)
+ * Following SPECIFICATION.md §13 (5-phase algorithm)
+ *
+ * @param eid - Element Identity to resolve
+ * @param dom - Document or root element to search in
+ * @param options - Resolver options
+ * @returns Resolution result with matched elements
+ */
+export declare function resolve(eid: ElementIdentity, dom: Document | Element, options?: ResolverOptions): ResolveResult;
+
+/**
+ * Resolve result
+ */
+export declare interface ResolveResult {
+    /** Resolution status */
+    status: ResolveStatus;
+    /** Matched elements (0, 1, or multiple) */
+    elements: Element[];
+    /** Warning messages */
+    warnings: string[];
+    /** Confidence score of match */
+    confidence: number;
+    /** Metadata about resolution */
+    meta: {
+        degraded: boolean;
+        degradationReason?: string;
+    };
+}
+
+/**
+ * Resolver options
+ * Following SPECIFICATION.md §13
+ */
+export declare interface ResolverOptions {
+    /** Strict mode: fail on ambiguity (default: false) */
+    strictMode?: boolean;
+    /** Enable fallback mechanisms (default: true) */
+    enableFallback?: boolean;
+    /** Maximum candidates to consider (default: 20) */
+    maxCandidates?: number;
+}
+
+/**
+ * Resolve SEQL Selector directly to DOM elements
+ *
+ * This is a convenience function that combines parseSEQL() and resolve().
+ *
+ * @param selector - SEQL Selector string
+ * @param root - Root element or document to search in
+ * @param options - Optional resolver options
+ * @returns Array of matched elements (empty if not found)
+ *
+ * @example
+ * ```typescript
+ * // Parse SEQL Selector from analytics
+ * const selector = "v1: form :: button.submit";
+ * const elements = resolveSEQL(selector, document);
+ *
+ * if (elements.length > 0) {
+ *   highlightElement(elements[0]);
+ * }
+ * ```
+ */
+export declare function resolveSEQL(selector: string, root: Document | Element, options?: ResolverOptions): Element[];
+
+/**
+ * Resolution status
+ * Following SPECIFICATION.md §13.5
+ */
+export declare type ResolveStatus = 'success' | 'ambiguous' | 'error' | 'degraded-fallback';
+
+/**
+ * Tier B role values for anchor detection
+ * Following SPECIFICATION.md §7
+ */
+export declare const ROLE_ANCHOR_VALUES: string[];
+
+/**
+ * Tier A semantic anchor tags - highest priority
+ * Following SPECIFICATION.md §7
+ */
+export declare const SEMANTIC_ANCHOR_TAGS: string[];
+
+/**
+ * Semantic attributes to extract
+ */
+export declare const SEMANTIC_ATTRIBUTES: string[];
+
+/**
+ * All semantic tags to include in path
+ * Following SPECIFICATION.md §8
+ */
+export declare const SEMANTIC_TAGS: string[];
+
+/**
+ * Extracts semantic features from DOM elements
+ * Following SPECIFICATION.md §10
+ */
+export declare class SemanticExtractor {
+    private includeUtilityClasses;
+    private cache?;
+    constructor(options: GeneratorOptions, cache?: EIDCache);
+    /**
+     * Extracts semantic features from element
+     * @param element - DOM element to extract from
+     * @returns Semantic features object
+     */
+    extract(element: Element): ElementSemantics;
+    /**
+     * Scores element based on semantic richness
+     * @param element - Element to score
+     * @returns Score from 0 to 1
+     */
+    scoreElement(element: Element): number;
+    /**
+     * Checks if attribute should be ignored
+     * @param attrName - Attribute name
+     * @returns True if should be ignored
+     */
+    private shouldIgnoreAttribute;
+    /**
+     * Gets attribute priority
+     * @param attrName - Attribute name
+     * @returns Priority number (higher = more priority)
+     */
+    private getAttributePriority;
+    /**
+     * Checks if attribute value is dynamic (should be ignored)
+     * @param value - Attribute value
+     * @returns True if value is dynamic
+     */
+    private isDynamicValue;
+    /**
+     * Extracts relevant semantic attributes from element
+     * Iterates through all attributes and filters by priority
+     */
+    private extractAttributes;
+    /**
+     * Extracts and normalizes text content
+     */
+    private extractText;
+    /**
+     * Gets direct text content excluding child elements
+     */
+    private getDirectTextContent;
+    /**
+     * Determines if text should be extracted for this element
+     */
+    private shouldExtractText;
+}
+
+/**
+ * Filters elements by semantic criteria
+ * Following SPECIFICATION.md §13.2
+ */
+export declare class SemanticsMatcher {
+    /**
+     * Filters elements that match the semantics
+     * @param elements - Candidate elements
+     * @param semantics - Target semantics to match
+     * @returns Filtered elements that match
+     */
+    match(elements: Element[], semantics: ElementSemantics): Element[];
+    /**
+     * Checks if a single element matches the semantics
+     */
+    private matchElement;
+    /**
+     * Matches text content
+     * Prioritizes direct text nodes, but falls back to full textContent if no direct text
+     */
+    matchText(element: Element, text: TextContent): boolean;
+    /**
+     * Matches attributes
+     */
+    matchAttributes(element: Element, attrs: Record<string, string>): boolean;
+    /**
+     * Matches SVG fingerprint
+     */
+    matchSvgFingerprint(element: SVGElement, fingerprint: SvgFingerprint): boolean;
+    /**
+     * Computes simple path hash (matching SvgFingerprinter)
+     */
+    private computePathHash;
+    /**
+     * Computes geometry hash for non-path shapes (matching SvgFingerprinter)
+     */
+    private computeGeomHash;
+    /**
+     * Simple hash function (matching SvgFingerprinter)
+     */
+    private simpleHash;
+}
+
+/**
+ * SEQL Selector - canonical string representation of ElementIdentity
+ * Similar to CSS Selector or XPath, but based on semantic features
+ * @example "v1: footer > div.container > ul > li#3 > svg > rect"
+ */
+export declare type SeqlSelector = string;
+
+/**
+ * Options for SEQL Selector stringification
+ */
+declare interface StringifyOptions {
+    /** Maximum number of classes to include per node (default: 2) */
+    maxClasses?: number;
+    /** Maximum number of attributes to include per node (default: 5) */
+    maxAttributes?: number;
+    /** Include text content as pseudo-attribute (default: true) */
+    includeText?: boolean;
+    /** Maximum text length to include (default: 50) */
+    maxTextLength?: number;
+    /** Simplify target node by removing redundant info (default: true) */
+    simplifyTarget?: boolean;
+    /** Include resolution constraints in SEQL Selector (default: true) */
+    includeConstraints?: boolean;
+}
+
+/**
+ * Converts EID to canonical SEQL Selector string representation
+ *
+ * Requirements (per SEQL_SPECIFICATION_v1.0.md):
+ * - Deterministic (same EID → same SEQL Selector)
+ * - Canonical (one EID → one SEQL Selector)
+ * - Versioned (includes protocol version)
+ * - PII-safe (no personal data)
+ * - Sorted attributes and classes
+ *
+ * @param eid - Element Identity Descriptor
+ * @param options - Optional stringify options
+ * @returns SEQL Selector (canonical string)
+ *
+ * @example
+ * ```typescript
+ * const eid = generateEID(element);
+ * const selector = stringifySEQL(eid);
+ * // "v1: footer :: ul.menu > li#3 > a[href="/contact"]"
+ * ```
+ */
+export declare function stringifySEQL(eid: ElementIdentity, options?: StringifyOptions): string;
+
+/**
+ * SVG element fingerprint for stable identification
+ * Following SPECIFICATION.md §9
+ */
+export declare interface SvgFingerprint {
+    /** SVG shape type */
+    shape: 'path' | 'circle' | 'rect' | 'line' | 'polyline' | 'polygon' | 'ellipse' | 'g' | 'text' | 'use' | 'svg';
+    /** Hash of path data (first N commands) for <path> elements */
+    dHash?: string;
+    /** Geometry hash for non-path shapes */
+    geomHash?: string;
+    /** Whether element has animations */
+    hasAnimation: boolean;
+    /** ARIA role if present */
+    role?: string;
+    /** <title> text inside SVG */
+    titleText?: string;
+}
+
+/**
+ * Generates stable fingerprints for SVG elements
+ * Following SPECIFICATION.md §9
+ */
+export declare class SvgFingerprinter {
+    /**
+     * Generates fingerprint for SVG element
+     * @param element - SVG element to fingerprint
+     * @returns SVG fingerprint object
+     */
+    fingerprint(element: SVGElement): SvgFingerprint;
+    /**
+     * Computes hash from path data (first N commands)
+     * @param d - SVG path d attribute value
+     * @returns Hash string
+     */
+    computePathHash(d: string): string;
+    /**
+     * Gets the shape type from tag name
+     */
+    private getShape;
+    /**
+     * Normalizes path data for consistent hashing
+     */
+    private normalizePathData;
+    /**
+     * Computes geometry hash for non-path shapes
+     */
+    private computeGeomHash;
+    /**
+     * Detects animations on SVG element
+     */
+    hasAnimation(element: SVGElement): boolean;
+    /**
+     * Simple hash function for fingerprinting (not cryptographic)
+     */
+    private simpleHash;
+}
+
+/**
+ * Target node - the element being identified
+ */
+export declare interface TargetNode extends PathNode {
+}
+
+/**
+ * Text content with normalization
+ * Following SPECIFICATION.md §11
+ */
+export declare interface TextContent {
+    /** Original text (for debugging) */
+    raw: string;
+    /** Normalized text (trimmed, collapsed whitespace) */
+    normalized: string;
+    /** Matching mode for text comparison */
+    matchMode?: 'exact' | 'partial';
+}
+
+/**
+ * Text proximity constraint (Levenshtein distance)
+ */
+export declare interface TextProximityConstraint extends Constraint {
+    type: 'text-proximity';
+    params: {
+        reference: string;
+        maxDistance: number;
+    };
+}
+
+/**
+ * Uniqueness constraint
+ */
+export declare interface UniquenessConstraint extends Constraint {
+    type: 'uniqueness';
+    params: {
+        mode: 'strict' | 'best-score' | 'allow-multiple';
+    };
+}
+
+/**
+ * Validates EID structure for correctness
+ * @param eid - The Element Identity to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateEID(eid: ElementIdentity): ValidationResult;
+
+/**
+ * Validation result
+ */
+export declare interface ValidationResult {
+    /** Whether DSL is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+}
+
+export { }