rusteerio 1.0.0 → 1.1.0

package/src/hooks.ts

@@ -1,6 +1,6 @@
 import { requireNative, type NativeDocument } from './native.js';
-import { getNode, hydrateLocation } from './nodes.js';
-import { routeDocument } from './router.js';
+import { attachParsedNodes, getNode, hydrateLocation, operation } from './nodes.js';
+import { plainSnapshot, recordAt, routeDocument, type DocumentState, type RoutedDocument } from './router.js';
 import type { CheerioOptions } from './types.js';
 import type { TokenizerCallbacks } from './parser-types.js';
 
@@ -182,6 +182,11 @@ export function createTreeAdapterSession(options: CheerioOptions, isDocument: bo
 export function parseNativeDocument(source: string, options: CheerioOptions, isDocument: boolean): NativeDocument {
   const binding = requireNative();
   const nativeOptions = parserOptions(source, options);
+  if (!options._useHtmlParser2 && options.treeAdapter && canReplay(options)) {
+    const document = routeDocument(new binding.NativeDocument(source, isDocument, JSON.stringify(nativeOptions)), options) as RoutedDocument;
+    const nodes = replayIntoAdapter(document, options.treeAdapter, isDocument);
+    if (nodes) { attachParsedNodes(document.state, nodes); return document; }
+  }
   if (!options._useHtmlParser2 && options.treeAdapter) {
     const parse = (binding as typeof binding & { parseWithTreeAdapter?(source: string, isDocument: boolean, options: string, bridge: (request: string) => string): NativeDocument }).parseWithTreeAdapter;
     if (!parse) throw new Error('This native addon does not support treeAdapter hooks; rebuild the Rust addon.');
@@ -218,3 +223,144 @@ export function createDiagnosticSession(options: CheerioOptions, isDocument = tr
     abort() { aborted = true; parser.abort(); },
   };
 }
+
+/**
+ * Whether an adapter can be given the finished tree instead of every parser
+ * step: it observes neither the open-element stack nor source locations, and
+ * no parse-error callback can change it while parsing.
+ */
+function canReplay(options: CheerioOptions): boolean {
+  const adapter = options.treeAdapter as unknown as Record<string, unknown>;
+  return !options.onParseError && !options.sourceCodeLocationInfo && adapter.onItemPush === undefined && adapter.onItemPop === undefined;
+}
+
+/**
+ * Builds the adapter's tree from a native parse by calling its construction
+ * methods in document order, then checks every node against the parse. An
+ * adapter whose nodes differ from what it was given (renamed elements,
+ * rewritten text, filtered children) could have steered parsing differently,
+ * so it returns `undefined` and the caller runs the parser with the adapter
+ * live instead.
+ */
+function replayIntoAdapter(document: RoutedDocument, adapter: any, isDocument: boolean): (object | undefined)[] | undefined {
+  const state = document.state;
+  const root = document.rootId() - state.base;
+  const size = state.baseline;
+  const nodes: any[] = new Array(size);
+  // Reading every record once builds the snapshot; plain nodes are then read from its arrays.
+  for (let local = 0; local < Math.min(size, 65); local++) recordAt(state, local);
+  for (let local = 0; local < size; local++) {
+    const snapshot = plainSnapshot(state, local);
+    const record = snapshot ? undefined : recordAt(state, local);
+    if (!snapshot && !record) continue;
+    const type = snapshot ? snapshot.typeOf(local) : record!.type;
+    if (local === root) {
+      nodes[local] = isDocument ? adapter.createDocument() : adapter.createDocumentFragment();
+      const mode = record?.['x-mode'];
+      if (isDocument && mode !== undefined) adapter.setDocumentMode(nodes[local], mode);
+      continue;
+    }
+    const parentLocal = snapshot ? snapshot.linkOf(local, 1) : record!.parent;
+    const parent = parentLocal == null ? undefined : nodes[parentLocal];
+    if (parent === undefined) return undefined;
+    switch (type) {
+      case 'tag': case 'script': case 'style': {
+        const element = snapshot
+          ? adapter.createElement(snapshot.nameOf(local), snapshot.namespaceOf(local), snapshot.attributeObjects(local))
+          : adapter.createElement(record!.name, record!.namespace, attributeList(record));
+        adapter.appendChild(parent, element);
+        nodes[local] = element;
+        break;
+      }
+      case 'root': {
+        const content = adapter.createDocumentFragment();
+        adapter.setTemplateContent(parent, content);
+        nodes[local] = content;
+        break;
+      }
+      case 'text': {
+        adapter.insertText(parent, (snapshot ? snapshot.dataOf(local) : record!.data) ?? '');
+        const children = adapter.getChildNodes(parent);
+        nodes[local] = children[children.length - 1];
+        break;
+      }
+      case 'comment': {
+        const comment = adapter.createCommentNode((snapshot ? snapshot.dataOf(local) : record!.data) ?? '');
+        adapter.appendChild(parent, comment);
+        nodes[local] = comment;
+        break;
+      }
+      case 'directive': {
+        if (!record || record.name !== '!doctype' || !isDocument) return undefined;
+        adapter.setDocumentType(parent, record['x-name'] ?? '', record['x-publicId'] ?? '', record['x-systemId'] ?? '');
+        nodes[local] = Array.from(adapter.getChildNodes(parent) ?? []).find((child) => adapter.isDocumentTypeNode(child));
+        break;
+      }
+      default: return undefined;
+    }
+  }
+  const changes = differencesFromParse(adapter, nodes, state, root);
+  if (!changes) return undefined;
+  // Attribute and text rewrites do not steer parsing; the document takes the adapter's values.
+  for (const change of changes) operation(document, 'setNode', { id: state.base + change.local, field: change.field, value: change.value });
+  return nodes;
+}
+
+function attributeList(record: any): { name: string; value: string; namespace?: string; prefix?: string }[] {
+  const attributes = record.attribs ?? {};
+  return Object.keys(attributes).map((name) => {
+    const namespace = record.attribsNamespace?.[name];
+    const prefix = record.attribsPrefix?.[name];
+    return { name, value: attributes[name], ...(namespace === undefined ? {} : { namespace }), ...(prefix === undefined ? {} : { prefix }) };
+  });
+}
+
+interface DataChange { local: number; field: 'attribs' | 'attribsNamespace' | 'attribsPrefix' | 'data'; value: unknown }
+
+/**
+ * The attribute and text values in which the adapter's nodes differ from the
+ * parse, or `undefined` when a name, namespace or link differs, since those
+ * could have steered parsing.
+ */
+function differencesFromParse(adapter: any, nodes: any[], state: DocumentState, root: number): DataChange[] | undefined {
+  const changes: DataChange[] = [];
+  for (let local = 0; local < nodes.length; local++) {
+    const node = nodes[local];
+    const snapshot = plainSnapshot(state, local);
+    const record = snapshot ? undefined : recordAt(state, local);
+    if (!snapshot && !record) continue;
+    if (!node) return undefined;
+    const type = snapshot ? snapshot.typeOf(local) : record!.type;
+    if (local !== root && adapter.getParentNode(node) !== nodes[(snapshot ? snapshot.linkOf(local, 1) : record!.parent)!]) return undefined;
+    if (type !== 'text' && type !== 'comment' && type !== 'directive') {
+      const children = adapter.getChildNodes(node) ?? [];
+      const count = snapshot ? snapshot.childCount(local) : record!.children.length;
+      if (children.length !== count) return undefined;
+      for (let index = 0; index < count; index++) if (children[index] !== nodes[snapshot ? snapshot.childAt(local, index) : record!.children[index]]) return undefined;
+    }
+    if (type === 'tag' || type === 'script' || type === 'style') {
+      const name = snapshot ? snapshot.nameOf(local) : record!.name;
+      const namespace = snapshot ? snapshot.namespaceOf(local) : record!.namespace;
+      if (!adapter.isElementNode(node) || adapter.getTagName(node) !== name || adapter.getNamespaceURI(node) !== namespace) return undefined;
+      const attributes: { name: string; value: string; namespace?: string; prefix?: string }[] = adapter.getAttrList(node) ?? [];
+      const expected = snapshot ? snapshot.attributeObjects(local) : attributeList(record);
+      const isSame = attributes.length === expected.length && attributes.every((attribute, index) => attribute.name === expected[index].name && attribute.value === expected[index].value);
+      if (!isSame) {
+        const values: Record<string, string> = Object.create(null);
+        const namespaces: Record<string, string> = Object.create(null);
+        const prefixes: Record<string, string> = Object.create(null);
+        for (const attribute of attributes) {
+          values[attribute.name] = attribute.value;
+          if (attribute.namespace !== undefined) namespaces[attribute.name] = attribute.namespace;
+          if (attribute.prefix !== undefined) prefixes[attribute.name] = attribute.prefix;
+        }
+        changes.push({ local, field: 'attribs', value: values }, { local, field: 'attribsNamespace', value: namespaces }, { local, field: 'attribsPrefix', value: prefixes });
+      }
+    } else if (type === 'text' || type === 'comment') {
+      if (type === 'text' ? !adapter.isTextNode(node) : !adapter.isCommentNode(node)) return undefined;
+      const data = type === 'text' ? adapter.getTextNodeContent(node) : adapter.getCommentNodeContent(node);
+      if (data !== (snapshot ? snapshot.dataOf(local) : record!.data)) changes.push({ local, field: 'data', value: data });
+    }
+  }
+  return changes;
+}

package/src/index.ts

@@ -6,9 +6,9 @@ import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { availableParallelism } from 'node:os';
 import { requireNative, nativeStatus, type NativeDocument, type NativeQuery } from './native.js';
 import { Cheerio } from './selection.js';
-import { getNode, importNodes, nodeBinding, operation } from './nodes.js';
+import { getNode, importNodes, nodeBinding, operation, rootNode, viewIdIn } from './nodes.js';
 import { isHtml } from './utils.js';
-import { routeDocument, sameNodeSpace } from './router.js';
+import { DOCUMENT, exposeDocumentTo, resumeCollection, routeDocument, sameNodeSpace } from './router.js';
 import type { AnyNode, Document, CheerioAPI, CheerioOptions, LoadContent, ParallelOptions, ExtractMap, ExtractedMap } from './types.js';
 
 export type * from './types.js';
@@ -38,15 +38,22 @@ export function createAPI(document: NativeDocument, options?: CheerioOptions | n
   const internal = flattenOptions(options);
   class LoadedCheerio<T = AnyNode> extends Cheerio<T> {}
   let api: CheerioAPI;
-  const initialize = function<T = AnyNode>(selector?: any, context?: any, root?: any, override?: CheerioOptions): Cheerio<T> {
-    if (selector?.cheerio) return selector;
-    const opts = flattenOptions(override, internal);
-    const rootIds = root === undefined ? [initialRoot]
-      : typeof root === 'string' ? [makeRoot(document, operation(document, 'create', { html: root, options: opts }))]
-      : root?.cheerio ? importNodes(document, root.toArray()) : importNodes(document, root);
+  const createRoot = (rootIds: number[], opts: CheerioOptions): Cheerio<Document> => {
     const rootInstance = new LoadedCheerio<Document>(api, document, rootIds, null, opts);
     rootInstance._root = rootInstance;
+    return rootInstance;
+  };
+  const initialize = function<T = AnyNode>(selector?: any, context?: any, root?: any, override?: CheerioOptions): Cheerio<T> {
+    resumeCollection(document);
+    if (selector?.cheerio) { exposeDocumentTo(document, selector[DOCUMENT]); return selector; }
+    const opts = flattenOptions(override, internal);
+    // Each call gets its own root selection, as in Cheerio: callers may change the one `end()` returns.
+    const rootInstance = createRoot(root === undefined ? [initialRoot]
+        : typeof root === 'string' ? [makeRoot(document, operation(document, 'create', { html: root, options: opts }))]
+        : root?.cheerio ? importNodes(document, root.toArray()) : importNodes(document, root), opts);
     if (!selector) return new LoadedCheerio<T>(api, document, [], rootInstance, opts);
+    const id = viewIdIn(document, selector);
+    if (id !== undefined) return new LoadedCheerio<T>(api, document, [id], rootInstance, opts);
     if (typeof selector === 'string' && isHtml(selector)) return new LoadedCheerio<T>(api, document, operation(document, 'create', { html: selector, options: opts }), rootInstance, opts);
     if (typeof selector === 'object') {
       const values = 'length' in selector && !selector.type ? Array.from(selector as ArrayLike<T>) : [selector];
@@ -65,46 +72,50 @@ export function createAPI(document: NativeDocument, options?: CheerioOptions | n
     }
     return searchContext.find(search) as unknown as Cheerio<T>;
   };
-  api = Object.assign(initialize, {
+  // As in Cheerio, static methods are shared by every loaded API and read the document through `this`.
+  api = Object.assign(initialize, staticMethods, {
     load,
-    _root: getNode(document, initialRoot),
+    _root: rootNode(document, initialRoot),
     _options: internal,
     fn: LoadedCheerio.prototype,
     prototype: LoadedCheerio.prototype,
-    root(this: CheerioAPI): Cheerio<Document> { return this(this._root) as Cheerio<Document>; },
-    html(this: CheerioAPI | undefined, dom?: any, renderOptions?: CheerioOptions): string {
-      if (!this) return '';
-      if (dom && typeof dom === 'object' && !('length' in dom) && !('type' in dom)) { renderOptions = dom; dom = undefined; }
-      const nodes = dom === undefined ? [this._root] : this(dom).toArray();
-      const binding = nodeBinding(this._root)!;
-      return operation(binding.document, 'render', { ids: importNodes(binding.document, nodes), options: flattenOptions(renderOptions, this._options) });
-    },
-    xml(this: CheerioAPI, dom?: any): string {
-      const binding = nodeBinding(this._root)!;
-      return operation(binding.document, 'render', { ids: importNodes(binding.document, dom === undefined ? [this._root] : this(dom).toArray()), options: { ...this._options, xmlMode: true, _useHtmlParser2: true } });
-    },
-    text(this: CheerioAPI | undefined, elements?: ArrayLike<AnyNode>): string {
-      if (!elements && !this) return '';
-      const nodes = elements ?? [this!._root];
-      const binding = this ? nodeBinding(this._root) : nodeBinding(nodes[0]);
-      if (binding) return binding.document.text(importNodes(binding.document, nodes));
-      const doc = routeDocument(new (requireNative().NativeDocument)('', false));
-      return doc.text(importNodes(doc, nodes));
-    },
-    parseHTML(this: CheerioAPI, data?: string | null, context?: unknown, keepScripts = typeof context === 'boolean' ? context : false): AnyNode[] | null {
-      if (!data || typeof data !== 'string') return null;
-      if (typeof context === 'boolean') keepScripts = context;
-      const parsed = this.load(data, this._options, false);
-      if (!keepScripts) parsed('script').remove();
-      return parsed._root.children.slice();
-    },
-    extract<M extends ExtractMap>(this: CheerioAPI, map: M): ExtractedMap<M> { return this.root().extract(map); },
-    contains,
-    merge,
   }) as unknown as CheerioAPI;
   return api;
 }
 
+const staticMethods = {
+  root(this: CheerioAPI): Cheerio<Document> { return this(this._root) as Cheerio<Document>; },
+  html(this: CheerioAPI | undefined, dom?: any, renderOptions?: CheerioOptions): string {
+    if (!this) return '';
+    if (dom && typeof dom === 'object' && !('length' in dom) && !('type' in dom)) { renderOptions = dom; dom = undefined; }
+    const nodes = dom === undefined ? [this._root] : this(dom).toArray();
+    const binding = nodeBinding(this._root)!;
+    return operation(binding.document, 'render', { ids: importNodes(binding.document, nodes), options: flattenOptions(renderOptions, this._options) });
+  },
+  xml(this: CheerioAPI, dom?: any): string {
+    const binding = nodeBinding(this._root)!;
+    return operation(binding.document, 'render', { ids: importNodes(binding.document, dom === undefined ? [this._root] : this(dom).toArray()), options: { ...this._options, xmlMode: true, _useHtmlParser2: true } });
+  },
+  text(this: CheerioAPI | undefined, elements?: ArrayLike<AnyNode>): string {
+    if (!elements && !this) return '';
+    const nodes = elements ?? [this!._root];
+    const binding = this ? nodeBinding(this._root) : nodeBinding(nodes[0]);
+    if (binding) return binding.document.text(importNodes(binding.document, nodes));
+    const doc = routeDocument(new (requireNative().NativeDocument)('', false));
+    return doc.text(importNodes(doc, nodes));
+  },
+  parseHTML(this: CheerioAPI, data?: string | null, context?: unknown, keepScripts = typeof context === 'boolean' ? context : false): AnyNode[] | null {
+    if (!data || typeof data !== 'string') return null;
+    if (typeof context === 'boolean') keepScripts = context;
+    const parsed = this.load(data, this._options, false);
+    if (!keepScripts) parsed('script').remove();
+    return parsed._root.children.slice();
+  },
+  extract<M extends ExtractMap>(this: CheerioAPI, map: M): ExtractedMap<M> { return this.root().extract(map); },
+  contains,
+  merge,
+};
+
 function makeRoot(document: NativeDocument, children: number[]): number {
   const id = operation<number>(document, 'createNode', { type: 'root' });
   operation(document, 'setNode', { id, field: 'children', value: children });

package/src/match.ts

@@ -0,0 +1,207 @@
+import type { NativeDocument } from './native.js';
+import type { CheerioOptions } from './types.js';
+import { attributeAt, isRouted, plainSnapshot, recordAt, stateIn, type DocumentState } from './router.js';
+import { NodeSnapshot } from './snapshot.js';
+
+/**
+ * One compound selector: an optional type plus id, class and attribute-presence
+ * tests. Lowercased names are kept for documents that lowercase names.
+ */
+interface Compound { tag: string | undefined; lowerTag: string | undefined; ids: string[]; classes: string[]; attributes: string[]; lowerAttributes: string[] }
+
+const compiled = new Map<string, Compound[] | null>();
+const compiledLimit = 512;
+
+/**
+ * Matches `ids` against selectors simple enough to evaluate on cached records,
+ * with the native engine's semantics; `undefined` means the caller must ask
+ * the native engine (any other syntax, foreign documents or parser options).
+ */
+export function matchSimpleSelector(document: NativeDocument, ids: readonly number[], selector: string, options: CheerioOptions): number[] | undefined {
+  if (!isRouted(document)) return undefined;
+  const compounds = compile(selector);
+  if (!compounds) return undefined;
+  const isXml = isXmlMode(options);
+  const isLowerCaseTags = options.lowerCaseTags ?? !isXml;
+  const isLowerCaseAttributes = options.lowerCaseAttributeNames ?? !isXml;
+  const result: number[] = [];
+  for (const id of ids) {
+    const state = stateIn(document, id);
+    if (!sameMatchOptions(state.options, isXml, isLowerCaseTags, isLowerCaseAttributes)) return undefined;
+    const local = id - state.base;
+    for (const compound of compounds) {
+      if (matchesCompound(state, local, compound, isLowerCaseTags, isLowerCaseAttributes)) { result.push(id); break; }
+    }
+  }
+  return result;
+}
+
+/** Nodes a single `find()` walks in JavaScript before leaving larger subtrees to the native engine. */
+const walkBudget = 4096;
+/** Documents small enough that walking all of them in JavaScript beats a native call. */
+const smallDocumentNodes = 512;
+/** Documents small enough that taking a snapshot to walk them still beats a native call. */
+const tinyDocumentNodes = 64;
+
+/**
+ * Selects the descendants of one element, or of the root of a small
+ * document, that match a simple selector, in document order, as the native
+ * `select` does; `undefined` defers to it.
+ */
+export function selectSimpleWithin(document: NativeDocument, contexts: readonly number[], selector: string, options: CheerioOptions): number[] | undefined {
+  if (contexts.length !== 1 || !isRouted(document)) return undefined;
+  const compounds = compile(selector);
+  if (!compounds) return undefined;
+  const isXml = isXmlMode(options);
+  const isLowerCaseTags = options.lowerCaseTags ?? !isXml;
+  const isLowerCaseAttributes = options.lowerCaseAttributeNames ?? !isXml;
+  const state = stateIn(document, contexts[0]);
+  if (!sameMatchOptions(state.options, isXml, isLowerCaseTags, isLowerCaseAttributes)) return undefined;
+  const context = contexts[0] - state.base;
+  const size = Math.max(state.baseline, state.snapshotSize);
+  const isDocumentRoot = context === (state.rootLocal ??= state.raw.rootId());
+  const contextType = isDocumentRoot ? 'root' : typeAt(state, context);
+  // After a write, walking would cost a fresh snapshot; the native engine reads the arena directly.
+  // A walk reads every node: worthwhile with a current snapshot, or when a tiny unchanged document needs one.
+  const isReadable = state.bulk instanceof NodeSnapshot ? size <= smallDocumentNodes : state.generation === 0 && size <= tinyDocumentNodes;
+  const isSmallRoot = contextType === 'root' && isReadable;
+  if (!isElementType(contextType) && !isSmallRoot) return undefined;
+  const result: number[] = [];
+  const stack: number[] = [];
+  pushChildren(state, context, stack);
+  for (let visited = 0; stack.length; visited++) {
+    if (visited === walkBudget) return undefined;
+    const local = stack.pop()!;
+    const type = typeAt(state, local);
+    // Template contents: outside an element's descendants, but selected from the document root.
+    if (type === 'root') { if (isSmallRoot) return undefined; continue; }
+    if (isElementType(type)) {
+      for (const compound of compounds) {
+        if (matchesCompound(state, local, compound, isLowerCaseTags, isLowerCaseAttributes)) { result.push(state.base + local); break; }
+      }
+    }
+    pushChildren(state, local, stack);
+  }
+  return result;
+}
+
+const isElementType = (type: string | undefined): boolean => type === 'tag' || type === 'script' || type === 'style';
+
+function typeAt(state: DocumentState, local: number): string | undefined {
+  const snapshot = plainSnapshot(state, local);
+  return snapshot ? snapshot.typeOf(local) : recordAt(state, local)?.type;
+}
+
+/** Pushes children last to first, so they pop in document order. */
+function pushChildren(state: DocumentState, local: number, stack: number[]): void {
+  const snapshot = plainSnapshot(state, local);
+  if (snapshot) {
+    for (let index = snapshot.childCount(local) - 1; index >= 0; index--) stack.push(snapshot.childAt(local, index));
+    return;
+  }
+  const children = recordAt(state, local)?.children ?? [];
+  for (let index = children.length - 1; index >= 0; index--) stack.push(children[index]);
+}
+
+function isXmlMode(options: CheerioOptions): boolean {
+  return options.xmlMode ?? (options.xml === true || typeof options.xml === 'object' && options.xml !== null);
+}
+
+/** Records were parsed with the document's options; matching must use the same name casing. */
+function sameMatchOptions(documentOptions: CheerioOptions, isXml: boolean, isLowerCaseTags: boolean, isLowerCaseAttributes: boolean): boolean {
+  const isDocumentXml = isXmlMode(documentOptions);
+  return isDocumentXml === isXml
+    && (documentOptions.lowerCaseTags ?? !isDocumentXml) === isLowerCaseTags
+    && (documentOptions.lowerCaseAttributeNames ?? !isDocumentXml) === isLowerCaseAttributes;
+}
+
+function matchesCompound(state: DocumentState, local: number, compound: Compound, isLowerCaseTags: boolean, isLowerCaseAttributes: boolean): boolean {
+  const snapshot = plainSnapshot(state, local);
+  const record = snapshot ? undefined : recordAt(state, local);
+  if (!snapshot && !record) return false;
+  if (!isElementType(snapshot ? snapshot.typeOf(local) : record!.type)) return false;
+  if (compound.tag !== undefined && (snapshot ? snapshot.nameOf(local) : record!.name) !== (isLowerCaseTags ? compound.lowerTag : compound.tag)) return false;
+  for (const id of compound.ids) if (attributeAt(state, local, 'id') !== id) return false;
+  if (compound.classes.length) {
+    const classes = attributeAt(state, local, 'class');
+    if (classes === undefined) return false;
+    for (const name of compound.classes) if (!hasClass(classes, name)) return false;
+  }
+  for (const name of isLowerCaseAttributes ? compound.lowerAttributes : compound.attributes) if (attributeAt(state, local, name) === undefined) return false;
+  return true;
+}
+
+const isAsciiWhitespace = (code: number): boolean => code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
+
+/** Whether `name` is one of the ASCII-whitespace-separated tokens of `classes`. */
+function hasClass(classes: string, name: string): boolean {
+  for (let start = classes.indexOf(name); start !== -1; start = classes.indexOf(name, start + 1)) {
+    const end = start + name.length;
+    if ((start === 0 || isAsciiWhitespace(classes.charCodeAt(start - 1))) && (end === classes.length || isAsciiWhitespace(classes.charCodeAt(end)))) return true;
+  }
+  return false;
+}
+
+function asciiLowerCase(value: string): string {
+  return /[A-Z]/.test(value) ? value.replace(/[A-Z]/g, (letter) => letter.toLowerCase()) : value;
+}
+
+function compile(selector: string): Compound[] | null {
+  const cached = compiled.get(selector);
+  if (cached !== undefined) return cached;
+  const result = parse(selector);
+  if (compiled.size >= compiledLimit) compiled.clear();
+  compiled.set(selector, result);
+  return result;
+}
+
+const identifierStart = /[A-Za-z_]/;
+const identifierPart = /[A-Za-z0-9_-]/;
+
+/** Parses the supported subset; anything else (escapes, combinators, pseudos, values) yields `null`. */
+function parse(selector: string): Compound[] | null {
+  const compounds: Compound[] = [];
+  let index = 0;
+  const skipSpace = (): void => { while (index < selector.length && isAsciiWhitespace(selector.charCodeAt(index))) index++; };
+  const identifier = (): string | null => {
+    const start = index;
+    if (selector[index] === '-') index++;
+    if (!identifierStart.test(selector[index] ?? '')) return null;
+    while (index < selector.length && identifierPart.test(selector[index])) index++;
+    return selector.slice(start, index);
+  };
+  for (;;) {
+    skipSpace();
+    const compound: Compound = { tag: undefined, lowerTag: undefined, ids: [], classes: [], attributes: [], lowerAttributes: [] };
+    let hasPart = false;
+    if (selector[index] === '*') { index++; hasPart = true; }
+    else if (/[A-Za-z]/.test(selector[index] ?? '')) { compound.tag = identifier()!; hasPart = true; }
+    for (;;) {
+      const character = selector[index];
+      if (character === '#' || character === '.') {
+        index++;
+        const name = identifier();
+        if (name === null) return null;
+        (character === '#' ? compound.ids : compound.classes).push(name);
+      } else if (character === '[') {
+        index++;
+        skipSpace();
+        const name = identifier();
+        if (name === null) return null;
+        skipSpace();
+        if (selector[index] !== ']') return null;
+        index++;
+        compound.attributes.push(name);
+      } else break;
+      hasPart = true;
+    }
+    if (!hasPart) return null;
+    compound.lowerTag = compound.tag === undefined ? undefined : asciiLowerCase(compound.tag);
+    compound.lowerAttributes = compound.attributes.map(asciiLowerCase);
+    compounds.push(compound);
+    skipSpace();
+    if (index === selector.length) return compounds;
+    if (selector[index] !== ',') return null;
+    index++;
+  }
+}

package/src/native.ts

@@ -90,6 +90,14 @@ let cached: NativeBinding | undefined;
 let attempted = false;
 let bindingError: unknown;
 
+/**
+ * The directory of this bundle, shared by the package's CommonJS and ESM
+ * entry points and distinct for every installed copy of the package.
+ */
+export function packageDirectory(): string {
+  return typeof __dirname === 'string' ? __dirname : dirname(fileURLToPath(import.meta.url));
+}
+
 /** Resolve the native addon bundled with the npm package. */
 export function nativeBinding(): NativeBinding | undefined {
   if (attempted) return cached;
@@ -97,7 +105,7 @@ export function nativeBinding(): NativeBinding | undefined {
 
   // This module is bundled into both CommonJS and ESM entry points. A synthetic
   // absolute filename lets createRequire work in both module formats.
-  const moduleDirectory = typeof __dirname === 'string' ? __dirname : dirname(fileURLToPath(import.meta.url));
+  const moduleDirectory = packageDirectory();
   const require = createRequire(join(moduleDirectory, 'rusteerio-loader.cjs'));
   const directories = [moduleDirectory, dirname(moduleDirectory)];
   const libc = process.platform === 'linux'