rusteerio 0.0.0-stage → 0.1.1

package/src/attributes.ts

@@ -0,0 +1,271 @@
+import type { AnyNode, Element, SerializedField } from './types.js';
+import type { Cheerio } from './selection.js';
+import type { NativeDocument } from './native.js';
+import { getNode, hydrateLocation, importNodes, nodeRecord } from './nodes.js';
+
+export interface StyleProp {
+  length: number;
+  [key: string]: string | number;
+  [index: number]: string;
+}
+
+export interface AttributeMethods<T = AnyNode> {
+  attr<U extends AnyNode>(this: Cheerio<U>, name: string): string | undefined;
+  attr<U extends AnyNode>(this: Cheerio<U>): Record<string, string> | undefined;
+  attr<U extends AnyNode>(this: Cheerio<U>, name: string, value?: string | null | ((this: Element, index: number, value: string) => string | null)): Cheerio<U>;
+  attr<U extends AnyNode>(this: Cheerio<U>, values: Record<string, string | null>): Cheerio<U>;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: 'tagName' | 'nodeName'): string | undefined;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: 'innerHTML' | 'outerHTML' | 'innerText' | 'textContent'): string | null;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: 'style'): StyleProp | undefined;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: 'href' | 'src'): string | undefined;
+  prop<U extends AnyNode, K extends keyof Element>(this: Cheerio<U>, name: K): Element[K];
+  prop<U extends AnyNode, K extends keyof Element>(this: Cheerio<U>, name: K, value: Element[K] | ((this: Element, index: number, property: K) => Element[keyof Element])): Cheerio<U>;
+  prop<U extends AnyNode>(this: Cheerio<U>, values: Record<string, string | Element[keyof Element] | boolean>): Cheerio<U>;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: string, value: string | boolean | null | ((this: Element, index: number, property: string) => string | boolean)): Cheerio<U>;
+  prop<U extends AnyNode>(this: Cheerio<U>, name: string): string;
+  data<U extends AnyNode>(this: Cheerio<U>, name: string): unknown;
+  data<U extends AnyNode>(this: Cheerio<U>): Record<string, unknown>;
+  data<U extends AnyNode>(this: Cheerio<U>, name: string, value: unknown): Cheerio<U>;
+  data<U extends AnyNode>(this: Cheerio<U>, values: Record<string, unknown>): Cheerio<U>;
+  val<U extends AnyNode>(this: Cheerio<U>): string | string[] | undefined;
+  val<U extends AnyNode>(this: Cheerio<U>, value: string | string[]): Cheerio<U>;
+  removeAttr<U extends AnyNode>(this: Cheerio<U>, name: string): Cheerio<U>;
+  hasClass<U extends AnyNode>(this: Cheerio<U>, name: string): boolean;
+  addClass<U extends AnyNode, R extends ArrayLike<U>>(this: R, name?: string | ((this: Element, index: number, current: string) => string | undefined)): R;
+  removeClass<U extends AnyNode, R extends ArrayLike<U>>(this: R, name?: string | ((this: Element, index: number, current: string) => string | undefined)): R;
+  toggleClass<U extends AnyNode, R extends ArrayLike<U>>(this: R, name?: string | ((this: Element, index: number, current: string, state?: boolean) => string), state?: boolean): R;
+  css<U extends AnyNode>(this: Cheerio<U>, names?: string[]): Record<string, string> | undefined;
+  css<U extends AnyNode>(this: Cheerio<U>, name: string): string | undefined;
+  css<U extends AnyNode>(this: Cheerio<U>, name: string, value: string | ((this: Element, index: number, current: string) => string | undefined)): Cheerio<U>;
+  css<U extends AnyNode>(this: Cheerio<U>, values: Record<string, string>): Cheerio<U>;
+  serializeArray<U extends AnyNode>(this: Cheerio<U>): SerializedField[];
+  serialize<U extends AnyNode>(this: Cheerio<U>): string;
+}
+
+type Selection = Cheerio<AnyNode>;
+type DataRecord = Record<string, unknown>;
+type DataCache = Map<number, WeakRef<DataRecord>>;
+type DataDocument = NativeDocument & {
+  nodeSpace?: object;
+  retainNodeData?: (id: number, data: DataRecord) => void;
+  nodeData?: (id: number) => DataRecord | undefined;
+  nodeDataOperation?: (id: number) => (command: string, args: unknown) => unknown;
+};
+const dataObjects = new WeakMap<object, DataCache>();
+const dataFinalizer = new FinalizationRegistry<{ cache: WeakRef<DataCache>; id: number; reference: WeakRef<DataRecord> }>(({ cache, id, reference }) => {
+  const records = cache.deref();
+  if (records?.get(id) === reference) records.delete(id);
+});
+
+function isElement(selection: Selection, id: number): boolean {
+  return ['tag', 'script', 'style'].includes(nodeRecord(selection._document, id)?.type);
+}
+
+function nativeValue(value: unknown): unknown {
+  const seen = new WeakSet<object>();
+  const json = JSON.stringify(value, (_key, value: unknown) => {
+    if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint' || value === undefined) return { __opaqueJavaScriptValue: true };
+    if (typeof value === 'number' && !Number.isFinite(value)) return { __nativeNumber: String(value) };
+    if (value && typeof value === 'object') {
+      if (seen.has(value)) return { __opaqueJavaScriptValue: true };
+      seen.add(value);
+    }
+    return value;
+  });
+  return json === undefined ? { __opaqueJavaScriptValue: true } : JSON.parse(json);
+}
+
+function hydrateValue(value: any): any {
+  if (value && typeof value === 'object') {
+    if (Object.keys(value).length === 1 && typeof value.__nativeNumber === 'string') return Number(value.__nativeNumber);
+    for (const key of Object.keys(value)) value[key] = hydrateValue(value[key]);
+  }
+  return value;
+}
+
+function dataObject(selection: Selection, id: number): Record<string, unknown> {
+  // Routed documents share a stable handle space. Moving a native node between
+  // documents therefore preserves data identities and callback references.
+  const document = selection._document as DataDocument;
+  const cacheKey = document.nodeSpace ?? document;
+  let documents = dataObjects.get(cacheKey);
+  if (!documents) dataObjects.set(cacheKey, documents = new Map());
+  const existingReference = documents.get(id);
+  let data = existingReference?.deref() ?? document.nodeData?.(id);
+  if (!data) {
+    const documentReference = new WeakRef(document);
+    const dispatch = document.nodeDataOperation?.(id) ?? ((command: string, args: unknown) => {
+      const document = documentReference.deref();
+      return document ? JSON.parse(document.op(command, JSON.stringify(args))) : undefined;
+    });
+    const target: Record<string, unknown> = {};
+    data = new Proxy(target, {
+      set(object, name, value) {
+        Reflect.set(object, name, value);
+        if (typeof name === 'string') dispatch('data', { ids: [id], name, value: nativeValue(value) });
+        return true;
+      },
+      defineProperty(object, name, descriptor) {
+        Reflect.defineProperty(object, name, descriptor);
+        if (typeof name === 'string' && 'value' in descriptor) dispatch('data', { ids: [id], name, value: nativeValue(descriptor.value) });
+        return true;
+      },
+      deleteProperty(object, name) {
+        Reflect.deleteProperty(object, name);
+        if (typeof name === 'string') dispatch('removeData', { ids: [id], name });
+        return true;
+      },
+    });
+    const node = getNode(selection._document, id);
+    // JS data can contain callbacks, cycles, and object identities. The DOM and
+    // parsed data values live in Rust; this handle preserves those JS values.
+    Object.defineProperty(node, 'data', { configurable: true, enumerable: true, get: () => data, set: (value: Record<string, unknown>) => { for (const key of Object.keys(data!)) delete data![key]; for (const key of Object.keys(value ?? {})) data![key] = value[key]; } });
+  }
+  if (existingReference?.deref() !== data) {
+    const reference = new WeakRef(data);
+    documents.set(id, reference);
+    dataFinalizer.register(data, { cache: new WeakRef(documents), id, reference });
+  }
+  document.retainNodeData?.(id, data);
+  return data;
+}
+
+function property(selection: Selection, id: number, name: string, raw = false): any {
+  const result = selection.op('prop', { ids: [id], name, ...(raw ? { raw: true } : {}) });
+  if (name === 'sourceCodeLocation') return hydrateLocation(result);
+  return result?.__nativeNodeProperty ? (getNode(selection._document, id) as any)[result.__nativeNodeProperty] : result === null ? undefined : result;
+}
+
+function propertyValue(selection: Selection, name: string, value: any): any {
+  if (name === 'children' || name === 'childNodes') return importNodes(selection._document, value);
+  if (['parent', 'parentNode', 'prev', 'previousSibling', 'next', 'nextSibling'].includes(name)) return value == null ? null : importNodes(selection._document, [value])[0] ?? null;
+  return value;
+}
+
+function attr(this: Selection, name?: any, value?: any): any {
+  if (typeof name === 'object' || value !== undefined) {
+    if (typeof value === 'function') {
+      if (typeof name !== 'string') throw new Error('Bad combination of arguments.');
+      this.ids.forEach((id, index) => {
+        if (!isElement(this, id)) return;
+        const node = getNode(this._document, id) as Element;
+        const current = node.attribs[name];
+        const next = value.call(node, index, current);
+        this.op('attr', { ids: [id], name, value: next === null ? null : String(next) });
+      });
+    } else if (typeof name === 'object') {
+      for (const key of Object.keys(name)) this.op('attr', { ids: this.ids, name: key, value: name[key] === null ? null : String(name[key]) });
+    } else {
+      this.op('attr', { ids: this.ids, name, value: value === null ? null : String(value) });
+    }
+    return this;
+  }
+  if (arguments.length > 1) return this;
+  const result = this.op('attr', { ids: this.ids, ...(typeof name === 'string' ? { name } : {}) });
+  if (result === null) return undefined;
+  return !name && this.ids.length ? (getNode(this._document, this.ids[0]) as Element).attribs : result;
+}
+
+function prop(this: Selection, name: any, value?: any): any {
+  if (typeof name === 'string' && value === undefined) return this.ids.length ? property(this, this.ids[0], name) : undefined;
+  if (typeof name === 'object' || value !== undefined) {
+    if (typeof value === 'function') {
+      if (typeof name === 'object') throw new TypeError('Bad combination of arguments.');
+      this.ids.forEach((id, index) => {
+        if (!isElement(this, id)) return;
+        const next = value.call(getNode(this._document, id), index, property(this, id, name, true));
+        this.op('prop', { ids: [id], name, value: propertyValue(this, name, next) });
+      });
+    } else if (typeof name === 'object') {
+      for (const key of Object.keys(name)) this.op('prop', { ids: this.ids, name: key, value: propertyValue(this, key, name[key]) });
+    } else {
+      this.op('prop', { ids: this.ids, name, value: propertyValue(this, name, value) });
+    }
+    return this;
+  }
+  return undefined;
+}
+
+function data(this: Selection, name?: any, value?: unknown): any {
+  const first = this.ids[0];
+  if (first === undefined || !isElement(this, first)) return undefined;
+  if (name != null && (typeof name === 'object' || value !== undefined)) {
+    for (const id of this.ids) {
+      if (!isElement(this, id)) continue;
+      const record = dataObject(this, id);
+      if (typeof name === 'object') for (const key of Object.keys(name)) record[key] = name[key];
+      else if (typeof name === 'string') record[name] = value;
+    }
+    return this;
+  }
+  const record = dataObject(this, first);
+  if (typeof name === 'string' && Object.hasOwn(record, name)) return record[name];
+  const found = this.op<{ found: boolean; value?: any }>('data', { ids: [first], ...(name == null ? {} : { name }) });
+  if (!found.found) return undefined;
+  if (name == null) {
+    for (const key of Object.keys(found.value)) if (!Object.hasOwn(record, key)) record[key] = hydrateValue(found.value[key]);
+    return record;
+  }
+  record[name] = hydrateValue(found.value);
+  return record[name];
+}
+
+function css(this: Selection, name?: any, value?: any): any {
+  if (name != null && value != null || typeof name === 'object' && !Array.isArray(name)) {
+    if (typeof name === 'object') {
+      for (const [propertyIndex, key] of Object.keys(name).entries()) {
+        if (typeof name[key] === 'function') {
+          for (const id of this.ids) {
+            if (!isElement(this, id)) continue;
+            const current = this.op('css', { ids: [id], name: key }) ?? undefined;
+            const next = name[key].call(getNode(this._document, id), propertyIndex, current);
+            this.op('css', { ids: [id], name: key, value: next == null ? null : String(next) });
+          }
+        } else this.op('css', { ids: this.ids, name: key, value: name[key] == null ? null : String(name[key]) });
+      }
+    } else if (typeof name === 'string' && typeof value === 'function') {
+      this.ids.forEach((id, index) => {
+        if (!isElement(this, id)) return;
+        const current = this.op('css', { ids: [id], name }) ?? undefined;
+        const next = value.call(getNode(this._document, id), index, current);
+        this.op('css', { ids: [id], name, value: next == null ? null : String(next) });
+      });
+    } else if (typeof name === 'string') this.op('css', { ids: this.ids, name, value: value == null ? null : String(value) });
+    return this;
+  }
+  return this.op('css', { ids: this.ids, ...(name === undefined ? {} : { name }) }) ?? undefined;
+}
+
+function classMethod(command: 'addClass' | 'removeClass' | 'toggleClass') {
+  return function(this: Selection, name?: any, state?: boolean): Selection {
+    if (typeof name === 'function') {
+      this.ids.forEach((id, index) => {
+        if (!isElement(this, id)) return;
+        const node = getNode(this._document, id) as Element;
+        const next = command === 'toggleClass'
+          ? name.call(node, index, node.attribs.class ?? '', state)
+          : name.call(node, index, node.attribs.class ?? '');
+        if (typeof next === 'string') this.op(command, { ids: [id], name: next, ...(typeof state === 'boolean' ? { state } : {}) });
+      });
+    } else if (typeof name === 'string' || command === 'removeClass' && arguments.length === 0) {
+      this.op(command, { ids: this.ids, ...(typeof name === 'string' ? { name } : { all: true }), ...(typeof state === 'boolean' ? { state } : {}) });
+    }
+    return this;
+  };
+}
+
+export function installAttributes(CheerioClass: { prototype: object }): void {
+  Object.assign(CheerioClass.prototype, {
+    attr, prop, data, css,
+    removeAttr(this: Selection, name: string) { this.op('removeAttr', { ids: this.ids, name }); return this; },
+    hasClass(this: Selection, name: string) { return this.op<boolean>('hasClass', { ids: this.ids, name }); },
+    addClass: classMethod('addClass'), removeClass: classMethod('removeClass'), toggleClass: classMethod('toggleClass'),
+    val(this: Selection, value?: unknown) {
+      if (arguments.length === 0) return this.op('val', { ids: this.ids }) ?? undefined;
+      const result = this.op('val', { ids: this.ids, value: value === undefined ? { __undefinedJavaScriptValue: true } : value });
+      return result?.chain === false ? result.returnValue : result === false ? undefined : this;
+    },
+    serializeArray(this: Selection) { return this.op<SerializedField[]>('serializeArray', { ids: this.ids }); },
+    serialize(this: Selection) { return this.op<string>('serialize', { ids: this.ids }); },
+  });
+}

