@thomasseanfahey/domq 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# domq
+
+Query DOM relationships, not selectors.
+
+`domq` is a small, ESM-first library for composable DOM traversal (relations) and filtering (predicates) with deterministic ordering and lazy evaluation.
+
+It’s designed for browser extensions, testing tooling, scraping/automation scripts, and any code that needs *relationship-first* DOM queries that don’t fit cleanly into CSS selectors.
+
+## Install
+
+```bash
+npm install domq
+```
+
+## Quick start
+
+```js
+import { dq } from "domq";
+
+const start = document.querySelector("#start");
+
+const primary =
+  dq(start)
+    .closest("[data-card]")
+    .descendants()
+    .where(dq.attr("data-action").eq("primary"))
+    .one();
+
+primary.click();
+```
+
+## Why not just selectors?
+
+Selectors are excellent, but they are string-based and don’t express many *relational* queries cleanly, especially when your query starts from an element and needs multi-step traversal:
+
+- “From this element, go up N ancestors, then traverse siblings, then descend, then pick the first match.”
+- “Find the second ancestor that has at least 3 siblings matching a runtime predicate.”
+- “Traverse across Shadow DOM boundaries (explicitly, not accidentally).”
+
+`domq` gives you a readable pipeline with clear semantics.
+
+## Core concepts
+
+### Relations
+
+Relations transform a set/sequence of elements into another ordered sequence.
+
+Common relations:
+
+- `.self()`
+- `.parent()` / `.ancestors()`
+- `.children()` / `.descendants()`
+- `.siblings()` / `.followingSiblings()` / `.precedingSiblings()`
+- `.closest(selector)`
+- `.find(selector)`
+- `.within(selector)`
+- `.until(predicateOrSelector)`
+
+### Predicates
+
+Predicates are composable tests applied via `.where(...)`.
+
+```js
+dq.attr("data-x").eq("1")
+dq.text().matches(/hello/i)
+dq.value().includes("abc")
+dq.matches("button, a")
+dq.hasClass("active")
+dq.role("dialog")
+```
+
+Combine them:
+
+```js
+const p = dq.and(
+  dq.matches("button"),
+  dq.attr("data-action").eq("primary")
+);
+```
+
+### Selection (terminal operations)
+
+Terminal operations evaluate lazily and can short-circuit:
+
+- `.first()` → `Element | null`
+- `.one()` → `Element` (throws with diagnostics if not exactly 1)
+- `.maybeOne()` → `Element | null` (throws if more than 1)
+- `.at(n)` / `.take(n)` / `.skip(n)` / `.slice(a,b)`
+- `.exists()` / `.count()` / `.toArray()`
+- `.unique()` / `.uniqueBy(fn)`
+
+## Deterministic semantics
+
+- **Ordering** is deterministic and documented in code:
+  - `ancestors()` yields *nearest-first*
+  - `descendants()` yields *document order*
+  - `siblings()` yields *left-to-right DOM order*
+- **Snapshot evaluation**: results reflect the DOM at evaluation time.
+- **Duplicates**: pipelines may include duplicates; use `.unique()` explicitly.
+
+## Budgets (safety valves)
+
+Guard traversal work in large DOMs:
+
+```js
+const el = dq(start)
+  .budget({ maxNodes: 50_000, maxDepth: 100, maxMs: 25 })
+  .descendants()
+  .where(dq.matches("a"))
+  .first();
+```
+
+## Compile reusable queries
+
+Turn a pipeline into a reusable function:
+
+```js
+const getPrimaryCTA = dq.compile(q =>
+  q.closest("[data-card]")
+   .descendants()
+   .where(dq.attr("data-action").eq("primary"))
+   .first()
+);
+
+const cta = getPrimaryCTA(event.target);
+```
+
+## Diagnostics
+
+- `.explain()` returns a readable pipeline description.
+- `.debug(label)` and `.tap(fn)` allow inspection.
+- `.one()` and `.maybeOne()` throw errors that include pipeline context and samples.
+
+## Shadow DOM (optional)
+
+Shadow traversal is explicit via `domq/shadow`.
+
+```js
+import { dq } from "domq";
+import { shadow } from "domq/shadow";
+
+const el = dq(start)
+  .use(shadow)
+  .composedAncestors()
+  .first();
+```
+
+## Extra predicates (optional)
+
+Expensive predicates live in `domq/extra`.
+
+```js
+import { dq } from "domq";
+import { extra } from "domq/extra";
+
+const visibleButtons = dq(document.body)
+  .use(extra)
+  .descendants()
+  .where(dq.matches("button"))
+  .where(dq.visible())
+  .toArray();
+```
+
+## Browser demo (no tooling)
+
+Browsers can’t resolve bare specifiers like `"domq"` without a bundler. For a zero-build demo, use an **import map** pointing at local files.
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "domq": "./src/index.js",
+    "domq/shadow": "./src/shadow.js",
+    "domq/extra": "./src/extra.js"
+  }
+}
+</script>
+<script type="module">
+  import { dq } from "domq";
+  console.log(dq(document.body).descendants().count());
+</script>
+```
+
+Serve the repo directory (modules don’t work reliably over `file://`):
+
+```bash
+npx -y serve .
+# or
+python -m http.server 5173
+```
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build:types
+npm run pack:check
+```
+
+`prepublishOnly` runs tests and emits type declarations to `dist/`.
+
+## License
+
+MIT

package/dist/core/dq.d.ts

@@ -0,0 +1,7 @@
+export function dq(node: any): Query;
+export namespace dq {
+    function all(iterable: any): Query;
+    function compile(builder: any): (start: any, options?: any) => any;
+    function use(plugin: any): void;
+}
+import { Query } from './query.js';

package/dist/core/predicates.d.ts

@@ -0,0 +1,32 @@
+export function predicate(fn: any, describe?: string): any;
+export function and(...preds: any[]): any;
+export function or(...preds: any[]): any;
+export function not(pred: any): any;
+export function attr(name: any): ComparatorBuilder;
+export function data(key: any): ComparatorBuilder;
+export function dataset(key: any): ComparatorBuilder;
+export function text(): ComparatorBuilder;
+export function ownText(): ComparatorBuilder;
+export function value(): ComparatorBuilder;
+export function tag(tagName: any): any;
+export function hasClass(className: any): any;
+export function matches(selector: any): any;
+export function role(roleName: any): any;
+declare class ComparatorBuilder {
+    constructor(kind: any, getter: any);
+    _kind: any;
+    _getter: any;
+    exists(): any;
+    eq(value: any): any;
+    ne(value: any): any;
+    includes(substr: any): any;
+    startsWith(prefix: any): any;
+    endsWith(suffix: any): any;
+    matches(re: any): any;
+    truthy(): any;
+    gt(n: any): any;
+    gte(n: any): any;
+    lt(n: any): any;
+    lte(n: any): any;
+}
+export {};

package/dist/core/query.d.ts

@@ -0,0 +1,44 @@
+export class Query {
+    static from(node: any): Query;
+    static fromAll(iterable: any): Query;
+    static installBaseRelations(relations: any): void;
+    constructor(iterableFactory: any, steps: any);
+    _iterableFactory: any;
+    _steps: any;
+    _budget: {};
+    _debugEnabled: boolean;
+    _debugLabel: any;
+    get(relation: any, ...args: any[]): Query;
+    where(pred: any): Query;
+    not(pred: any): Query;
+    unique(): Query;
+    uniqueBy(keyFn: any): Query;
+    reverse(): Query;
+    budget(budget: any): this;
+    debug(label?: boolean): this;
+    explain(): any;
+    first(): any;
+    exists(): boolean;
+    one(): any;
+    maybeOne(): any;
+    at(n: any): Query;
+    take(n: any): Query;
+    skip(n: any): Query;
+    slice(start: any, end: any): Query;
+    count(): number;
+    toArray(): any[];
+    map(fn: any): any[];
+    _clone(iterableFactory: any, steps: any): Query;
+    _evaluate(): {
+        ctx: {
+            budget: {};
+            debugEnabled: boolean;
+            debugLabel: any;
+            visitedNodes: number;
+            startedAt: number;
+        };
+        iterable: Generator<any, void, unknown>;
+    };
+    _maybeDebug(ctx: any, matchCount: any): void;
+}
+export function checkBudget(ctx: any): void;

package/dist/core/relations.d.ts

@@ -0,0 +1,14 @@
+export const self: any;
+export const parent: any;
+export const ancestors: any;
+export const children: any;
+export const descendants: any;
+export const siblings: any;
+export const followingSiblings: any;
+export const precedingSiblings: any;
+export const next: any;
+export const prev: any;
+export const closest: any;
+export const find: any;
+export const within: any;
+export const until: any;

package/dist/core/util.d.ts

@@ -0,0 +1,7 @@
+export function toElement(node: any): any;
+export function toIterable(iterable: any): any;
+export function describeElement(el: any): string;
+export function normaliseText(s: any): string;
+export function getOwnText(el: any): string;
+export function getValue(el: any): string;
+export function safeMatches(el: any, selector: any): any;

package/dist/extra.d.ts

@@ -0,0 +1 @@
+export { extra } from "./plugins/extra.js";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { dq } from "./core/dq.js";
+export { shadow } from "./plugins/shadow.js";
+export { extra } from "./plugins/extra.js";

package/dist/plugins/extra.d.ts

@@ -0,0 +1 @@
+export function extra(dq: any): void;

package/dist/plugins/shadow.d.ts

@@ -0,0 +1 @@
+export function shadow(dq: any, Query: any): void;

package/dist/shadow.d.ts

@@ -0,0 +1 @@
+export { shadow } from "./plugins/shadow.js";

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@thomasseanfahey/domq",
+  "version": "0.1.0",
+  "description": "Query DOM relationships, not selectors. Composable traversal + predicates with deterministic semantics and lazy evaluation.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./shadow": {
+      "types": "./dist/shadow.d.ts",
+      "default": "./src/shadow.js"
+    },
+    "./extra": {
+      "types": "./dist/extra.d.ts",
+      "default": "./src/extra.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "keywords": [
+    "dom",
+    "dom-traversal",
+    "dom-query",
+    "browser",
+    "browser-extension",
+    "scraping",
+    "testing",
+    "shadow-dom",
+    "predicate",
+    "query"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true });\"",
+    "build:types": "npm run clean && npx -y tsc -p tsconfig.json",
+    "prepack": "npm run build:types",
+    "prepublishOnly": "npm test && npm run build:types",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": { "typescript": "^5.6.3" },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/dq.js

@@ -0,0 +1,24 @@
+import { Query } from './query.js';
+import { and, or, not, predicate, attr, data, dataset, text, ownText, value, tag, hasClass, matches, role } from './predicates.js';
+import { self, parent, ancestors, children, descendants, siblings, followingSiblings, precedingSiblings, next, prev, closest, find, within, until } from './relations.js';
+
+function dq(node) { return Query.from(node); }
+dq.all = (iterable) => Query.fromAll(iterable);
+
+dq.compile = (builder) => {
+  if (typeof builder !== 'function') throw new TypeError('dq.compile(builder) requires a function');
+  return (start, options = undefined) => {
+    const q = dq(start);
+    if (options) { if (options.budget) q.budget(options.budget); if (options.debug) q.debug(options.debug); }
+    return builder(q);
+  };
+};
+
+dq.use = (plugin) => { if (typeof plugin !== 'function') throw new TypeError('dq.use(plugin) requires a function'); plugin(dq, Query); };
+
+Object.assign(dq, { and, or, not, predicate, attr, data, dataset, text, ownText, value, tag, hasClass, matches, role });
+Object.assign(dq, { relations: { self, parent, ancestors, children, descendants, siblings, followingSiblings, precedingSiblings, next, prev, closest, find, within, until } });
+
+Query.installBaseRelations({ self, parent, ancestors, children, descendants, siblings, followingSiblings, precedingSiblings, next, prev, closest, find, within, until });
+
+export { dq };

package/src/core/predicates.js

@@ -0,0 +1,67 @@
+import { getOwnText, getValue, normaliseText, safeMatches } from './util.js';
+
+function attachDescribe(fn, describe) {
+  Object.defineProperty(fn, '_domqDescribe', { value: () => describe, enumerable: false });
+  return fn;
+}
+
+export function predicate(fn, describe = 'predicate') {
+  if (typeof fn !== 'function') throw new TypeError('dq.predicate(fn) requires a function');
+  return attachDescribe((el) => Boolean(fn(el)), String(describe));
+}
+
+export function and(...preds) {
+  preds = preds.flat().filter(Boolean);
+  const desc = preds.map(p => (p && p._domqDescribe ? p._domqDescribe() : 'predicate')).join(' AND ');
+  return attachDescribe((el) => preds.every(p => p(el)), `(${desc})`);
+}
+
+export function or(...preds) {
+  preds = preds.flat().filter(Boolean);
+  const desc = preds.map(p => (p && p._domqDescribe ? p._domqDescribe() : 'predicate')).join(' OR ');
+  return attachDescribe((el) => preds.some(p => p(el)), `(${desc})`);
+}
+
+export function not(pred) {
+  const desc = pred && pred._domqDescribe ? pred._domqDescribe() : 'predicate';
+  return attachDescribe((el) => !pred(el), `NOT(${desc})`);
+}
+
+class ComparatorBuilder {
+  constructor(kind, getter) { this._kind = kind; this._getter = getter; }
+  exists() { return attachDescribe((el) => { const v = this._getter(el); return v !== null && v !== undefined && v !== ''; }, `${this._kind}.exists()`); }
+  eq(value) { return attachDescribe((el) => this._getter(el) === value, `${this._kind} == ${JSON.stringify(value)}`); }
+  ne(value) { return attachDescribe((el) => this._getter(el) !== value, `${this._kind} != ${JSON.stringify(value)}`); }
+  includes(substr) { const s = String(substr); return attachDescribe((el) => String(this._getter(el) ?? '').includes(s), `${this._kind}.includes(${JSON.stringify(s)})`); }
+  startsWith(prefix) { const p = String(prefix); return attachDescribe((el) => String(this._getter(el) ?? '').startsWith(p), `${this._kind}.startsWith(${JSON.stringify(p)})`); }
+  endsWith(suffix) { const s = String(suffix); return attachDescribe((el) => String(this._getter(el) ?? '').endsWith(s), `${this._kind}.endsWith(${JSON.stringify(s)})`); }
+  matches(re) { const rx = (re instanceof RegExp) ? re : new RegExp(String(re)); return attachDescribe((el) => rx.test(String(this._getter(el) ?? '')), `${this._kind}.matches(${rx.toString()})`); }
+  truthy() { return attachDescribe((el) => Boolean(this._getter(el)), `${this._kind}.truthy()`); }
+  gt(n) { const num = Number(n); return attachDescribe((el) => Number(this._getter(el)) > num, `${this._kind} > ${num}`); }
+  gte(n) { const num = Number(n); return attachDescribe((el) => Number(this._getter(el)) >= num, `${this._kind} >= ${num}`); }
+  lt(n) { const num = Number(n); return attachDescribe((el) => Number(this._getter(el)) < num, `${this._kind} < ${num}`); }
+  lte(n) { const num = Number(n); return attachDescribe((el) => Number(this._getter(el)) <= num, `${this._kind} <= ${num}`); }
+}
+
+export function attr(name) { const key = String(name); return new ComparatorBuilder(`attr(${JSON.stringify(key)})`, (el) => el.getAttribute(key)); }
+
+export function data(key) {
+  const k = String(key);
+  return new ComparatorBuilder(`data(${JSON.stringify(k)})`, (el) => {
+    const ds = el.dataset || {};
+    if (k in ds) return ds[k];
+    const camel = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (camel in ds) return ds[camel];
+    return el.getAttribute(`data-${k}`);
+  });
+}
+
+export function dataset(key) { return data(key); }
+export function text() { return new ComparatorBuilder('text()', (el) => normaliseText(el.textContent || '')); }
+export function ownText() { return new ComparatorBuilder('ownText()', (el) => getOwnText(el)); }
+export function value() { return new ComparatorBuilder('value()', (el) => getValue(el)); }
+
+export function tag(tagName) { const t = String(tagName).toLowerCase(); return attachDescribe((el) => (el.tagName || '').toLowerCase() === t, `tag(${JSON.stringify(t)})`); }
+export function hasClass(className) { const c = String(className); return attachDescribe((el) => el.classList ? el.classList.contains(c) : false, `hasClass(${JSON.stringify(c)})`); }
+export function matches(selector) { const s = String(selector); return attachDescribe((el) => safeMatches(el, s), `matches(${JSON.stringify(s)})`); }
+export function role(roleName) { const r = String(roleName); return attachDescribe((el) => el.getAttribute('role') === r, `role(${JSON.stringify(r)})`); }

package/src/core/query.js

@@ -0,0 +1,235 @@
+import { describeElement, toIterable, toElement } from './util.js';
+
+function nowMs() { return (typeof performance !== 'undefined' && performance.now) ? performance.now() : Date.now(); }
+
+function checkBudget(ctx) {
+  const b = ctx.budget;
+  if (!b) return;
+  if (typeof b.maxNodes === 'number' && ctx.visitedNodes > b.maxNodes) {
+    const err = new Error(`domq: traversal budget exceeded (maxNodes=${b.maxNodes})`);
+    err.code = 'DOMQ_BUDGET_NODES';
+    throw err;
+  }
+  if (typeof b.maxMs === 'number') {
+    const elapsed = nowMs() - ctx.startedAt;
+    if (elapsed > b.maxMs) {
+      const err = new Error(`domq: traversal budget exceeded (maxMs=${b.maxMs}, elapsed=${Math.round(elapsed)}ms)`);
+      err.code = 'DOMQ_BUDGET_TIME';
+      throw err;
+    }
+  }
+}
+
+export class Query {
+  constructor(iterableFactory, steps) {
+    this._iterableFactory = iterableFactory;
+    this._steps = steps || [];
+    this._budget = {};
+    this._debugEnabled = false;
+    this._debugLabel = null;
+  }
+
+  static from(node) {
+    const el = toElement(node);
+    return new Query(
+      (ctx) => (function* () { if (!el) return; ctx.visitedNodes += 1; checkBudget(ctx); yield el; })(),
+      el ? [`from(${describeElement(el)})`] : ['from(null)']
+    );
+  }
+
+  static fromAll(iterable) {
+    const it = toIterable(iterable);
+    return new Query(
+      (ctx) => (function* () {
+        for (const el of it) {
+          if (!(el instanceof Element)) continue;
+          ctx.visitedNodes += 1;
+          checkBudget(ctx);
+          yield el;
+        }
+      })(),
+      ['fromAll(...)']
+    );
+  }
+
+  static installBaseRelations(relations) {
+    for (const [name, fn] of Object.entries(relations)) {
+      if (Query.prototype[name]) continue;
+      Query.prototype[name] = function (...args) { return this.get(fn, ...args); };
+    }
+  }
+
+  get(relation, ...args) {
+    if (typeof relation !== 'function') throw new TypeError('domq: relation must be a function');
+    const prevFactory = this._iterableFactory;
+    const step = relation._domqName ? `${relation._domqName}(${args.map(String).join(', ')})` : 'relation(...)';
+    const nextFactory = (ctx) => relation(prevFactory(ctx), ctx, ...args);
+    return this._clone(nextFactory, [...this._steps, step]);
+  }
+
+  where(pred) {
+    if (typeof pred !== 'function') throw new TypeError('domq: predicate must be a function');
+    const prevFactory = this._iterableFactory;
+    const label = pred._domqDescribe ? pred._domqDescribe() : 'predicate';
+    const nextFactory = (ctx) => (function* () { for (const el of prevFactory(ctx)) if (pred(el)) yield el; })();
+    return this._clone(nextFactory, [...this._steps, `where(${label})`]);
+  }
+
+  not(pred) {
+    if (typeof pred !== 'function') throw new TypeError('domq: predicate must be a function');
+    const prevFactory = this._iterableFactory;
+    const label = pred._domqDescribe ? pred._domqDescribe() : 'predicate';
+    const nextFactory = (ctx) => (function* () { for (const el of prevFactory(ctx)) if (!pred(el)) yield el; })();
+    return this._clone(nextFactory, [...this._steps, `not(${label})`]);
+  }
+
+  unique() {
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () {
+      const seen = new Set();
+      for (const el of prevFactory(ctx)) { if (seen.has(el)) continue; seen.add(el); yield el; }
+    })();
+    return this._clone(nextFactory, [...this._steps, 'unique()']);
+  }
+
+  uniqueBy(keyFn) {
+    if (typeof keyFn !== 'function') throw new TypeError('domq: keyFn must be a function');
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () {
+      const seen = new Set();
+      for (const el of prevFactory(ctx)) { const key = keyFn(el); if (seen.has(key)) continue; seen.add(key); yield el; }
+    })();
+    return this._clone(nextFactory, [...this._steps, 'uniqueBy(fn)']);
+  }
+
+  reverse() {
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => { const arr = Array.from(prevFactory(ctx)); arr.reverse(); return arr; };
+    return this._clone(nextFactory, [...this._steps, 'reverse()']);
+  }
+
+  budget(budget) { this._budget = Object.assign({}, this._budget, budget || {}); return this; }
+  debug(label = true) { this._debugEnabled = Boolean(label); this._debugLabel = (typeof label === 'string') ? label : null; return this; }
+  explain() { return this._steps.join(' -> '); }
+
+  first() {
+    const { ctx, iterable } = this._evaluate();
+    let count = 0;
+    for (const el of iterable) { count += 1; this._maybeDebug(ctx, count); return el; }
+    this._maybeDebug(ctx, 0);
+    return null;
+  }
+
+  exists() {
+    const { ctx, iterable } = this._evaluate();
+    for (const _ of iterable) { this._maybeDebug(ctx, 1); return true; }
+    this._maybeDebug(ctx, 0);
+    return false;
+  }
+
+  one() {
+    const { ctx, iterable } = this._evaluate();
+    const matches = [];
+    for (const el of iterable) { matches.push(el); if (matches.length > 2) break; }
+    this._maybeDebug(ctx, matches.length);
+    if (matches.length === 1) return matches[0];
+    const summary = matches.map(describeElement).join(', ');
+    const err = new Error(`domq.one(): expected exactly 1 match, got ${matches.length}.\nPipeline: ${this.explain()}\n` + (matches.length ? `Sample: ${summary}` : 'No matches.'));
+    err.code = 'DOMQ_ONE';
+    throw err;
+  }
+
+  maybeOne() {
+    const { ctx, iterable } = this._evaluate();
+    let first = null;
+    let count = 0;
+    for (const el of iterable) { count += 1; if (count === 1) first = el; if (count > 1) break; }
+    this._maybeDebug(ctx, count);
+    if (count <= 1) return first;
+    const err = new Error(`domq.maybeOne(): expected 0 or 1 match, got ${count}.\nPipeline: ${this.explain()}`);
+    err.code = 'DOMQ_MAYBEONE';
+    throw err;
+  }
+
+  at(n) {
+    if (!Number.isInteger(n)) throw new TypeError('domq.at(n) requires an integer');
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () {
+      const arr = Array.from(prevFactory(ctx));
+      const idx = n < 0 ? arr.length + n : n;
+      if (idx < 0 || idx >= arr.length) return;
+      yield arr[idx];
+    })();
+    return this._clone(nextFactory, [...this._steps, `at(${n})`]);
+  }
+
+  take(n) {
+    if (!Number.isInteger(n) || n < 0) throw new TypeError('domq.take(n) requires n >= 0 integer');
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () { let i = 0; for (const el of prevFactory(ctx)) { if (i++ >= n) break; yield el; } })();
+    return this._clone(nextFactory, [...this._steps, `take(${n})`]);
+  }
+
+  skip(n) {
+    if (!Number.isInteger(n) || n < 0) throw new TypeError('domq.skip(n) requires n >= 0 integer');
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () { let i = 0; for (const el of prevFactory(ctx)) { if (i++ < n) continue; yield el; } })();
+    return this._clone(nextFactory, [...this._steps, `skip(${n})`]);
+  }
+
+  slice(start, end) {
+    if (!Number.isInteger(start)) throw new TypeError('domq.slice(start, end) requires integer start');
+    if (end != null && !Number.isInteger(end)) throw new TypeError('domq.slice(start, end) requires integer end or null');
+    const prevFactory = this._iterableFactory;
+    const nextFactory = (ctx) => (function* () { const arr = Array.from(prevFactory(ctx)); for (const el of arr.slice(start, end == null ? undefined : end)) yield el; })();
+    return this._clone(nextFactory, [...this._steps, `slice(${start}, ${end == null ? 'null' : end})`]);
+  }
+
+  count() {
+    const { ctx, iterable } = this._evaluate();
+    let c = 0;
+    for (const _ of iterable) c += 1;
+    this._maybeDebug(ctx, c);
+    return c;
+  }
+
+  toArray() {
+    const { ctx, iterable } = this._evaluate();
+    const arr = Array.from(iterable);
+    this._maybeDebug(ctx, arr.length);
+    return arr;
+  }
+
+  map(fn) {
+    if (typeof fn !== 'function') throw new TypeError('domq.map(fn) requires a function');
+    const { ctx, iterable } = this._evaluate();
+    const out = [];
+    let i = 0;
+    for (const el of iterable) out.push(fn(el, i++));
+    this._maybeDebug(ctx, i);
+    return out;
+  }
+
+  _clone(iterableFactory, steps) {
+    const q = new Query(iterableFactory, steps);
+    q._budget = Object.assign({}, this._budget);
+    q._debugEnabled = this._debugEnabled;
+    q._debugLabel = this._debugLabel;
+    return q;
+  }
+
+  _evaluate() {
+    const ctx = { budget: Object.assign({}, this._budget), debugEnabled: this._debugEnabled, debugLabel: this._debugLabel, visitedNodes: 0, startedAt: nowMs() };
+    const iterable = (function* (factory, ctx) { for (const el of factory(ctx)) { ctx.visitedNodes += 1; checkBudget(ctx); yield el; } })(this._iterableFactory, ctx);
+    return { ctx, iterable };
+  }
+
+  _maybeDebug(ctx, matchCount) {
+    if (!ctx.debugEnabled) return;
+    const label = ctx.debugLabel ? ` ${ctx.debugLabel}` : '';
+    const elapsed = Math.round((nowMs() - ctx.startedAt) * 100) / 100;
+    console.log(`[domq${label}] matches=${matchCount} visited=${ctx.visitedNodes} time=${elapsed}ms\n${this.explain()}`);
+  }
+}
+
+export { checkBudget };

package/src/core/relations.js

@@ -0,0 +1,106 @@
+import { safeMatches } from './util.js';
+
+function named(name, fn) { Object.defineProperty(fn, '_domqName', { value: name, enumerable: false }); return fn; }
+function maxDepth(ctx) { return (ctx && ctx.budget && typeof ctx.budget.maxDepth === 'number') ? ctx.budget.maxDepth : null; }
+
+export const self = named('self', (nodes) => nodes);
+
+export const parent = named('parent', (nodes) => (function* () { for (const el of nodes) if (el.parentElement) yield el.parentElement; })());
+
+export const ancestors = named('ancestors', (nodes, ctx) => {
+  const limit = maxDepth(ctx);
+  return (function* () {
+    for (const el of nodes) {
+      let cur = el.parentElement;
+      let depth = 0;
+      while (cur) {
+        if (limit != null && depth >= limit) break;
+        yield cur;
+        cur = cur.parentElement;
+        depth += 1;
+      }
+    }
+  })();
+});
+
+export const children = named('children', (nodes) => (function* () { for (const el of nodes) for (const c of el.children) yield c; })());
+
+export const descendants = named('descendants', (nodes, ctx) => {
+  const limit = maxDepth(ctx);
+  return (function* () {
+    for (const root of nodes) {
+      const stack = [];
+      const kids = root.children;
+      for (let i = kids.length - 1; i >= 0; i -= 1) stack.push({ el: kids[i], depth: 1 });
+      while (stack.length) {
+        const { el, depth } = stack.pop();
+        if (limit != null && depth > limit) continue;
+        yield el;
+        const ck = el.children;
+        for (let i = ck.length - 1; i >= 0; i -= 1) stack.push({ el: ck[i], depth: depth + 1 });
+      }
+    }
+  })();
+});
+
+export const siblings = named('siblings', (nodes) => (function* () {
+  for (const el of nodes) {
+    const p = el.parentElement;
+    if (!p) continue;
+    for (const c of p.children) if (c !== el) yield c;
+  }
+})());
+
+export const followingSiblings = named('followingSiblings', (nodes) => (function* () {
+  for (const el of nodes) { let cur = el.nextElementSibling; while (cur) { yield cur; cur = cur.nextElementSibling; } }
+})());
+
+export const precedingSiblings = named('precedingSiblings', (nodes) => (function* () {
+  for (const el of nodes) {
+    const acc = [];
+    let cur = el.previousElementSibling;
+    while (cur) { acc.push(cur); cur = cur.previousElementSibling; }
+    acc.reverse();
+    for (const x of acc) yield x;
+  }
+})());
+
+export const next = named('next', (nodes) => (function* () { for (const el of nodes) if (el.nextElementSibling) yield el.nextElementSibling; })());
+export const prev = named('prev', (nodes) => (function* () { for (const el of nodes) if (el.previousElementSibling) yield el.previousElementSibling; })());
+
+export const closest = named('closest', (nodes, _ctx, selector) => {
+  const s = String(selector);
+  return (function* () { for (const el of nodes) { const c = el.closest(s); if (c) yield c; } })();
+});
+
+export const find = named('find', (nodes, _ctx, selector) => {
+  const s = String(selector);
+  return (function* () {
+    for (const el of nodes) {
+      try { for (const x of el.querySelectorAll(s)) yield x; } catch {}
+    }
+  })();
+});
+
+export const within = named('within', (nodes, _ctx, selector) => {
+  const s = String(selector);
+  return (function* () { for (const el of nodes) { const c = el.closest(s); if (c) yield c; } })();
+});
+
+export const until = named('until', (nodes, _ctx, boundary) => {
+  const boundaryPred = (typeof boundary === 'string') ? (el) => safeMatches(el, boundary)
+    : (typeof boundary === 'function') ? boundary : null;
+  if (!boundaryPred) throw new TypeError('domq.until(boundary) requires a selector string or predicate function');
+
+  return (function* () {
+    for (const el of nodes) {
+      let cur = el;
+      while (cur && cur.parentElement) {
+        cur = cur.parentElement;
+        if (!cur) break;
+        if (boundaryPred(cur)) break;
+        yield cur;
+      }
+    }
+  })();
+});

package/src/core/util.js

@@ -0,0 +1,54 @@
+export function toElement(node) {
+  if (!node) return null;
+  if (node instanceof Element) return node;
+  if (node && typeof node === 'object' && 'nodeType' in node) {
+    if (node.nodeType === 1) return node;
+    if (node.parentElement instanceof Element) return node.parentElement;
+  }
+  return null;
+}
+
+export function toIterable(iterable) {
+  if (!iterable) return [];
+  if (typeof iterable[Symbol.iterator] === 'function') return iterable;
+  if (typeof iterable.length === 'number') {
+    return (function* () { for (let i = 0; i < iterable.length; i += 1) yield iterable[i]; })();
+  }
+  return [];
+}
+
+export function describeElement(el) {
+  if (!(el instanceof Element)) return String(el);
+  const tag = el.tagName ? el.tagName.toLowerCase() : 'element';
+  const id = el.id ? `#${el.id}` : '';
+  let cls = '';
+  if (typeof el.className === 'string' && el.className.trim()) {
+    const parts = el.className.trim().split(/\s+/).slice(0, 3);
+    cls = parts.length ? `.${parts.join('.')}` : '';
+  }
+  const attrs = [];
+  const keys = ['data-testid', 'data-test', 'data-qa', 'name', 'role', 'aria-label'];
+  for (const k of keys) {
+    const v = el.getAttribute && el.getAttribute(k);
+    if (v) attrs.push(`${k}=\"${v}\"`);
+    if (attrs.length >= 2) break;
+  }
+  const attrStr = attrs.length ? `[${attrs.join(' ')}]` : '';
+  return `${tag}${id}${cls}${attrStr}`;
+}
+
+export function normaliseText(s) { return String(s ?? '').replace(/\s+/g, ' ').trim(); }
+
+export function getOwnText(el) {
+  let out = '';
+  for (const n of el.childNodes) if (n.nodeType === 3) out += n.nodeValue || '';
+  return normaliseText(out);
+}
+
+export function getValue(el) {
+  const tag = el.tagName ? el.tagName.toLowerCase() : '';
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return String(el.value ?? '');
+  return '';
+}
+
+export function safeMatches(el, selector) { try { return el.matches(selector); } catch { return false; } }

