npm - @whenessel/seql-js - Versions diffs - 1.1.0 → 1.2.0 - Mend

@whenessel/seql-js 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -97,27 +97,35 @@ Resolution: EID → resolve() → ResolveResult
 ### SEQL Selector Functions
 #### `generateSEQL(element, generatorOptions?, stringifyOptions?)`
 Convenience function: `generateEID` + `stringifySEQL`. Returns a string or `null`.
 #### `resolveSEQL(selector, root, options?)`
 Convenience function: `parseSEQL` + `resolve`. Returns `Element[]`.
 #### `parseSEQL(selector)`
 Parses a SEQL Selector into an `ElementIdentity` object.
 #### `stringifySEQL(eid, options?)`
 Converts an `ElementIdentity` object into a canonical SEQL Selector.
 ### Core Functions
 #### `generateEID(element, options?)`
 Generates an `ElementIdentity` (EID) from a DOM element.
 - `maxPathDepth`: Default 10.
 - `enableSvgFingerprint`: Default true.
 - `confidenceThreshold`: Default 0.1.
 #### `resolve(eid, root, options?)`
 Resolves an EID back to DOM element(s). Returns a `ResolveResult` object.
 - `status`: `'success' | 'ambiguous' | 'error' | 'degraded-fallback'`.
 - `elements`: `Element[]` of matches.
 - `confidence`: Match confidence score (0-1).
@@ -125,9 +133,11 @@ Resolves an EID back to DOM element(s). Returns a `ResolveResult` object.
 ### Utilities & Advanced
 #### `generateEIDBatch(elements, options?)`
 Optimized generation for multiple elements at once.
 #### `createEIDCache(options?)` / `getGlobalCache()`
 Manage the LRU cache to improve performance for frequent generations/resolutions.
 ## Project Structure
@@ -148,14 +158,20 @@ Manage the LRU cache to improve performance for frequent generations/resolutions
 ## Documentation
-- [Architecture Design](docs/specs/ARCHITECTURE.md)
-- [EID Specification v1.0](docs/specs/SPECIFICATION.md) (Russian)
-- [Developer Guidelines](CLAUDE.md)
-- [Migration Guide](docs/MIGRATION.md)
+- **[Getting Started](docs/getting-started/)** - Installation and quick start guide
+- **[API Reference](docs/api/)** - Complete API documentation
+- **[Examples](docs/examples/)** - Practical code examples
+- **[Specification](docs/specification/)** - EID and SEQL format specifications
+- **[Architecture](docs/architecture/)** - System design and internals
+- **[Guides](docs/guides/)** - Advanced topics and patterns
+- **[Contributing](docs/contributing/)** - Development guide
+- **[Troubleshooting](docs/troubleshooting/)** - Common issues and solutions
+- **[CLAUDE.md](CLAUDE.md)** - AI agent development guidelines
 ## Migrating from v0.x
 If you are upgrading from v0.x, note these breaking changes:
 - `generateDsl()` → `generateEID()`
 - `resolveDsl()` → `resolve()`
 - `DslIdentity` → `ElementIdentity`

package/dist/seql-js.d.ts CHANGED Viewed

@@ -11,6 +11,11 @@ export declare class AnchorFinder {
      * Finds the best anchor element for the target
      * @param target - Target element to find anchor for
      * @returns Anchor result or null if not found
+     * @remarks
+     * Special handling for root elements (html, head, body):
+     * - For html: returns html itself as anchor
+     * - For head or elements inside head: returns html as anchor
+     * - For body: returns html as anchor
      */
     findAnchor(target: Element): AnchorResult | null;
     /**
@@ -28,6 +33,25 @@ export declare class AnchorFinder {
      * Determines the tier of an anchor element
      */
     private getTier;
+    /**
+     * Checks if element is inside <head> section.
+     * Stops at <body> to avoid false positives.
+     * @param element - Element to check
+     * @returns True if element is inside head, false otherwise
+     * @remarks
+     * Traverses up the DOM tree until finding head or body.
+     * Returns false if body is encountered first.
+     * @example
+     * const meta = document.querySelector('meta');
+     * if (isInsideHead(meta)) { ... }
+     */
+    private isInsideHead;
+    /**
+     * Caches the anchor result for the target element
+     * @param target - Target element
+     * @param result - Anchor result to cache
+     */
+    private cacheResult;
 }
 /**
@@ -400,6 +424,20 @@ export declare class CssGenerator {
      * @returns True if element is an SVG child
      */
     private isSvgChildElement;
+    /**
+     * Builds CSS selector for elements inside <head>.
+     * Uses child combinator (>) for strict structure: html > head > ... > target
+     * @param eid - Element Identity with anchor=html and path[0]=head
+     * @param options - Optional uniqueness control settings
+     * @returns CSS selector string or BuildSelectorResult
+     * @remarks
+     * This method handles the special case where elements are inside <head>.
+     * The selector always uses child combinators for strict parent-child relationships.
+     * @example
+     * For <html><head><meta name="description"></head></html>
+     * Returns: "html > head > meta[name='description']"
+     */
+    private buildHeadSelector;
 }
 /**
@@ -774,6 +812,10 @@ export declare class PathBuilder {
      * @param target - Target element (end)
      * @param extractor - Semantic extractor instance
      * @returns Path build result with nodes and degradation info
+     * @remarks
+     * Special handling for root elements:
+     * - If anchor is html and target is head/body: returns empty path
+     * - If anchor is html and target is inside head: builds path through head
      */
     buildPath(anchor: Element, target: Element, extractor: SemanticExtractor): PathBuildResult;
     /**
@@ -809,6 +851,28 @@ export declare class PathBuilder {
      * Checks if element has meaningful semantic features
      */
     private hasSemanticFeatures;
+    /**
+     * Checks if element is inside <head> section.
+     * Stops at <body> to avoid false positives.
+     * @param element - Element to check
+     * @returns True if element is inside head, false otherwise
+     * @remarks
+     * Traverses up the DOM tree until finding head or body.
+     * Returns false if body is encountered first.
+     */
+    private isInsideHead;
+    /**
+     * Builds path from html to target through head element.
+     * Always includes head in the path for correct CSS selector generation.
+     * @param htmlElement - The html element (anchor)
+     * @param target - Target element inside head
+     * @param extractor - Semantic extractor instance
+     * @returns Path build result with head and intermediate nodes
+     * @example
+     * For <html><head><meta name="description"></head></html>
+     * Returns path: [head]
+     */
+    private buildHeadPath;
 }
 /**
@@ -1154,8 +1218,7 @@ export declare class SvgFingerprinter {
 /**
  * Target node - the element being identified
  */
-export declare interface TargetNode extends PathNode {
-}
+export declare type TargetNode = PathNode;
 /**
  * Text content with normalization