rusteerio 1.0.0 → 1.1.0

package/src/nodes.ts

@@ -1,16 +1,24 @@
 import type { NativeDocument, NativeNodeRecord } from './native.js';
+import type { NodeSnapshot } from './snapshot.js';
 import type { AnyNode } from './types.js';
 import { nodePrototype } from './dom.js';
-import { sameNodeSpace } from './router.js';
+import { cachedView, cacheView, exposeTo, isLocalState, isRouted, onViewRefresh, plainSnapshot, recordAt, routedFor, stateIn, VIEW_ATTRIBUTES, VIEW_CHILD_TARGET, VIEW_LOCAL, VIEW_SELF, VIEW_STATE, type DocumentState } from './router.js';
 
 export interface NodeBinding { document: NativeDocument; id: number }
-interface ViewState { document: NativeDocument; id: number; lease?: object; children?: AnyNode[]; attributes?: Record<string, string>; maps?: Record<string, Record<string, string>> }
-interface NodeState { views: WeakMap<object, ViewState>; bindings: WeakMap<object, NodeBinding>; caches: WeakMap<object, Map<number, WeakRef<AnyNode>>>; finalizer: FinalizationRegistry<{ cache: Map<number, WeakRef<AnyNode>>; id: number }> }
-const nodeStateKey = Symbol.for('rusteerio.native-node-views.v2');
-const nodeGlobals = globalThis as typeof globalThis & { [key: symbol]: NodeState | undefined };
-const nodeState: NodeState = nodeGlobals[nodeStateKey] ??= { views: new WeakMap(), bindings: new WeakMap(), caches: new WeakMap(), finalizer: new FinalizationRegistry(({ cache, id }) => { if (!cache.get(id)?.deref()) cache.delete(id); }) };
-const { bindings, caches } = nodeState;
+
+/** A node object: its fields read the native record for the node's current location. */
+interface View { [VIEW_STATE]: DocumentState; [VIEW_LOCAL]: number; [VIEW_SELF]: View; [VIEW_ATTRIBUTES]: AttributeView | undefined; [VIEW_CHILDREN]: AnyNode[] | undefined; [VIEW_CHILD_TARGET]: AnyNode[] | undefined; [key: string]: any }
+/** A plain attribute object that mirrors the record; its proxy only intercepts writes. */
+/**
+ * The handler of a node's attribute proxy, which also keeps the proxy's plain
+ * target and the generation it was copied in, so each attribute object costs
+ * one target, one handler and one proxy.
+ */
+interface AttributeView extends ProxyHandler<Record<string, string>> { view: View; proxy: Record<string, string>; target: Record<string, string>; generation: number; state: DocumentState }
+
+const VIEW_CHILDREN = Symbol.for('rusteerio.node.children');
 const arrayIndex = /^(?:0|[1-9]\d*)$/;