package/src/extra.js

@@ -0,0 +1 @@
+export { extra } from './plugins/extra.js';

package/src/index.js

@@ -0,0 +1,3 @@
+export { dq } from './core/dq.js';
+export { shadow } from './plugins/shadow.js';
+export { extra } from './plugins/extra.js';

package/src/plugins/extra.js

@@ -0,0 +1,58 @@
+function attachDescribe(fn, desc) { Object.defineProperty(fn, '_domqDescribe', { value: () => desc, enumerable: false }); return fn; }
+function getComputed(el) { try { return window.getComputedStyle(el); } catch { return null; } }
+
+function visiblePredicate() {
+  return attachDescribe((el) => {
+    if (!(el instanceof Element)) return false;
+    const cs = getComputed(el);
+    if (!cs) return false;
+    if (cs.display === 'none') return false;
+    if (cs.visibility === 'hidden') return false;
+    if (Number(cs.opacity) === 0) return false;
+    const rects = el.getClientRects();
+    return rects && rects.length > 0;
+  }, 'visible()');
+}
+
+function inViewportPredicate(options = {}) {
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0;
+  return attachDescribe((el) => {
+    if (!(el instanceof Element)) return false;
+    const r = el.getBoundingClientRect();
+    const vw = window.innerWidth || document.documentElement.clientWidth || 0;
+    const vh = window.innerHeight || document.documentElement.clientHeight || 0;
+    if (vw <= 0 || vh <= 0) return false;
+
+    const interLeft = Math.max(0, Math.min(vw, r.right) - Math.max(0, r.left));
+    const interTop = Math.max(0, Math.min(vh, r.bottom) - Math.max(0, r.top));
+    const interArea = interLeft * interTop;
+    const area = Math.max(0, r.width) * Math.max(0, r.height);
+    if (area === 0) return false;
+
+    return (interArea / area) >= threshold;
+  }, `inViewport(${JSON.stringify({ threshold })})`);
+}
+
+function styleFactory(prop) {
+  const p = String(prop);
+  return {
+    eq(value) { return attachDescribe((el) => { const cs = getComputed(el); return cs ? cs.getPropertyValue(p) === String(value) : false; }, `style(${JSON.stringify(p)}) == ${JSON.stringify(String(value))}`); },
+    ne(value) { return attachDescribe((el) => { const cs = getComputed(el); return cs ? cs.getPropertyValue(p) !== String(value) : false; }, `style(${JSON.stringify(p)}) != ${JSON.stringify(String(value))}`); },
+    matches(re) { const rx = re instanceof RegExp ? re : new RegExp(String(re)); return attachDescribe((el) => { const cs = getComputed(el); const v = cs ? cs.getPropertyValue(p) : ''; return rx.test(v); }, `style(${JSON.stringify(p)}).matches(${rx.toString()})`); },
+    includes(substr) { const s = String(substr); return attachDescribe((el) => { const cs = getComputed(el); const v = cs ? cs.getPropertyValue(p) : ''; return v.includes(s); }, `style(${JSON.stringify(p)}).includes(${JSON.stringify(s)})`); }
+  };
+}
+
+function rectFactory() {
+  return {
+    width: { gt(n) { const num = Number(n); return attachDescribe((el) => el.getBoundingClientRect().width > num, `rect().width > ${num}`); }, lt(n) { const num = Number(n); return attachDescribe((el) => el.getBoundingClientRect().width < num, `rect().width < ${num}`); } },
+    height: { gt(n) { const num = Number(n); return attachDescribe((el) => el.getBoundingClientRect().height > num, `rect().height > ${num}`); }, lt(n) { const num = Number(n); return attachDescribe((el) => el.getBoundingClientRect().height < num, `rect().height < ${num}`); } }
+  };
+}
+
+export function extra(dq) {
+  dq.visible = visiblePredicate;
+  dq.inViewport = inViewportPredicate;
+  dq.style = styleFactory;
+  dq.rect = rectFactory;
+}