package/src/codec.ts

@@ -0,0 +1,74 @@
+/**
+ * Node strings use UTF-16, including unpaired surrogates. Rust strings use
+ * Unicode scalar values. Reserve a small private-use alphabet on this private
+ * boundary so neither representation loses a code unit.
+ */
+const reserved = /[\ud800-\ue800]/;
+const encoded = /[\ue000-\ue800]/;
+const escapeUnit = 0xe800;
+const isWellFormed = (String.prototype as String & { isWellFormed?(): boolean }).isWellFormed;
+
+export function encodeString(value: string): string {
+  if (!encoded.test(value) && (isWellFormed ? isWellFormed.call(value) : !reserved.test(value))) return value;
+  const parts: string[] = [];
+  let start = 0;
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) { index++; continue; }
+    }
+    let replacement: string | undefined;
+    if (unit >= 0xd800 && unit <= 0xdfff) replacement = String.fromCharCode(0xe000 + unit - 0xd800);
+    else if (unit >= 0xe000 && unit <= escapeUnit) replacement = '\ue800' + value[index];
+    if (replacement !== undefined) {
+      parts.push(value.slice(start, index), replacement);
+      start = index + 1;
+    }
+  }
+  return start === 0 ? value : parts.join('') + value.slice(start);
+}
+
+export function decodeString(value: string): string {
+  if (!encoded.test(value)) return value;
+  const parts: string[] = [];
+  let start = 0;
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit < 0xe000 || unit > escapeUnit) continue;
+    const next = value.charCodeAt(index + 1);
+    if (unit === escapeUnit) {
+      if (next < 0xe000 || next > escapeUnit || Number.isNaN(next)) continue;
+      parts.push(value.slice(start, index), value[++index]);
+    } else parts.push(value.slice(start, index), String.fromCharCode(0xd800 + unit - 0xe000));
+    start = index + 1;
+  }
+  return start === 0 ? value : parts.join('') + value.slice(start);
+}
+
+// Transform JSON string tokens rather than the whole JSON text: JSON.stringify
+// escapes lone surrogates, while a literal backslash-u sequence is plain data.
+const stringToken = /"(?:[^"\\]|\\[\s\S])*"/g;
+const encodeJsonCandidate = /[\ud800-\ue800]|\\u(?:d[89a-f][\da-f]{2}|e[0-8][\da-f]{2})/i;
+const escapedJsonCandidate = /\\u(?:d[89a-f][\da-f]{2}|e[0-8][\da-f]{2})/i;
+const decodeJsonCandidate = /[\ue000-\ue800]|\\ue[0-8][\da-f]{2}/i;
+
+export function encodeJson(value: string): string {
+  if (!encodeJsonCandidate.test(value)) return value;
+  if (isWellFormed?.call(value) && !encoded.test(value) && !escapedJsonCandidate.test(value)) return value;
+  return value.replace(stringToken, (token) => JSON.stringify(encodeString(JSON.parse(token))));
+}
+
+export function decodeJson(value: string): string {
+  return decodeJsonCandidate.test(value) ? value.replace(stringToken, (token) => JSON.stringify(decodeString(JSON.parse(token)))) : value;
+}
+
+/** Private parser protocol flag, appended without deserializing large options. */
+export function encodeOptions(value?: string): string {
+  if (value === undefined) return '{"__utf16Codec":true}';
+  const json = encodeJson(value);
+  if (!json.trimStart().startsWith('{')) return '{"__utf16Codec":true}';
+  const end = json.lastIndexOf('}');
+  const prefix = json.slice(0, end);
+  return prefix + (prefix.trimEnd().endsWith('{') ? '' : ',') + '"__utf16Codec":true' + json.slice(end);
+}

