@whenessel/seql-js 1.4.0 → 1.6.0

package/README.md

@@ -146,6 +146,30 @@ Manage the LRU cache to improve performance for frequent generations/resolutions
 - `src/resolver/`: Logic for resolving EID JSON back to DOM elements.
 - `src/types/`: Core type definitions for EIDs, Semantics, and Constraints.
 - `src/utils/`: Shared utilities, constants, and scoring algorithms.
+- `extensions/chrome/`: Chrome DevTools extension for visual SEQL inspection.
+
+## Developer Tools
+
+### Chrome DevTools Extension
+
+The SEQL Inspector extension provides visual tooling for working with SEQL selectors directly in Chrome DevTools.
+
+**Features:**
+
+- Generate SEQL selectors for all elements or pick individual elements
+- Full iframe support with automatic detection and context switching
+- Live search and resolution testing
+- Interactive element highlighting and inspection
+- Tree view with grouping and filtering
+
+**Installation:**
+
+```bash
+yarn extension:prepare
+# Then load extensions/chrome/ as unpacked extension in Chrome
+```
+
+See [Chrome Extension README](extensions/chrome/README.md) for detailed documentation.
 
 ## Scripts
 
@@ -154,6 +178,7 @@ Manage the LRU cache to improve performance for frequent generations/resolutions
 - `yarn test:watch`: Run tests in watch mode.
 - `yarn test:coverage`: Run tests with coverage report.
 - `yarn types:check`: Run TypeScript type checking.
+- `yarn extension:prepare`: Build library and prepare Chrome extension.
 - `npx vitest <path>`: Run a specific test file.
 
 ## Documentation

package/dist/seql-js.d.ts

@@ -452,12 +452,12 @@ export declare class CssGenerator {
  * div with utility classes) can still be identified using positional information
  * (nthChild).
  */
-export declare const DEFAULT_GENERATOR_OPTIONS: Omit<Required<GeneratorOptions>, 'cache'> & Pick<GeneratorOptions, 'cache'>;
+export declare const DEFAULT_GENERATOR_OPTIONS: Omit<Required<GeneratorOptions>, 'cache' | 'root'> & Pick<GeneratorOptions, 'cache' | 'root'>;
 
 /**
  * Default resolver options
  */
-export declare const DEFAULT_RESOLVER_OPTIONS: Required<ResolverOptions>;
+export declare const DEFAULT_RESOLVER_OPTIONS: Omit<Required<ResolverOptions>, 'root' | 'documentUrl'> & Pick<ResolverOptions, 'root' | 'documentUrl'>;
 
 /**
  * EID specification version
@@ -744,6 +744,21 @@ export declare interface GeneratorOptions {
     source?: string;
     /** Optional cache instance for performance optimization */
     cache?: EIDCache;
+    /**
+     * Root element or document for validation (optional).
+     *
+     * ⚠️ IMPORTANT: When working with iframes, pass iframe.contentDocument
+     * to ensure cross-document validation works correctly.
+     *
+     * @example
+     * // Main document
+     * generateEID(element, { root: document });
+     *
+     * // Iframe content
+     * const iframe = document.querySelector('iframe');
+     * generateEID(iframeElement, { root: iframe.contentDocument });
+     */
+    root?: Document | Element;
 }
 
 /**
@@ -948,7 +963,7 @@ export declare interface ResolveResult {
     /** Metadata about resolution */
     meta: {
         degraded: boolean;
-        degradationReason?: string;
+        degradationReason?: 'not-found' | 'strict-not-found' | 'ambiguous' | 'anchor-fallback' | 'anchor-not-found' | 'first-of-multiple' | 'best-of-multiple' | 'multiple-matches' | 'over-constrained' | 'relaxed-text-matching' | 'invalid-context' | 'invalid-selector' | 'invalid-anchor-selector';
     };
 }
 