package/src/plugins/shadow.js

@@ -0,0 +1,80 @@
+function named(name, fn) { Object.defineProperty(fn, '_domqName', { value: name, enumerable: false }); return fn; }
+
+function composedParent(el) {
+  if (el.assignedSlot) return el.assignedSlot;
+  const root = el.getRootNode && el.getRootNode();
+  if (root && root.host instanceof Element) return root.host;
+  return el.parentElement;
+}
+
+const shadowRootRel = named('shadowRoot', (nodes) => (function* () {
+  for (const el of nodes) {
+    const sr = el.shadowRoot;
+    if (sr && sr instanceof ShadowRoot) for (const child of sr.children) yield child;
+  }
+})());
+
+const composedAncestorsRel = named('composedAncestors', (nodes, ctx) => {
+  const limit = (ctx && ctx.budget && typeof ctx.budget.maxDepth === 'number') ? ctx.budget.maxDepth : null;
+  return (function* () {
+    for (const el of nodes) {
+      let cur = el;
+      let depth = 0;
+      while (cur) {
+        const p = composedParent(cur);
+        if (!p) break;
+        if (limit != null && depth >= limit) break;
+        yield p;
+        cur = p;
+        depth += 1;
+      }
+    }
+  })();
+});
+
+const composedDescendantsRel = named('composedDescendants', (nodes, ctx) => {
+  const limit = (ctx && ctx.budget && typeof ctx.budget.maxDepth === 'number') ? ctx.budget.maxDepth : null;
+
+  function* iterChildren(el) {
+    for (const c of el.children) yield c;
+    if (el.shadowRoot) for (const c of el.shadowRoot.children) yield c;
+  }
+
+  return (function* () {
+    for (const root of nodes) {
+      const stack = [];
+      const kids = Array.from(iterChildren(root));
+      for (let i = kids.length - 1; i >= 0; i -= 1) stack.push({ el: kids[i], depth: 1 });
+      while (stack.length) {
+        const { el, depth } = stack.pop();
+        if (limit != null && depth > limit) continue;
+        yield el;
+        const ck = Array.from(iterChildren(el));
+        for (let i = ck.length - 1; i >= 0; i -= 1) stack.push({ el: ck[i], depth: depth + 1 });
+      }
+    }
+  })();
+});
+
+const assignedSlotRel = named('assignedSlot', (nodes) => (function* () { for (const el of nodes) if (el.assignedSlot) yield el.assignedSlot; })());
+const assignedElementsRel = named('assignedElements', (nodes) => (function* () {
+  for (const el of nodes) {
+    if (el instanceof HTMLSlotElement) {
+      const assigned = el.assignedElements ? el.assignedElements({ flatten: true }) : [];
+      for (const a of assigned) yield a;
+    }
+  }
+})());
+
+export function shadow(dq, Query) {
+  dq.relations.shadowRoot = shadowRootRel;
+  dq.relations.composedAncestors = composedAncestorsRel;
+  dq.relations.composedDescendants = composedDescendantsRel;
+  dq.relations.assignedSlot = assignedSlotRel;
+  dq.relations.assignedElements = assignedElementsRel;
+
+  const methods = { shadowRoot: shadowRootRel, composedAncestors: composedAncestorsRel, composedDescendants: composedDescendantsRel, assignedSlot: assignedSlotRel, assignedElements: assignedElementsRel };
+  for (const [name, fn] of Object.entries(methods)) {
+    if (!Query.prototype[name]) Query.prototype[name] = function (...args) { return this.get(fn, ...args); };
+  }
+}

package/src/shadow.js

@@ -0,0 +1 @@
+export { shadow } from './plugins/shadow.js';