+const emptyRecord = Object.freeze({ id: -1, type: 'released', children: [] }) as unknown as NativeNodeRecord;
 
 export function operation<T = any>(document: NativeDocument, command: string, args: unknown = {}): T {
   const direct = (document as NativeDocument & { operate?(command: string, args: unknown): T }).operate;
@@ -19,13 +27,34 @@ export function operation<T = any>(document: NativeDocument, command: string, ar
   return (value === undefined || value === '' ? undefined : JSON.parse(value)) as T;
 }
 
+/** The id of a native node object, without allocating a binding. */
+export function viewId(node: unknown): number | undefined {
+  const view = node as View | null | undefined;
+  const state = view?.[VIEW_STATE];
+  return state !== undefined && view![VIEW_SELF] === view && isLocalState(state) ? state.base + view![VIEW_LOCAL] : undefined;
+}
+
+/** Whether `node` is a node object of a native document, of this or another copy of the package. */
+function isNativeNode(node: unknown): boolean {
+  const view = node as View | null | undefined;
+  return view?.[VIEW_STATE] !== undefined && view[VIEW_SELF] === view;
+}
+
+/** The id of a native node object, made resolvable by `document`'s operations. */
+export function viewIdIn(document: NativeDocument, node: unknown): number | undefined {
+  const id = viewId(node);
+  if (id !== undefined) exposeTo(document, (node as View)[VIEW_STATE]);
+  return id;
+}
+
 export function nodeBinding(node: unknown): NodeBinding | undefined {
-  return node && typeof node === 'object' ? bindings.get(node) : undefined;
+  const id = node && typeof node === 'object' ? viewId(node) : undefined;
+  return id === undefined ? undefined : { document: routedFor((node as View)[VIEW_STATE]), id };
 }
 
 export function nodeId(node: unknown, document?: NativeDocument): number | undefined {
-  const binding = nodeBinding(node);
-  return binding && (!document || sameNodeSpace(document, binding.document)) ? binding.id : undefined;
+  const id = node && typeof node === 'object' ? viewId(node) : undefined;
+  return id !== undefined && (!document || isRouted(document)) ? id : undefined;
 }
 
 /** Recreate parse5's null-prototype attribute maps and shared start-tag map. */
@@ -40,201 +69,515 @@ export function hydrateLocation<T>(location: T): T {
   return location;
 }
 
+/** The node's record; its links are ids local to the node's document. */
 export function nodeRecord(document: NativeDocument, id: number): NativeNodeRecord {
-  return operation(document, 'node', { id });
+  if (!isRouted(document)) return operation(document, 'node', { id });
+  const state = stateIn(document, id);
+  return recordAt(state, id - state.base) as NativeNodeRecord;
+}
+
+const isElementType = (type: string | undefined): boolean => type === 'tag' || type === 'script' || type === 'style';
+
+/** Mirrors the native `traverse` operation over cached records; `undefined` defers to it. */
+export function traverseRecords(document: NativeDocument, ids: number[], kind: string): number[] | undefined {
+  if (!isRouted(document)) return undefined;
+  const result: number[] = [];
+  for (const id of ids) {
+    const state = stateIn(document, id);
+    const { base } = state;
+    const node = recordAt(state, id - base);
+    if (!node) continue;
+    const isElement = (local: number): boolean => isElementType(recordAt(state, local)?.type);
+    if (kind === 'children') {
+      for (const child of node.children ?? []) if (isElement(child)) result.push(base + child);
+    } else if (kind === 'contents') {
+      for (const child of node.children ?? []) result.push(base + child);
+    } else if (kind === 'parent') {
+      if (node.parent != null && isElement(node.parent)) result.push(base + node.parent);
+    } else if (kind === 'parents' || kind === 'ancestors') {
+      const seen = new Set<number>();
+      for (let parent = node.parent; parent != null && !seen.has(parent);) {
+        seen.add(parent);
+        const ancestor = recordAt(state, parent);
+        if (!ancestor || ancestor.type === 'root') break;
+        if (isElementType(ancestor.type)) result.push(base + parent);
+        parent = ancestor.parent;
+      }
+    } else if (kind === 'next' || kind === 'prev' || kind === 'nextAll' || kind === 'prevAll') {
+      const isForward = kind === 'next' || kind === 'nextAll';
+      const isSingle = kind === 'next' || kind === 'prev';
+      const seen = new Set<number>();
+      for (let sibling = isForward ? node.next : node.prev; sibling != null && !seen.has(sibling);) {
+        seen.add(sibling);
+        const record = recordAt(state, sibling);
+        if (!record) break;
+        if (isElementType(record.type)) {
+          result.push(base + sibling);
+          if (isSingle) break;
+        }
+        sibling = isForward ? record.next : record.prev;
+      }
+    } else if (kind === 'siblings') {
+      const parent = node.parent == null ? null : recordAt(state, node.parent);
+      const local = id - base;
+      for (const other of parent?.children ?? []) if (other !== local && isElement(other)) result.push(base + other);
+    } else return undefined;
+  }
+  return result;
+}
+
+/** The node object for an arena slot, created on first use and then shared. */
+export function viewAt(state: DocumentState, local: number): AnyNode | undefined {
+  const existing = state.views[local] ?? cachedView(state, local);
+  if (existing) return existing as AnyNode;
+  const parsed = state.adapterNodes?.[local];
+  if (parsed) { state.adapterNodes![local] = undefined; return adoptObject(state, local, parsed); }
+  const snapshot = plainSnapshot(state, local);
+  let constructor: ViewConstructor;
+  if (snapshot) constructor = viewConstructor(snapshot.typeOf(local), false);
+  else {
+    const record = recordAt(state, local);
+    if (!record) return undefined;
+    constructor = viewConstructor(record.type, record.sourceCodeLocation !== undefined);
+  }
+  const view = new constructor(state, local);
+  cacheView(state, local, view);
+  return view as unknown as AnyNode;
+}
+
+/** A document root's node object, built without reading its record: its type is known. */
+export function rootNode(document: NativeDocument, id: number): AnyNode {
+  if (!isRouted(document)) throw new TypeError('Native nodes require a routed document');
+  const state = stateIn(document, id);
+  const local = id - state.base;
+  const existing = cachedView(state, local);
+  if (existing) return existing as AnyNode;
+  if (state.adapterNodes?.[local] || state.options.sourceCodeLocationInfo) return viewAt(state, local) as AnyNode;
+  const view = new (viewConstructor('root', false))(state, local);
+  cacheView(state, local, view);
+  return view as unknown as AnyNode;
+}
+
+/** Stable DOM node identities; each property reads or updates the Rust arena. */
+export function getNode(document: NativeDocument, id: number, original?: any): AnyNode {
+  if (!isRouted(document)) throw new TypeError('Native nodes require a routed document');
+  const state = stateIn(document, id);
+  const local = id - state.base;
+  if (original === undefined) return viewAt(state, local) as AnyNode;
+  return adoptObject(state, local, original);
 }
 
-function setField(document: NativeDocument, id: number, field: string, value: unknown): void {
-  operation(document, 'setNode', { id, field, value });
+function viewRecord(view: View): NativeNodeRecord {
+  const state = view[VIEW_STATE];
+  const local = view[VIEW_LOCAL];
+  return state.records[local] ?? recordAt(state, local) ?? emptyRecord;
 }
 
-function attributes(document: NativeDocument, id: number, field = 'attribs', prototype: object | null = (document as NativeDocument & { options?: { _useHtmlParser2?: boolean } }).options?._useHtmlParser2 === false ? null : Object.prototype): Record<string, string> {
-  const read = () => (nodeRecord(document, id) as any)?.[field] ?? {};
-  const target = Object.create(prototype);
+function linkedView(view: View, local: number | null | undefined): AnyNode | null {
+  return local == null ? null : viewAt(view[VIEW_STATE], local) ?? null;
+}
+
+function setField(view: View, field: string, value: unknown): void {
+  const state = view[VIEW_STATE];
+  operation(routedFor(state), 'setNode', { id: state.base + view[VIEW_LOCAL], field, value });
+}
+
+function setPointer(view: View, field: string, value: unknown): void {
+  setField(view, field, value == null ? null : importNodes(routedFor(view[VIEW_STATE]), [value])[0]);
+}
+
+function attributesOf(view: View): Record<string, string> {
+  const state = view[VIEW_STATE];
+  let attributes = view[VIEW_ATTRIBUTES];
+  if (!attributes) view[VIEW_ATTRIBUTES] = attributes = createAttributes(view, state.options._useHtmlParser2 === false ? null : Object.prototype);
+  if (attributes.generation !== state.generation || attributes.state !== state) syncAttributes(view, attributes);
+  return attributes.proxy;
+}
+
+function createAttributes(view: View, prototype: object | null): AttributeView {
+  const target: Record<string, string> = Object.create(prototype);
+  // The node lives on the proxy's own handler, so the attribute object stays plain to reflection.
+  const handler: AttributeView = Object.create(attributeWrites);
+  handler.view = view;
+  handler.target = target;
+  handler.generation = -1;
+  handler.state = view[VIEW_STATE];
+  handler.proxy = new Proxy(target, handler);
+  return handler;
+}
+
+/** Copies the record's attributes into the plain target, preserving key order. */
+function syncAttributes(view: View, attributes: AttributeView): void {
+  const { target } = attributes;
+  const state = view[VIEW_STATE];
+  const local = view[VIEW_LOCAL];
+  if (attributes.generation === -1) {
+    const snapshot = plainSnapshot(state, local);
+    if (snapshot) {
+      snapshot.copyAttributes(local, target);
+      attributes.generation = state.generation;
+      return;
+    }
+  }
+  const values = viewRecord(view).attribs ?? {};
+  const keys = Object.keys(target);
+  const nextKeys = Object.keys(values);
+  let isSameOrder = keys.length === nextKeys.length;
+  for (let index = 0; isSameOrder && index < keys.length; index++) isSameOrder = keys[index] === nextKeys[index];
+  if (!isSameOrder) for (const key of keys) delete target[key];
+  for (const key of nextKeys) {
+    if (isSameOrder && target[key] === values[key]) continue;
+    if (key === '__proto__') Object.defineProperty(target, key, { value: values[key], writable: true, enumerable: true, configurable: true });
+    else target[key] = values[key];
+  }
+  attributes.generation = view[VIEW_STATE].generation;
+  attributes.state = view[VIEW_STATE];
+}
+
+/** Re-reads attributes for a node whose attributes a native command changed. */
+function refreshAttributes(view: object): void {
+  const attributes = (view as View)[VIEW_ATTRIBUTES];
+  if (attributes) syncAttributes(view as View, attributes);
+}
+onViewRefresh(refreshAttributes, fillChildren);
+
+/** Reads go straight to the plain target; writes go to Rust, which then refreshes the target. */
+const attributeWrites: ProxyHandler<Record<string, string>> = {
+  set(this: AttributeView, target, key, value) {
+    if (typeof key === 'symbol') return Reflect.set(target, key, value);
+    const view = this.view;
+    setField(view, 'attribs', { ...viewRecord(view).attribs, [key]: String(value) });
+    syncAttributes(view, view[VIEW_ATTRIBUTES]!);
+    return true;
+  },
+  deleteProperty(this: AttributeView, target, key) {
+    if (typeof key === 'symbol') return Reflect.deleteProperty(target, key);
+    const view = this.view;
+    const values = { ...viewRecord(view).attribs };
+    delete values[key];
+    setField(view, 'attribs', values);
+    syncAttributes(view, view[VIEW_ATTRIBUTES]!);
+    return true;
+  },
+  defineProperty(this: AttributeView, target, key, descriptor) {
+    if (typeof key === 'symbol') return Reflect.defineProperty(target, key, descriptor);
+    const view = this.view;
+    setField(view, 'attribs', { ...viewRecord(view).attribs, [key]: String(descriptor.value) });
+    syncAttributes(view, view[VIEW_ATTRIBUTES]!);
+    return true;
+  },
+};
+
+/** Namespace and prefix maps are rare; they read the record on every access. */
+function attributeMap(view: View, field: 'attribsNamespace' | 'attribsPrefix'): Record<string, string> {
+  const read = (): Record<string, string> => (viewRecord(view) as any)[field] ?? {};
+  const target = Object.create(view[VIEW_STATE].options._useHtmlParser2 === false ? null : Object.prototype);
+  const viewField = `x-${field}`;
   return new Proxy(target, {
-    get(_target, key) { return typeof key === 'symbol' ? Reflect.get(target, key) : Object.hasOwn(read(), key) ? read()[key] : Reflect.get(target, key); },
-    set(_target, key, value) { setField(document, id, field, { ...read(), [key]: String(value) }); return true; },
-    deleteProperty(_target, key) { const values = { ...read() }; delete values[key]; setField(document, id, field, values); return true; },
+    get(_target, key) {
+      if (typeof key === 'symbol') return Reflect.get(target, key);
+      const values = read();
+      return Object.hasOwn(values, key) ? values[key] : Reflect.get(target, key);
+    },
+    set(_target, key, value) { setField(view, viewField, { ...read(), [key]: String(value) }); return true; },
+    deleteProperty(_target, key) { const values = { ...read() }; delete values[key as string]; setField(view, viewField, values); return true; },
     ownKeys() { return Reflect.ownKeys(read()); },
     has(_target, key) { return Object.hasOwn(read(), key) || key in target; },
-    getOwnPropertyDescriptor(_target, key) { return Object.hasOwn(read(), key) ? { value: read()[key], writable: true, enumerable: true, configurable: true } : undefined; },
-    defineProperty(_target, key, descriptor) { const values = { ...read(), [key]: String(descriptor.value) }; setField(document, id, field, values); return true; },
+    getOwnPropertyDescriptor(_target, key) { const values = read(); return Object.hasOwn(values, key) ? { value: values[key as string], writable: true, enumerable: true, configurable: true } : undefined; },
+    defineProperty(_target, key, descriptor) { setField(view, viewField, { ...read(), [key]: String(descriptor.value) }); return true; },
   });
 }
 
-function children(document: NativeDocument, id: number): AnyNode[] {
-  const read = (): number[] => nodeRecord(document, id)?.children ?? [];
-  const snapshot = () => read().map((child) => getNode(document, child));
-  const save = (nodes: unknown[]) => setField(document, id, 'children', importNodes(document, nodes));
-  const mutating = new Set(['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'copyWithin', 'fill']);
-  const target: AnyNode[] = [];
-  return new Proxy(target, {
-    get(_target, key, receiver) {
-      if (key === 'length') return read().length;
-      if (typeof key === 'string' && arrayIndex.test(key)) { const child = read()[Number(key)]; return child === undefined ? undefined : getNode(document, child); }
-      if (typeof key === 'string' && mutating.has(key)) return (...args: unknown[]) => {
-        const values = snapshot();
-        const result = Reflect.apply((Array.prototype as any)[key], values, args);
-        save(values);
-        return result === values ? receiver : result;
-      };
-      return Reflect.get(target, key, receiver);
-    },
-    set(_target, key, value) {
-      const values = snapshot();
-      if (key === 'length') values.length = value;
-      else if (typeof key === 'string' && arrayIndex.test(key)) values[Number(key)] = value;
-      else return Reflect.set(target, key, value);
-      save(values); return true;
-    },
-    deleteProperty(_target, key) { if (typeof key === 'string' && arrayIndex.test(key)) { const values = snapshot(); values.splice(Number(key), 1); save(values); return true; } return Reflect.deleteProperty(target, key); },
-    has(_target, key) { return typeof key === 'string' && arrayIndex.test(key) ? Number(key) < read().length : Reflect.has(target, key); },
-    ownKeys() { return [...read().map((_child, i) => String(i)), 'length']; },
-    getOwnPropertyDescriptor(_target, key) {
-      if (key === 'length') return { ...Reflect.getOwnPropertyDescriptor(target, 'length')!, value: read().length };
-      if (typeof key === 'string' && arrayIndex.test(key) && Number(key) < read().length) return { value: getNode(document, read()[Number(key)]), writable: true, enumerable: true, configurable: true };
-      return Reflect.getOwnPropertyDescriptor(target, key);
+/**
+ * A node's children: a real array of node objects, so reads cost what
+ * Cheerio's do. Its mutating methods write the whole list to Rust once, and
+ * the router refills the array in place whenever Rust reports the parent
+ * changed. Assigning an index or `length` directly changes only this array.
+ * `constructor` is `Array`, so arrays derived from it are plain.
+ */
+class ChildArray extends Array<AnyNode> {
+  readonly #view: View;
+  constructor(view: View) {
+    super();
+    this.#view = view;
+  }
+  static viewOf(list: unknown): View | undefined {
+    return list instanceof ChildArray ? list.#view : undefined;
+  }
+}
+Object.defineProperty(ChildArray.prototype, 'constructor', { configurable: true, writable: true, value: Array });
+for (const method of ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'copyWithin', 'fill'] as const) {
+  Object.defineProperty(ChildArray.prototype, method, {
+    configurable: true, writable: true,
+    value(this: ChildArray, ...args: unknown[]) {
+      const view = ChildArray.viewOf(this);
+      if (!view) return Reflect.apply((Array.prototype as any)[method], this, args);
+      const values = Array.from(this);
+      const result = Reflect.apply((Array.prototype as any)[method], values, args);
+      saveChildren(view, values);
+      return result === values ? this : result;
     },
   });
 }
 
-const parentAliases: Record<string, string> = { parentNode: 'parent', previousSibling: 'prev', nextSibling: 'next' };
-const sourceFields = new Set(['type', 'name', 'data', 'namespace', 'prefix', 'startIndex', 'endIndex', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode']);
-const tagTypes = new Set(['tag', 'script', 'style']);
-const parentTypes = new Set(['root', 'tag', 'script', 'style', 'cdata']);
-const dataTypes = new Set(['text', 'comment', 'directive']);
-function viewKeys(record: NativeNodeRecord): string[] {
-  const keys = ['parent', 'prev', 'next', 'startIndex', 'endIndex'];
-  if (parentTypes.has(record.type)) keys.push('children');
-  if (record.data !== undefined) keys.push('data');
-  if (record.name !== undefined) keys.push('name');
-  if (tagTypes.has(record.type)) keys.push('attribs');
-  keys.push('type');
-  for (const field of sourceFields) if (!keys.includes(field) && field in record) keys.push(field);
-  if (tagTypes.has(record.type)) {
-    if ('attribsNamespace' in record) keys.push('x-attribsNamespace');
-    if ('attribsPrefix' in record) keys.push('x-attribsPrefix');
-  }
-  return keys;
-}
-function viewValue(state: ViewState, key: string, receiver: any): any {
-  const { document, id } = state;
-  const record = nodeRecord(document, id);
-  if (key === 'cloneNode') return cloneNode;
-  if (key === 'nodeType') return ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[record.type] ?? 1;
-  if (key === 'tagName' && tagTypes.has(record.type)) return record.name;
-  if (key === 'nodeValue' && dataTypes.has(record.type)) return record.data;
-  const pointer = parentAliases[key] ?? key;
-  if (['parent', 'prev', 'next'].includes(pointer)) return record[pointer] == null ? null : getNode(document, record[pointer]);
-  if (['children', 'childNodes', 'firstChild', 'lastChild'].includes(key) && parentTypes.has(record.type)) {
-    const list = state.children ??= children(document, id);
-    return key === 'firstChild' ? list[0] ?? null : key === 'lastChild' ? list[list.length - 1] ?? null : list;
+function saveChildren(view: View, values: unknown[]): void {
+  setField(view, 'children', importNodes(routedFor(view[VIEW_STATE]), values));
+}
+
+function childList(view: View): AnyNode[] {
+  const existing = view[VIEW_CHILDREN];
+  if (existing) return existing;
+  const state = view[VIEW_STATE];
+  if (!state.hasChildLists) { state.hasChildLists = true; state.raw.takeTouched?.(); }
+  const list = new ChildArray(view);
+  view[VIEW_CHILD_TARGET] = list;
+  view[VIEW_CHILDREN] = list;
+  fillChildren(view);
+  return list;
+}
+
+/** Rebuilds a materialized child array from the node's current record. */
+function fillChildren(view: object): void {
+  const target = (view as View)[VIEW_CHILD_TARGET];
+  if (!target) return;
+  const state = (view as View)[VIEW_STATE];
+  const local = (view as View)[VIEW_LOCAL];
+  const snapshot = plainSnapshot(state, local);
+  if (snapshot && state.stale.size === 0) {
+    fillFromSnapshot(state, snapshot, local, target);
+    return;
   }
-  if (key === 'attribs' && tagTypes.has(record.type)) return state.attributes ??= attributes(document, id);
-  if ((key === 'x-attribsNamespace' && 'attribsNamespace' in record || key === 'x-attribsPrefix' && 'attribsPrefix' in record) && tagTypes.has(record.type)) {
-    state.maps ??= {};
-    return state.maps[key] ??= attributes(document, id, key === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix');
+  const locals = viewRecord(view as View).children ?? [];
+  target.length = locals.length;
+  for (let index = 0; index < locals.length; index++) target[index] = viewAt(state, locals[index])!;
+}
+
+/**
+ * The common case of a walk: a node's children read straight from the
+ * snapshot arrays and cached strongly, with each type's constructor resolved
+ * once per snapshot instead of once per node.
+ */
+function fillFromSnapshot(state: DocumentState, snapshot: NodeSnapshot, local: number, target: AnyNode[]): void {
+  const count = snapshot.childCount(local);
+  const first = snapshot.childStart(local);
+  const childIds = snapshot.childIds;
+  const views = state.views;
+  const isStrong = !state.adapterNodes;
+  const constructors = snapshotConstructors(snapshot);
+  target.length = count;
+  for (let index = 0; index < count; index++) {
+    const child = childIds[first + index];
+    let node = (views[child] ?? (state.weakViews.size ? cachedView(state, child) : undefined)) as AnyNode | undefined;
+    if (node === undefined) {
+      const constructor = isStrong && child < state.baseline && snapshot.isPlain(child) ? constructors(snapshot.typeReference(child)) : undefined;
+      if (constructor) views[child] = node = new constructor(state, child) as unknown as AnyNode;
+      else node = viewAt(state, child)!;
+    }
+    target[index] = node;
   }
-  if (key === 'attributes' && tagTypes.has(record.type)) {
-    const attrs = state.attributes ??= attributes(document, id);
-    return Object.keys(attrs).map((name) => ({ name, value: attrs[name], namespace: record.attribsNamespace?.[name], prefix: record.attribsPrefix?.[name] }));
+}
+
+function snapshotConstructors(snapshot: NodeSnapshot): (reference: number) => ViewConstructor {
+  let lookup = snapshot.viewConstructors as ((reference: number) => ViewConstructor) | undefined;
+  if (!lookup) {
+    const byReference: ViewConstructor[] = [];
+    lookup = (reference) => byReference[reference] ??= viewConstructor(snapshot.name(reference), false);
+    snapshot.viewConstructors = lookup;
   }
-  if (key === 'sourceCodeLocation') return hydrateLocation(record[key]);
-  if (sourceFields.has(key)) return record[key] ?? (key === 'startIndex' || key === 'endIndex' ? null : undefined);
-  return undefined;
-}
-function writeView(state: ViewState, key: string, value: any): boolean {
-  const { document, id } = state;
-  const record = nodeRecord(document, id);
-  if (key === 'tagName' && tagTypes.has(record.type)) key = 'name';
-  else if (key === 'nodeValue' && dataTypes.has(record.type)) key = 'data';
-  else if (key === 'childNodes') key = 'children';
-  else key = parentAliases[key] ?? key;
-  if (sourceFields.has(key) || ['attribs', 'x-attribsNamespace', 'x-attribsPrefix'].includes(key)) { setField(document, id, key, value); return true; }
-  if (key === 'children' && parentTypes.has(record.type)) { setField(document, id, key, importNodes(document, value)); return true; }
-  if (['parent', 'prev', 'next'].includes(key)) { setField(document, id, key, value == null ? null : importNodes(document, [value])[0]); return true; }
-  return false;
-}
-const nodeHandler: ProxyHandler<object> = {
-  get(target, key, receiver) {
-    if (Reflect.getOwnPropertyDescriptor(target, key)) return Reflect.get(target, key, receiver);
-    if (typeof key === 'string') {
-      const state = nodeState.views.get(target)!;
-      if (key === 'cloneNode' || key === 'nodeType' || sourceFields.has(key) || ['tagName', 'nodeValue', 'parent', 'prev', 'next', 'parentNode', 'previousSibling', 'nextSibling', 'children', 'childNodes', 'firstChild', 'lastChild', 'attribs', 'attributes', 'x-attribsNamespace', 'x-attribsPrefix'].includes(key)) return viewValue(state, key, receiver);
-    }
-    return Reflect.get(target, key, receiver);
-  },
-  set(target, key, value, receiver) {
-    if (Reflect.getOwnPropertyDescriptor(target, key)) return Reflect.set(target, key, value, receiver);
-    if (typeof key === 'string' && writeView(nodeState.views.get(target)!, key, value)) return true;
-    return Reflect.set(target, key, value, receiver);
+  return lookup;
+}
+
+type Accessor = { get(this: View): unknown; set(this: View, value: any): void };
+const recordField = (field: string, fallback?: null): Accessor => ({
+  get() { return (viewRecord(this) as any)[field] ?? fallback; },
+  set(value) { setField(this, field, value); },
+});
+/** Fields read straight from the snapshot when it holds the node, without building a record. */
+const snapshotField = (field: 'type' | 'name' | 'data'): Accessor => ({
+  get() {
+    const state = this[VIEW_STATE];
+    const local = this[VIEW_LOCAL];
+    const snapshot = plainSnapshot(state, local);
+    if (snapshot) return field === 'type' ? snapshot.typeOf(local) : field === 'name' ? snapshot.nameOf(local) : snapshot.dataOf(local);
+    return (viewRecord(this) as any)[field];
   },
-  has(target, key) { return Reflect.has(target, key) || typeof key === 'string' && (viewKeys(nodeRecord(nodeState.views.get(target)!.document, nodeState.views.get(target)!.id)).includes(key) || ['cloneNode', 'nodeType', 'parentNode', 'previousSibling', 'nextSibling'].includes(key)); },
-  ownKeys(target) { const state = nodeState.views.get(target)!; return [...new Set([...viewKeys(nodeRecord(state.document, state.id)), ...Reflect.ownKeys(target)])]; },
-  getOwnPropertyDescriptor(target, key) {
-    const existing = Reflect.getOwnPropertyDescriptor(target, key);
-    if (existing) return existing;
-    const state = nodeState.views.get(target)!;
-    if (typeof key === 'string' && viewKeys(nodeRecord(state.document, state.id)).includes(key)) return { value: viewValue(state, key, undefined), configurable: true, enumerable: true, writable: true };
-    return undefined;
+  set(value) { setField(this, field, value); },
+});
+const linkOffsets = { parent: 1, prev: 2, next: 3 } as const;
+const pointerField = (field: 'parent' | 'prev' | 'next'): Accessor => ({
+  get() {
+    const state = this[VIEW_STATE];
+    const local = this[VIEW_LOCAL];
+    const snapshot = plainSnapshot(state, local);
+    return linkedView(this, snapshot ? snapshot.linkOf(local, linkOffsets[field]) : viewRecord(this)[field]);
   },
+  set(value) { setPointer(this, field, value); },
+});
+const nodeAccessors: Record<string, Accessor> = {
+  type: snapshotField('type'),
+  parent: pointerField('parent'),
+  prev: pointerField('prev'),
+  next: pointerField('next'),
+  startIndex: recordField('startIndex', null),
+  endIndex: recordField('endIndex', null),
+};
+/** Present only on nodes parsed with location info, as in Cheerio. */
+const locationAccessor: Accessor = { get() { return hydrateLocation(viewRecord(this).sourceCodeLocation); }, set(value) { setField(this, 'sourceCodeLocation', value); } };
+const childAccessors: Record<string, Accessor> = {
+  children: { get() { return childList(this); }, set(value) { setField(this, 'children', importNodes(routedFor(this[VIEW_STATE]), value)); } },
 };
+const elementAccessors: Record<string, Accessor> = {
+  name: snapshotField('name'),
+  attribs: { get() { return attributesOf(this); }, set(value) { setField(this, 'attribs', value); } },
+  namespace: recordField('namespace'),
+  prefix: recordField('prefix'),
+  'x-attribsNamespace': { get() { return viewRecord(this).attribsNamespace !== undefined ? attributeMap(this, 'attribsNamespace') : undefined; }, set(value) { setField(this, 'x-attribsNamespace', value); } },
+  'x-attribsPrefix': { get() { return viewRecord(this).attribsPrefix !== undefined ? attributeMap(this, 'attribsPrefix') : undefined; }, set(value) { setField(this, 'x-attribsPrefix', value); } },
+};
+const dataAccessors: Record<string, Accessor> = { data: snapshotField('data') };
+const directiveAccessors: Record<string, Accessor> = { name: recordField('name'), 'x-name': recordField('x-name'), 'x-publicId': recordField('x-publicId'), 'x-systemId': recordField('x-systemId') };
+const documentAccessors: Record<string, Accessor> = { 'x-mode': recordField('x-mode') };
 
-/** Stable DOM node identities; each property reads or updates the Rust arena. */
-export function getNode(document: NativeDocument, id: number, original?: any): AnyNode {
-  const cacheKey = document.nodeSpace ?? document;
-  let cache = caches.get(cacheKey);
-  if (!cache) caches.set(cacheKey, cache = new Map());
-  const existing = cache.get(id)?.deref();
-  if (existing) return existing;
-  document = (document as NativeDocument & { nodeDocument?(id: number): NativeDocument }).nodeDocument?.(id) ?? document;
-  const lease = (document as NativeDocument & { retainNodes?(ids: number[]): object }).retainNodes?.([id]);
-  const record = nodeRecord(document, id);
-  if (!record) return undefined as unknown as AnyNode;
-  if (original === undefined) {
-    const target = Object.create(nodePrototype(record.type));
-    const node = new Proxy(target, nodeHandler) as AnyNode;
-    nodeState.views.set(target, { document, id, lease });
-    cache.set(id, new WeakRef(node));
-    nodeState.finalizer.register(node, { cache, id });
-    bindings.set(node, { document, id });
-    return node;
+function accessorsFor(type: string): Record<string, Accessor> {
+  switch (type) {
+    case 'tag': case 'script': case 'style': return { ...nodeAccessors, ...childAccessors, ...elementAccessors };
+    case 'root': return { ...nodeAccessors, ...childAccessors, ...documentAccessors };
+    case 'cdata': return { ...nodeAccessors, ...childAccessors };
+    case 'directive': return { ...nodeAccessors, ...dataAccessors, ...directiveAccessors };
+    case 'text': case 'comment': return { ...nodeAccessors, ...dataAccessors };
+    default: return { ...nodeAccessors, ...childAccessors, ...dataAccessors, name: recordField('name') };
   }
-  const node: any = original;
-  cache.set(id, new WeakRef(node));
-  nodeState.finalizer.register(node, { cache, id });
-  bindings.set(node, { document, id });
-  const read = (): any => { void lease; return nodeRecord(document, id); };
-  const define = (key: string, get: () => unknown, set?: (value: any) => void, enumerable = true) => {
-    try { Object.defineProperty(node, key, { configurable: true, enumerable, get, ...(set ? { set } : {}) }); } catch { /* Foreign user properties may be non-configurable. */ }
-  };
-  for (const field of ['type', 'name', 'data', 'namespace', 'prefix', 'startIndex', 'endIndex', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode']) {
-    if (field in record || ['type', 'startIndex', 'endIndex'].includes(field)) define(field, () => (field === 'sourceCodeLocation' ? hydrateLocation(read()[field]) : read()[field]) ?? (field === 'startIndex' || field === 'endIndex' ? null : undefined), (value) => setField(document, id, field, value));
+}
+
+type ViewConstructor = new (state: DocumentState, local: number) => View;
+const viewConstructors = new Map<string, ViewConstructor>();
+const plainConstructors: Record<string, ViewConstructor | undefined> = Object.create(null);
+
+/** One constructor per node shape so node objects share a hidden class and prototype. */
+function viewConstructor(type: string, hasLocation: boolean): ViewConstructor {
+  if (!hasLocation) { const plain = plainConstructors[type]; if (plain) return plain; }
+  const key = hasLocation ? `${type}:location` : type;
+  let constructor = viewConstructors.get(key);
+  if (constructor) return constructor;
+  const prototype = Object.create(nodePrototype(type));
+  const accessors = hasLocation ? { ...accessorsFor(type), sourceCodeLocation: locationAccessor } : accessorsFor(type);
+  for (const [field, accessor] of Object.entries(accessors)) Object.defineProperty(prototype, field, { ...accessor, configurable: true, enumerable: false });
+  constructor = function (this: View, state: DocumentState, local: number) {
+    this[VIEW_STATE] = state;
+    this[VIEW_LOCAL] = local;
+    this[VIEW_SELF] = this;
+    this[VIEW_ATTRIBUTES] = undefined;
+    this[VIEW_CHILDREN] = undefined;
+    this[VIEW_CHILD_TARGET] = undefined;
+  } as unknown as ViewConstructor;
+  Object.defineProperty(prototype, inspectSymbol, { configurable: true, writable: true, value: inspectNode });
+  constructor.prototype = prototype;
+  viewConstructors.set(key, constructor);
+  if (!hasLocation) plainConstructors[type] = constructor;
+  return constructor;
+}
+
+const inspectSymbol = Symbol.for('nodejs.util.inspect.custom');
+const inspectedFields = ['type', 'name', 'data', 'attribs', 'namespace', 'startIndex', 'endIndex'];
+
+/** Console output shows the node's fields instead of its native bookkeeping. */
+function inspectNode(this: View, depth: number, options: object, inspect: (value: unknown, options: object) => string): string {
+  const fields: Record<string, unknown> = {};
+  for (const field of inspectedFields) if (field in this && this[field] != null) fields[field] = field === 'attribs' ? { ...this.attribs } : this[field];
+  if ('children' in this) fields.children = `[${this.children.length} nodes]`;
+  const name = Object.getPrototypeOf(Object.getPrototypeOf(this))?.constructor?.name ?? 'Node';
+  return depth < 0 ? `[${name}]` : `${name} ${inspect(fields, { ...options, depth: 1 })}`;
+}
+
+const adoptedAliases: PropertyDescriptorMap = {
+  parentNode: { configurable: true, enumerable: false, get(this: View) { return this.parent; }, set(this: View, value) { this.parent = value; } },
+  previousSibling: { configurable: true, enumerable: false, get(this: View) { return this.prev; }, set(this: View, value) { this.prev = value; } },
+  nextSibling: { configurable: true, enumerable: false, get(this: View) { return this.next; }, set(this: View, value) { this.next = value; } },
+  nodeType: { configurable: true, enumerable: false, get(this: View) { return ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[viewRecord(this).type] ?? 1; } },
+  cloneNode: { configurable: true, enumerable: false, writable: true, value: cloneNode },
+};
+const adoptedChildAliases: PropertyDescriptorMap = {
+  childNodes: { configurable: true, enumerable: false, get(this: View) { return this.children; }, set(this: View, value) { this.children = value; } },
+  firstChild: { configurable: true, enumerable: false, get(this: View) { return this.children[0] ?? null; } },
+  lastChild: { configurable: true, enumerable: false, get(this: View) { return this.children[this.children.length - 1] ?? null; } },
+};
+const adoptedElementAliases: PropertyDescriptorMap = {
+  tagName: { configurable: true, enumerable: false, get(this: View) { return this.name; }, set(this: View, value) { this.name = value; } },
+  attributes: { configurable: true, enumerable: false, get(this: View) { const attributes = this.attribs; const record = viewRecord(this); return Object.keys(attributes).map((name) => ({ name, value: attributes[name], namespace: record.attribsNamespace?.[name], prefix: record.attribsPrefix?.[name] })); } },
+};
+const adoptedDataAliases: PropertyDescriptorMap = {
+  nodeValue: { configurable: true, enumerable: false, get(this: View) { return this.data; }, set(this: View, value) { this.data = value; } },
+};
+const adoptedFields = new Map<string, PropertyDescriptorMap>();
+const optionalAdoptedKeys = ['name', 'data', 'namespace', 'prefix', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode', 'x-attribsNamespace', 'x-attribsPrefix'];
+const optionalAdoptedFields = new Set(optionalAdoptedKeys);
+const adoptedShapes = new Map<string, PropertyDescriptorMap>();
+
+/**
+ * Binds an object created outside the arena (a DOM constructor or a parser
+ * hook's node) to its native node, keeping the caller's object identity.
+ */
+function adoptObject(state: DocumentState, local: number, original: any): AnyNode {
+  const record = recordAt(state, local);
+  if (!record) return undefined as unknown as AnyNode;
+  const view = original as View;
+  const attributesPrototype = original.attribs && typeof original.attribs === 'object' ? Object.getPrototypeOf(original.attribs) : undefined;
+  view[VIEW_STATE] = state;
+  view[VIEW_LOCAL] = local;
+  view[VIEW_SELF] = view;
+  view[VIEW_ATTRIBUTES] = undefined;
+  view[VIEW_CHILDREN] = undefined;
+  view[VIEW_CHILD_TARGET] = undefined;
+  let fields = adoptedFields.get(record.type);
+  if (!fields) {
+    fields = {};
+    for (const [key, accessor] of Object.entries({ ...accessorsFor(record.type), sourceCodeLocation: locationAccessor })) fields[key] = { ...accessor, configurable: true, enumerable: true };
+    adoptedFields.set(record.type, fields);
   }
-  for (const field of ['parent', 'prev', 'next']) define(field, () => { const value = read()[field]; return value === null || value === undefined ? null : getNode(document, value); }, (value) => setField(document, id, field, value == null ? null : importNodes(document, [value])[0]));
-  for (const [alias, field] of [['parentNode', 'parent'], ['previousSibling', 'prev'], ['nextSibling', 'next']]) define(alias, () => node[field], (value) => { node[field] = value; }, false);
-  if ('children' in record && ['root', 'tag', 'script', 'style', 'cdata'].includes(record.type)) {
-    const list = children(document, id);
-    define('children', () => list, (value) => setField(document, id, 'children', importNodes(document, value)));
-    define('childNodes', () => list, (value) => { node.children = value; }, false);
-    define('firstChild', () => list[0] ?? null, undefined, false);
-    define('lastChild', () => list[list.length - 1] ?? null, undefined, false);
+  // Which optional fields a node has varies; each combination's full descriptor map is built once.
+  let shape = record.type;
+  for (const key of optionalAdoptedKeys) {
+    if (!(key in fields)) continue;
+    const field = key === 'x-attribsNamespace' ? 'attribsNamespace' : key === 'x-attribsPrefix' ? 'attribsPrefix' : key;
+    shape += (record as any)[field] !== undefined || Object.hasOwn(original, key) ? '1' : '0';
   }
-  if (['tag', 'script', 'style'].includes(record.type)) {
-    const attrs = attributes(document, id, 'attribs', Object.getPrototypeOf(original.attribs ?? {}));
-    define('attribs', () => attrs, (value) => setField(document, id, 'attribs', value));
-    define('tagName', () => node.name, (value) => { node.name = value; }, false);
-    for (const field of ['x-attribsNamespace', 'x-attribsPrefix']) {
-      if (!((field === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix') in record) && !Object.hasOwn(original, field)) continue;
-      const values = attributes(document, id, field === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix');
-      define(field, () => values, (value) => setField(document, id, field, value));
+  let descriptors = adoptedShapes.get(shape);
+  if (!descriptors) {
+    const present: PropertyDescriptorMap = {};
+    for (const key in fields) {
+      const field = key === 'x-attribsNamespace' ? 'attribsNamespace' : key === 'x-attribsPrefix' ? 'attribsPrefix' : key;
+      if (optionalAdoptedFields.has(key) && (record as any)[field] === undefined && !Object.hasOwn(original, key)) continue;
+      present[key] = fields[key];
     }
-    define('attributes', () => Object.keys(attrs).map((name) => ({ name, value: attrs[name], namespace: read().attribsNamespace?.[name], prefix: read().attribsPrefix?.[name] })), undefined, false);
+    const isParent = 'children' in present;
+    const isData = record.type === 'text' || record.type === 'comment' || record.type === 'directive';
+    descriptors = { ...present, ...adoptedAliases, ...(isParent ? adoptedChildAliases : {}), ...(isElementType(record.type) ? adoptedElementAliases : {}), ...(isData ? adoptedDataAliases : {}) };
+    adoptedShapes.set(shape, descriptors);
+  }
+  const isElement = isElementType(record.type);
+  try {
+    Object.defineProperties(view, descriptors);
+  } catch {
+    // Foreign user properties may be non-configurable; those keep their values.
+  }
+  if (isElement && attributesPrototype !== undefined) view[VIEW_ATTRIBUTES] = createAttributes(view, attributesPrototype);
+  cacheView(state, local, view);
+  return view as unknown as AnyNode;
+}
+
+/**
+ * Registers a tree adapter's nodes for the document's slots. Each node can be
+ * passed back to the API at once; its fields become live when first returned.
+ */
+export function attachParsedNodes(state: DocumentState, nodes: (object | undefined)[]): void {
+  state.adapterNodes = nodes;
+  for (let local = 0; local < nodes.length; local++) {
+    const node = nodes[local] as View | undefined;
+    if (!node) continue;
+    node[VIEW_STATE] = state;
+    node[VIEW_LOCAL] = local;
+    node[VIEW_SELF] = node;
   }
-  if (['text', 'comment', 'directive'].includes(record.type)) define('nodeValue', () => node.data, (value) => { node.data = value; }, false);
-  define('nodeType', () => ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[read().type] ?? 1, undefined, false);
-  Object.defineProperty(node, 'cloneNode', { configurable: true, enumerable: false, writable: true, value: cloneNode });
-  return node;
 }
 
 /** Clone through the receiver's current native owner, including borrowed calls. */
@@ -244,6 +587,11 @@ export function cloneNode<T extends AnyNode>(this: T, recursive = false): T {
   return getNode(binding.document, operation<number[]>(binding.document, 'clone', { ids: [binding.id], deep: recursive })[0]) as T;
 }
 
+function childIds(document: NativeDocument, id: number): number[] {
+  const state = stateIn(document, id);
+  return (recordAt(state, id - state.base)?.children ?? []).map((child) => state.base + child);
+}
+
 /** Import external DOM nodes once and keep their object identities as handles. */
 export function importNodes(document: NativeDocument, input: unknown): number[] {
   if (input == null || input === false) return [];
@@ -251,8 +599,8 @@ export function importNodes(document: NativeDocument, input: unknown): number[]
   const result: number[] = [];
   for (const node of values) {
     if (node == null) continue;
-    const existing = nodeId(node, document);
-    if (existing !== undefined) { document.retainNode?.(existing); result.push(existing); continue; }
+    const existing = node && typeof node === 'object' ? viewIdIn(document, node) : undefined;
+    if (existing !== undefined) { result.push(existing); continue; }
     if (typeof node !== 'object' || typeof node.type !== 'string') continue;
     const records: any[] = [];
     const originals = new Map<number, any>();
@@ -273,10 +621,10 @@ export function importNodes(document: NativeDocument, input: unknown): number[]
     const adopt = (oldId: number, newId: number): void => {
       const source = originals.get(oldId);
       const oldChildren = records[oldId].children;
-      const newChildren = nodeRecord(document, newId).children ?? [];
+      const newChildren = childIds(document, newId);
       // A node already belonging to another Rust document must retain its
       // original document handle. Imported clones receive their own handles.
-      getNode(document, newId, nodeBinding(source) ? undefined : source);
+      getNode(document, newId, isNativeNode(source) ? undefined : source);
       for (let i = 0; i < oldChildren.length; i++) if (newChildren[i] !== undefined) adopt(oldChildren[i], newChildren[i]);
     };
     adopt(root, imported[0]);
@@ -285,6 +633,6 @@ export function importNodes(document: NativeDocument, input: unknown): number[]
   return result;
 }
 
-export const isTag = (node: any): boolean => !!node && ['tag', 'script', 'style'].includes(node.type);
+export const isTag = (node: any): boolean => !!node && isElementType(node.type);
 export const isDocument = (node: any): boolean => node?.type === 'root';
 export const hasChildren = (node: any): boolean => !!node && 'children' in node;