@whenessel/seql-js 1.4.0 → 1.5.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'> & Pick<ResolverOptions, 'root'>;
 
 /**
  * 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,21 @@ 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;
 }
 
 /**
@@ -985,6 +1015,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[];
 
@@ -1095,6 +1140,19 @@ export declare class SemanticsMatcher {
      * Prioritizes direct text nodes, but falls back to full textContent if no direct text
      */
     matchText(element: Element, text: TextContent): boolean;
+    /**
+     * 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
+     */
+    private matchElementLenient;
+    /**
+     * Filters elements with lenient matching (exported for use in resolver)
+     */
+    matchLenient(elements: Element[], semantics: ElementSemantics): Element[];
     /**
      * Matches attributes
      */