@@ -963,6 +978,63 @@ export declare interface ResolverOptions {
     enableFallback?: boolean;
     /** Maximum candidates to consider (default: 20) */
     maxCandidates?: number;
+    /**
+     * Root element or document for CSS queries.
+     *
+     * ⚠️ IMPORTANT: When working with iframes, you MUST pass iframe.contentDocument
+     * as the root parameter. Otherwise, resolution will fail or return incorrect elements.
+     *
+     * @example
+     * // Main document
+     * resolve(eid, document, { root: document });
+     *
+     * // Iframe content
+     * const iframe = document.querySelector('iframe');
+     * resolve(eid, iframe.contentDocument, { root: iframe.contentDocument });
+     */
+    root?: Document | Element;
+    /**
+     * Document base URL for URL normalization.
+     * Used when comparing href/src attributes to provide correct origin context.
+     *
+     * ⚠️ IMPORTANT: When working with iframes, this should match iframe.contentWindow.location.href
+     * to ensure correct same-origin detection.
+     *
+     * If not provided, falls back to root.defaultView?.location?.href or window.location.href.
+     *
+     * @example
+     * // Iframe context
+     * const iframe = document.querySelector('iframe');
+     * resolve(eid, iframe.contentDocument, {
+     *   root: iframe.contentDocument,
+     *   documentUrl: iframe.contentWindow.location.href
+     * });
+     *
+     * @example
+     * // Manual override for testing
+     * resolve(eid, document, {
+     *   documentUrl: 'https://example.com'
+     * });
+     */
+    documentUrl?: string;
+    /**
+     * Match URLs by pathname only, ignoring origin differences.
+     * Useful for cross-origin rrweb replay scenarios (e.g., localhost dev with production links).
+     *
+     * When enabled (default):
+     * - /booking matches https://any-origin.com/booking
+     * - Ignores protocol and domain differences
+     * - Compares only pathname (+ search + hash if present)
+     * - Recommended for rrweb replay and development environments
+     *
+     * When disabled:
+     * - Full URL normalization with same-origin detection
+     * - Cross-origin URLs preserved as absolute
+     * - More strict origin validation
+     *
+     * @default true
+     */
+    matchUrlsByPathOnly?: boolean;
 }
 
 /**
@@ -985,6 +1057,21 @@ export declare interface ResolverOptions {
  *   highlightElement(elements[0]);
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Working with iframes - pass iframe.contentDocument as both root and in options
+ * const iframe = document.querySelector('iframe');
+ * const iframeDoc = iframe.contentDocument;
+ * const selector = "v1: form#payment :: input[name=cardnumber]";
+ *
+ * // IMPORTANT: Pass contentDocument as root in options for correct resolution
+ * const elements = resolveSEQL(selector, iframeDoc, { root: iframeDoc });
+ *
+ * if (elements.length > 0) {
+ *   console.log('Found payment input in iframe:', elements[0]);
+ * }
+ * ```
  */
 export declare function resolveSEQL(selector: string, root: Document | Element, options?: ResolverOptions): Element[];
 
@@ -1083,11 +1170,15 @@ export declare class SemanticsMatcher {
      * Filters elements that match the semantics
      * @param elements - Candidate elements
      * @param semantics - Target semantics to match
+     * @param documentUrl - Optional document base URL for URL normalization (iframe context)
+     * @param matchUrlsByPathOnly - Optional flag to match URLs by pathname only (ignoring origin)
      * @returns Filtered elements that match
      */
-    match(elements: Element[], semantics: ElementSemantics): Element[];
+    match(elements: Element[], semantics: ElementSemantics, documentUrl?: string, matchUrlsByPathOnly?: boolean): Element[];
     /**
      * Checks if a single element matches the semantics
+     * @param documentUrl - Optional document base URL for URL normalization (iframe context)
+     * @param matchUrlsByPathOnly - Optional flag to match URLs by pathname only (ignoring origin)
      */
     private matchElement;
     /**
@@ -1096,9 +1187,28 @@ export declare class SemanticsMatcher {
      */
     matchText(element: Element, text: TextContent): boolean;
     /**
-     * Matches attributes
+     * Lenient text matching - uses partial matching instead of exact
+     * Used as fallback when exact matching fails
+     */
+    private matchTextLenient;
+    /**
+     * Checks if a single element matches the semantics with lenient text matching
+     * @param documentUrl - Optional document base URL for URL normalization (iframe context)
+     * @param matchUrlsByPathOnly - Optional flag to match URLs by pathname only (ignoring origin)
+     */
+    private matchElementLenient;
+    /**
+     * Filters elements with lenient matching (exported for use in resolver)
+     * @param documentUrl - Optional document base URL for URL normalization (iframe context)
+     * @param matchUrlsByPathOnly - Optional flag to match URLs by pathname only (ignoring origin)
+     */
+    matchLenient(elements: Element[], semantics: ElementSemantics, documentUrl?: string, matchUrlsByPathOnly?: boolean): Element[];
+    /**
+     * Matches attributes with URL normalization for href/src
+     * @param documentUrl - Optional document base URL for URL normalization (iframe context)
+     * @param matchUrlsByPathOnly - Optional flag to match URLs by pathname only (ignoring origin, default: true)
      */
-    matchAttributes(element: Element, attrs: Record<string, string>): boolean;
+    matchAttributes(element: Element, attrs: Record<string, string>, documentUrl?: string, matchUrlsByPathOnly?: boolean): boolean;
     /**
      * Matches SVG fingerprint
      */