package/src/dom.ts

@@ -0,0 +1,87 @@
+import { requireNative } from './native.js';
+import { getNode, importNodes, nodeBinding, operation, cloneNode } from './nodes.js';
+import { routeDocument } from './router.js';
+import type * as Shape from './types.js';
+
+export const ElementType = Object.freeze({ Root: 'root', Text: 'text', Directive: 'directive', Comment: 'comment', Script: 'script', Style: 'style', Tag: 'tag', CDATA: 'cdata', Doctype: 'doctype' } as typeof Shape.ElementType);
+
+function initialize<T extends Node>(node: T, type: string, fields: Record<string, unknown>, children: readonly Shape.AnyNode[] = []): T {
+  const document = routeDocument(new (requireNative().NativeDocument)('', false));
+  const id = operation<number>(document, 'createNode', { type, ...fields });
+  if (children.length) operation(document, 'setNode', { id, field: 'children', value: importNodes(document, children) });
+  return getNode(document, id, node) as unknown as T;
+}
+
+/** DOM constructors backed by native storage, also shared across ESM/CJS views. */
+export abstract class Node {
+  static [Symbol.hasInstance](value: unknown): boolean {
+    const binding = nodeBinding(value);
+    if (!binding) return Function.prototype[Symbol.hasInstance].call(this, value);
+    const type = (value as Shape.AnyNode).type;
+    switch (this.name) {
+      case 'Node': return true;
+      case 'DataNode': return ['text', 'comment', 'directive'].includes(type);
+      case 'NodeWithChildren': return ['root', 'tag', 'script', 'style', 'cdata'].includes(type);
+      case 'Element': return ['tag', 'script', 'style'].includes(type);
+      case 'Document': return type === 'root';
+      case 'CDATA': return type === 'cdata';
+      case 'Text': return type === 'text';
+      case 'Comment': return type === 'comment';
+      case 'ProcessingInstruction': return type === 'directive';
+      default: return Function.prototype[Symbol.hasInstance].call(this, value);
+    }
+  }
+}
+export interface Node extends Shape.Node {}
+export abstract class DataNode extends Node {}
+export interface DataNode extends Shape.DataNode {}
+export abstract class NodeWithChildren extends Node {}
+export interface NodeWithChildren extends Shape.NodeWithChildren {}
+export class Text extends DataNode { declare readonly nodeType: 3; declare type: Shape.Text['type']; constructor(data: string) { super(); return initialize(this, 'text', { data }); } }
+export interface Text extends Shape.Text {}
+export class Comment extends DataNode { declare readonly nodeType: 8; declare type: Shape.Comment['type']; constructor(data: string) { super(); return initialize(this, 'comment', { data }); } }
+export interface Comment extends Shape.Comment {}
+export class ProcessingInstruction extends DataNode { declare readonly nodeType: 1; declare type: Shape.ProcessingInstruction['type']; constructor(name: string, data: string) { super(); return initialize(this, 'directive', { name, data }); } }
+export interface ProcessingInstruction extends Shape.ProcessingInstruction {}
+export class Document extends NodeWithChildren { declare readonly nodeType: 9; declare type: Shape.Document['type']; constructor(children: Shape.ChildNode[]) { super(); return initialize(this, 'root', {}, children); } }
+export interface Document extends Shape.Document {}
+export class CDATA extends NodeWithChildren { declare readonly nodeType: 4; declare type: Shape.CDATA['type']; constructor(children: Shape.ChildNode[]) { super(); return initialize(this, 'cdata', {}, children); } }
+export interface CDATA extends Shape.CDATA {}
+export class Element extends NodeWithChildren { declare readonly nodeType: 1; declare type: Shape.Element['type']; declare sourceCodeLocation?: Shape.TagSourceCodeLocation | null;
+  constructor(name: string, attribs: Record<string, string>, children: Shape.ChildNode[] = [], type?: Shape.Element['type']) {
+    super(); return initialize(this, type ?? (name === 'script' || name === 'style' ? name : 'tag'), { name, attribs }, children);
+  }
+}
+export interface Element extends Shape.Element {}
+
+/** @internal */
+export function nodePrototype(type: string): object {
+  return ({ root: Document, text: Text, comment: Comment, directive: ProcessingInstruction, cdata: CDATA, tag: Element, script: Element, style: Element }[type] ?? Node).prototype;
+}
+export const isTag = (node: Shape.Node): node is Shape.Element => ['tag', 'script', 'style'].includes(node.type);
+export const isText = (node: Shape.Node): node is Shape.Text => node.type === 'text';
+export const isComment = (node: Shape.Node): node is Shape.Comment => node.type === 'comment';
+export const isDirective = (node: Shape.Node): node is Shape.ProcessingInstruction => node.type === 'directive';
+export const isDocument = (node: Shape.Node): node is Shape.Document => node.type === 'root';
+export const isCDATA = (node: Shape.Node): node is Shape.CDATA => node.type === 'cdata';
+export const hasChildren = (node: Shape.Node): node is Shape.NodeWithChildren => 'children' in node;
+
+// DOM aliases live on their class prototypes, as they do in domhandler. Native
+// views intercept the underlying fields; external supplied nodes keep theirs.
+Object.defineProperties(Node.prototype, {
+  cloneNode: { configurable: true, writable: true, value: cloneNode },
+  parentNode: { configurable: true, get(this: Shape.Node) { return this.parent; }, set(this: Shape.Node, value: Shape.ParentNode | null) { this.parent = value; } },
+  previousSibling: { configurable: true, get(this: Shape.Node) { return this.prev; }, set(this: Shape.Node, value: Shape.ChildNode | null) { this.prev = value; } },
+  nextSibling: { configurable: true, get(this: Shape.Node) { return this.next; }, set(this: Shape.Node, value: Shape.ChildNode | null) { this.next = value; } },
+  nodeType: { configurable: true, get(this: Shape.Node) { return ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[this.type] ?? 1; } },
+});
+Object.defineProperty(DataNode.prototype, 'nodeValue', { configurable: true, get(this: Shape.DataNode) { return this.data; }, set(this: Shape.DataNode, value: string) { this.data = value; } });
+Object.defineProperties(NodeWithChildren.prototype, {
+  childNodes: { configurable: true, get(this: Shape.NodeWithChildren) { return this.children; }, set(this: Shape.NodeWithChildren, value: Shape.ChildNode[]) { this.children = value; } },
+  firstChild: { configurable: true, get(this: Shape.NodeWithChildren) { return this.children[0] ?? null; } },
+  lastChild: { configurable: true, get(this: Shape.NodeWithChildren) { return this.children[this.children.length - 1] ?? null; } },
+});
+Object.defineProperties(Element.prototype, {
+  tagName: { configurable: true, get(this: Shape.Element) { return this.name; }, set(this: Shape.Element, value: string) { this.name = value; } },
+  attributes: { configurable: true, get(this: Shape.Element) { return Object.keys(this.attribs).map((name) => ({ name, value: this.attribs[name], namespace: this['x-attribsNamespace']?.[name], prefix: this['x-attribsPrefix']?.[name] })); } },
+});

