@whenessel/seql-js 1.5.0 → 1.6.0

package/dist/seql-js.d.ts

@@ -457,7 +457,7 @@ export declare const DEFAULT_GENERATOR_OPTIONS: Omit<Required<GeneratorOptions>,
 /**
  * Default resolver options
  */
-export declare const DEFAULT_RESOLVER_OPTIONS: Omit<Required<ResolverOptions>, 'root'> & Pick<ResolverOptions, 'root'>;
+export declare const DEFAULT_RESOLVER_OPTIONS: Omit<Required<ResolverOptions>, 'root' | 'documentUrl'> & Pick<ResolverOptions, 'root' | 'documentUrl'>;
 
 /**
  * EID specification version
@@ -993,6 +993,48 @@ export declare interface ResolverOptions {
      * 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;
 }
 
 /**
@@ -1128,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;
     /**
@@ -1147,16 +1193,22 @@ export declare class SemanticsMatcher {
     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): Element[];
+    matchLenient(elements: Element[], semantics: ElementSemantics, documentUrl?: string, matchUrlsByPathOnly?: boolean): Element[];
     /**
-     * Matches attributes
+     * 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
      */