@whenessel/seql-js 1.0.2 → 1.1.1

package/README.md

@@ -8,7 +8,8 @@ Semantic Element Query Language (SEQL) - Stable DOM element identification for w
 
 - **Semantic-first**: Uses ARIA roles, labels, semantic HTML tags, and stable attributes.
 - **Resilient**: Designed to be stable across UI updates and DOM changes.
-- **Dual Format**: 
+- **State-independent** (v1.0.3): Filters out state attributes (`aria-selected`, `data-state`, `disabled`) to ensure elements are found regardless of their current state.
+- **Dual Format**:
   - **EID** (JSON): Structured descriptor for internal operations and high precision.
   - **SEQL Selector** (String): Canonical string format for easy transport (analytics) and storage.
 - **Deterministic**: Guaranteed same output for the same DOM state.
@@ -96,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).
@@ -124,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
@@ -147,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

@@ -43,6 +43,8 @@ export declare interface AnchorNode {
     score: number;
     /** Whether this is a degraded/fallback anchor */
     degraded: boolean;
+    /** Position among siblings (1-based, for nth-child CSS selector) */
+    nthChild?: number;
 }
 
 /**
@@ -1152,8 +1154,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