package/src/extract-plan.ts

@@ -0,0 +1,97 @@
+import type { CheerioOptions, ExtractMap } from './types.js';
+import { types } from 'node:util';
+
+export interface ExtractPlanEntry {
+  key: string;
+  selector: string;
+  all: boolean;
+  value: { kind: 'property'; name: string } | { kind: 'map'; entries: ExtractPlanEntry[] };
+}
+
+export interface ExtractPlan { version: 1; entries: ExtractPlanEntry[] }
+
+// Properties that can be returned as ordinary values. Properties returning DOM
+// views stay on the regular API so their identities and document leases survive.
+const scalarProperties = new Set([
+  'textContent', 'innerText', 'innerHTML', 'outerHTML', 'tagName', 'nodeName',
+  'nodeType', 'id', 'class', 'className', 'title', 'href', 'src', 'alt', 'name',
+  'value', 'type', 'checked', 'selected', 'disabled', 'multiple', 'readOnly',
+  'required', 'hidden', 'open', 'autofocus', 'controls', 'loop', 'muted',
+]);
+
+function dataValue(object: object, key: string): { value: unknown } | undefined {
+  for (let current: object | null = object; current; current = Object.getPrototypeOf(current)) {
+    if (types.isProxy(current)) return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(current, key);
+    if (descriptor) return 'value' in descriptor ? { value: descriptor.value } : undefined;
+  }
+  return { value: undefined };
+}
+
+/** Compile pure extraction maps. User callbacks and accessors keep JS semantics. */
+export function compileExtractPlan(map: ExtractMap, options: CheerioOptions): ExtractPlan | undefined {
+  if (options.pseudos || options.treeAdapter || options.Tokenizer || options.xml && typeof options.xml === 'object' && options.xml.Tokenizer) return undefined;
+  const ancestors = new Set<object>();
+  const compile = (input: unknown): ExtractPlanEntry[] | undefined => {
+    if (!input || typeof input !== 'object' || types.isProxy(input) || ancestors.has(input) || ancestors.size >= 64) return undefined;
+    for (let current = Object.getPrototypeOf(input); current; current = Object.getPrototypeOf(current)) {
+      if (types.isProxy(current)) return undefined;
+    }
+    ancestors.add(input);
+    try {
+      const entries: ExtractPlanEntry[] = [];
+      for (const key in input) {
+        // Cheerio uses an ordinary result object. Its legacy __proto__ setter
+        // semantics must execute through the JavaScript path.
+        if (key === '__proto__') return undefined;
+        const inherited = Object.getOwnPropertyDescriptor(Object.prototype, key);
+        if (inherited && (!('value' in inherited) || !inherited.writable)) return undefined;
+        const slot = dataValue(input, key);
+        if (!slot) return undefined;
+        const all = Array.isArray(slot.value);
+        if (slot.value && typeof slot.value === 'object' && types.isProxy(slot.value)) return undefined;
+        const first = all ? dataValue(slot.value as object, '0') : slot;
+        if (!first) return undefined;
+        const descriptor = first.value;
+        let selector: unknown;
+        let value: unknown;
+        if (typeof descriptor === 'string') { selector = descriptor; value = 'textContent'; }
+        else if (descriptor && typeof descriptor === 'object') {
+          if (types.isProxy(descriptor)) return undefined;
+          const selectorSlot = dataValue(descriptor, 'selector');
+          const valueSlot = dataValue(descriptor, 'value');
+          if (!selectorSlot || !valueSlot) return undefined;
+          selector = selectorSlot.value;
+          value = valueSlot.value ?? 'textContent';
+        } else return undefined;
+        if (typeof selector !== 'string') return undefined;
+        if (typeof value === 'string') {
+          if (!scalarProperties.has(value) && !/^(?:data-|aria-).+/.test(value)) return undefined;
+          entries.push({ key, selector, all, value: { kind: 'property', name: value } });
+        } else {
+          const nested = compile(value);
+          if (!nested) return undefined;
+          entries.push({ key, selector, all, value: { kind: 'map', entries: nested } });
+        }
+      }
+      return entries;
+    } finally { ancestors.delete(input); }
+  };
+  const entries = compile(map);
+  return entries && { version: 1, entries };
+}
+
+/** JSON omits undefined fields; restore them recursively without changing order. */
+export function hydrateExtractResult(result: Record<string, unknown>, entries: ExtractPlanEntry[]): void {
+  const values = entries.map((entry) => Object.hasOwn(result, entry.key) ? result[entry.key] : entry.all ? [] : undefined);
+  for (const entry of entries) delete result[entry.key];
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    Object.defineProperty(result, entry.key, { value: values[index], enumerable: true, configurable: true, writable: true });
+    if (entry.value.kind !== 'map') continue;
+    const nested = result[entry.key];
+    for (const value of entry.all && Array.isArray(nested) ? nested : [nested]) {
+      if (value && typeof value === 'object' && !Array.isArray(value)) hydrateExtractResult(value as Record<string, unknown>, entry.value.entries);
+    }
+  }
+}