@lifeart/async-dom 2.0.0-alpha.3

package/dist/index3.d.cts

@@ -0,0 +1,882 @@
+import { c as DomMutation, f as InsertPosition, g as NodeId, i as AppId, t as Transport } from "./base.cjs";
+import { n as DebugOptions } from "./debug.cjs";
+
+//#region src/platform.d.ts
+
+/**
+ * PlatformHost abstraction for running async-dom in different environments
+ * (Web Worker, Node.js, etc.).
+ *
+ * Only three things need platform abstraction:
+ * 1. navigator (userAgent, language, etc.)
+ * 2. Error handlers (onerror, onunhandledrejection)
+ * 3. beforeunload / shutdown hook
+ */
+interface PlatformHost {
+  navigator: {
+    userAgent: string;
+    language: string;
+    languages: readonly string[];
+    hardwareConcurrency: number;
+  };
+  /**
+   * Install global error and unhandled rejection handlers.
+   * Returns a cleanup function that removes the handlers.
+   */
+  installErrorHandlers(onError: (message: string, error?: Error, filename?: string, lineno?: number, colno?: number) => void, onUnhandledRejection: (reason: unknown) => void): () => void;
+  /**
+   * Register a callback to run before the environment shuts down.
+   * Returns a cleanup function that removes the hook.
+   */
+  onBeforeUnload(callback: () => void): () => void;
+}
+/**
+ * Create a PlatformHost for Web Worker environments (uses `self`).
+ */
+declare function createWorkerPlatform(): PlatformHost;
+/**
+ * Create a PlatformHost for Node.js environments (uses `process`).
+ */
+declare function createNodePlatform(): PlatformHost;
+/**
+ * Auto-detect the current platform and create the appropriate PlatformHost.
+ */
+declare function detectPlatform(): PlatformHost;
+//# sourceMappingURL=platform.d.ts.map
+//#endregion
+//#region src/core/sync-channel.d.ts
+/**
+ * SharedArrayBuffer-based synchronous communication channel.
+ *
+ * Allows a worker thread to make blocking reads from the main thread
+ * using Atomics.wait/notify. Inspired by Partytown's approach.
+ *
+ * Buffer layout (SharedArrayBuffer):
+ *   Int32Array view:
+ *     [0] — signal: 0=idle, 1=request-pending, 2=response-ready
+ *     [1] — query type enum
+ *     [2] — request data length (bytes)
+ *     [3] — response data length (bytes)
+ *   Uint8Array view at offset 16: request data (JSON-encoded)
+ *   Uint8Array view at offset 16+REQUEST_REGION_SIZE: response data (JSON-encoded)
+ */
+/** Type of synchronous query that a worker can make to the main thread. */
+declare enum QueryType {
+  /** Request element.getBoundingClientRect() result. */
+  BoundingRect = 0,
+  /** Request window.getComputedStyle() result for a property. */
+  ComputedStyle = 1,
+  /** Request a DOM node property (e.g., clientWidth, scrollTop). */
+  NodeProperty = 2,
+  /** Request a window property (e.g., innerWidth). */
+  WindowProperty = 3,
+}
+/** A pending query read from the shared buffer by the main-thread host. */
+
+/**
+ * Worker-side synchronous channel.
+ * Uses Atomics.wait to block until the main thread responds.
+ */
+declare class SyncChannel {
+  private signal;
+  private meta;
+  private requestRegion;
+  private responseRegion;
+  private encoder;
+  private decoder;
+  private constructor();
+  /**
+   * Create a new SyncChannel with a fresh SharedArrayBuffer.
+   * The returned buffer must be transferred to the worker via postMessage.
+   * @param size - Total buffer size in bytes (default: 64KB)
+   */
+  static create(size?: number): {
+    channel: SyncChannel;
+    buffer: SharedArrayBuffer;
+  };
+  /** Attach to an existing SharedArrayBuffer received from the main thread. */
+  static fromBuffer(sab: SharedArrayBuffer): SyncChannel;
+  /**
+   * Send a synchronous request to the main thread and block until response.
+   *
+   * Protocol:
+   * 1. Write JSON-encoded request data to the request region
+   * 2. Set query type and data length in the header via Atomics.store (memory fence)
+   * 3. Set signal to SIGNAL_REQUEST and notify the main thread
+   * 4. Block with Atomics.wait until signal changes or timeout (100ms per retry, 5 retries max)
+   * 5. Read JSON-encoded response from the response region
+   *
+   * @param queryType - The type of DOM query to execute
+   * @param data - JSON-encoded request payload
+   * @returns Parsed response object, or null on timeout or parse failure
+   */
+  request(queryType: QueryType, data: string): unknown;
+}
+/**
+ * Main-thread host for the sync channel.
+ * Polls for pending requests and writes responses.
+ */
+//#endregion
+//#region src/worker-thread/mutation-collector.d.ts
+/** Entry recording a coalesced (eliminated) mutation. */
+interface CoalescedLogEntry {
+  action: string;
+  key: string;
+  timestamp: number;
+}
+/**
+ * Collects DOM mutations during synchronous execution and flushes them
+ * as a batched message at the end of the current microtask.
+ */
+declare class MutationCollector {
+  private appId;
+  private queue;
+  private scheduled;
+  private uidCounter;
+  private transport;
+  private _coalesceEnabled;
+  private _stats;
+  private _coalescedLog;
+  private _perTypeCoalesced;
+  /** Total mutations added (monotonically increasing counter for diff-based tracking). */
+  get totalAdded(): number;
+  /** Feature 15: Current causal event tag for this flush cycle */
+  private _causalEvent;
+  getStats(): {
+    added: number;
+    coalesced: number;
+    flushed: number;
+  };
+  getCoalescedLog(): CoalescedLogEntry[];
+  getPerTypeCoalesced(): Record<string, {
+    added: number;
+    coalesced: number;
+  }>;
+  constructor(appId: AppId);
+  /** Feature 15: Set the causal event for the current mutation cycle. */
+  setCausalEvent(event: {
+    eventType: string;
+    listenerId: string;
+    timestamp: number;
+  } | null): void;
+  /** Feature 15: Get current causal event. */
+  getCausalEvent(): {
+    eventType: string;
+    listenerId: string;
+    timestamp: number;
+  } | null;
+  enableCoalescing(enabled: boolean): void;
+  setTransport(transport: Transport): void;
+  add(mutation: DomMutation): void;
+  private coalesce;
+  private _buildKey;
+  flush(): void;
+  /** Force-flush all pending mutations immediately */
+  flushSync(): void;
+  /** Get number of pending mutations (useful for testing) */
+  get pendingCount(): number;
+}
+//# sourceMappingURL=mutation-collector.d.ts.map
+//#endregion
+//#region src/worker-thread/element.d.ts
+/** Union of all virtual node types that can appear in the worker-side DOM tree. */
+type VirtualNode = VirtualElement | VirtualTextNode | VirtualCommentNode;
+/**
+ * Virtual DOM element that records mutations via the MutationCollector
+ * instead of touching real DOM.
+ *
+ * Implements a broad subset of the HTMLElement API:
+ * - Attributes: setAttribute, getAttribute, removeAttribute, dataset
+ * - Children: appendChild, removeChild, insertBefore, replaceChild, etc.
+ * - Text/HTML: textContent, innerHTML, outerHTML, insertAdjacentHTML
+ * - Input state: value, checked, disabled, selectedIndex (with main-thread sync)
+ * - Media state: currentTime, duration, paused, ended, readyState
+ * - Events: addEventListener, removeEventListener, on* handlers, dispatchEvent
+ * - Layout queries: getBoundingClientRect, clientWidth/Height, etc. (via SyncChannel)
+ * - CSS: style proxy, classList, className
+ * - Traversal: querySelector, closest, contains, parentNode, children, etc.
+ *
+ * Every mutating operation emits a DomMutation to the collector. Layout queries
+ * use the SyncChannel to synchronously read values from the main thread's DOM.
+ */
+declare class VirtualElement {
+  private collector;
+  static readonly ELEMENT_NODE = 1;
+  static readonly TEXT_NODE = 3;
+  static readonly COMMENT_NODE = 8;
+  static readonly DOCUMENT_NODE = 9;
+  static readonly DOCUMENT_FRAGMENT_NODE = 11;
+  readonly _nodeId: NodeId;
+  readonly nodeName: string;
+  readonly tagName: string;
+  readonly nodeType = 1;
+  readonly namespaceURI: string;
+  parentNode: VirtualElement | null;
+  _ownerDocument: VirtualDocument | null;
+  childNodes: VirtualNode[];
+  private _attributes;
+  private _classes;
+  private _textContent;
+  private _value;
+  private _checked;
+  private _disabled;
+  private _selectedIndex;
+  private _datasetProxy;
+  style: Record<string, string>;
+  classList: VirtualClassList;
+  get id(): string;
+  set id(value: string);
+  get children(): VirtualElement[];
+  get childElementCount(): number;
+  get firstElementChild(): VirtualElement | null;
+  get lastElementChild(): VirtualElement | null;
+  get clientWidth(): number;
+  get clientHeight(): number;
+  get scrollWidth(): number;
+  get scrollHeight(): number;
+  get offsetWidth(): number;
+  get offsetHeight(): number;
+  get offsetTop(): number;
+  get offsetLeft(): number;
+  get scrollTop(): number;
+  set scrollTop(v: number);
+  get scrollLeft(): number;
+  set scrollLeft(v: number);
+  /**
+   * Synchronously read a numeric DOM property from the main thread via SyncChannel.
+   * Returns null if no sync channel is available (e.g., no SharedArrayBuffer support).
+   */
+  private _readNodeProperty;
+  constructor(tag: string, collector: MutationCollector, id?: NodeId);
+  _setNamespaceURI(ns: string): void;
+  setAttribute(name: string, value: string): void;
+  getAttribute(name: string): string | null;
+  hasAttribute(name: string): boolean;
+  removeAttribute(name: string): void;
+  getAttributeNS(_ns: string | null, name: string): string | null;
+  setAttributeNS(_ns: string | null, name: string, value: string): void;
+  removeAttributeNS(_ns: string | null, name: string): void;
+  get attributes(): {
+    length: number;
+    item(index: number): {
+      name: string;
+      value: string;
+    } | null;
+  };
+  appendChild(child: VirtualNode): VirtualNode;
+  private _appendSingleChild;
+  removeChild(child: VirtualNode): VirtualNode;
+  insertBefore(newChild: VirtualNode, refChild: VirtualNode | null): VirtualNode;
+  remove(): void;
+  append(...nodes: VirtualNode[]): void;
+  prepend(...nodes: VirtualNode[]): void;
+  replaceWith(...nodes: VirtualNode[]): void;
+  before(...nodes: VirtualNode[]): void;
+  after(...nodes: VirtualNode[]): void;
+  replaceChildren(...nodes: VirtualNode[]): void;
+  get textContent(): string;
+  set textContent(value: string);
+  get innerHTML(): string;
+  set innerHTML(value: string);
+  get outerHTML(): string;
+  get value(): string;
+  set value(v: string);
+  get checked(): boolean;
+  set checked(v: boolean);
+  get disabled(): boolean;
+  set disabled(v: boolean);
+  get selectedIndex(): number;
+  set selectedIndex(v: number);
+  /**
+   * Sync input state from a main-thread event without emitting mutations.
+   * Called by VirtualDocument.dispatchEvent to keep the worker's model in sync
+   * with real DOM input values after user interaction.
+   */
+  _updateInputState(state: {
+    value?: string;
+    checked?: boolean;
+    selectedIndex?: number;
+  }): void;
+  private _currentTime;
+  private _duration;
+  private _paused;
+  private _ended;
+  private _readyState;
+  get currentTime(): number;
+  set currentTime(v: number);
+  get duration(): number;
+  get paused(): boolean;
+  get ended(): boolean;
+  get readyState(): number;
+  /** Sync media element state from a main-thread event without emitting mutations. */
+  _updateMediaState(state: Record<string, unknown>): void;
+  get className(): string;
+  set className(value: string);
+  /** Map of listenerId -> callback for event dispatch. */
+  private _eventListeners;
+  /** Map of listenerId -> event name, used to match removeEventListener by name+callback. */
+  private _listenerEventNames;
+  /** Map of event name -> callback for on* property handlers (e.g., onclick). */
+  private _onHandlers;
+  /**
+   * Register an event listener. Emits an addEventListener mutation so the main thread
+   * attaches a real DOM listener that will serialize and forward events back.
+   * Supports the `once` option by wrapping the callback with auto-removal.
+   */
+  addEventListener(name: string, callback: (e: unknown) => void, options?: AddEventListenerOptions | boolean): void;
+  getEventListener(listenerId: string): ((e: unknown) => void) | undefined;
+  /** Remove a listener by event name and callback reference. Emits a removeEventListener mutation. */
+  removeEventListener(_name: string, callback: (e: unknown) => void): void;
+  /** Invoke all listeners matching the event type. Called during bubbling by VirtualDocument.dispatchEvent. */
+  _dispatchBubbledEvent(event: {
+    type: string;
+    immediatePropagationStopped?: boolean;
+  }): void;
+  /**
+   * Recursively clean up this element and all children from the document's registries.
+   * Called before emitting removal mutations to prevent memory leaks.
+   */
+  _cleanupFromDocument(): void;
+  /** Emit a configureEvent mutation to tell the main thread to call preventDefault for this event. */
+  preventDefaultFor(eventName: string): void;
+  /** Implement on* handler properties (onclick, etc.) by managing a single listener per event name. */
+  private _setOnHandler;
+  set onclick(cb: ((e: unknown) => void) | null);
+  set ondblclick(cb: ((e: unknown) => void) | null);
+  set onmouseenter(cb: ((e: unknown) => void) | null);
+  set onmouseleave(cb: ((e: unknown) => void) | null);
+  set onmousedown(cb: ((e: unknown) => void) | null);
+  set onmouseup(cb: ((e: unknown) => void) | null);
+  set onmouseover(cb: ((e: unknown) => void) | null);
+  set onmousemove(cb: ((e: unknown) => void) | null);
+  set onkeydown(cb: ((e: unknown) => void) | null);
+  set onkeyup(cb: ((e: unknown) => void) | null);
+  set onkeypress(cb: ((e: unknown) => void) | null);
+  set onchange(cb: ((e: unknown) => void) | null);
+  set oncontextmenu(cb: ((e: unknown) => void) | null);
+  set oninput(cb: ((e: unknown) => void) | null);
+  set onfocus(cb: ((e: unknown) => void) | null);
+  set onblur(cb: ((e: unknown) => void) | null);
+  set onsubmit(cb: ((e: unknown) => void) | null);
+  get firstChild(): VirtualNode | null;
+  get lastChild(): VirtualNode | null;
+  get nextSibling(): VirtualNode | null;
+  get previousSibling(): VirtualNode | null;
+  get parentElement(): VirtualElement | null;
+  get ownerDocument(): VirtualDocument | null;
+  get isConnected(): boolean;
+  getRootNode(): VirtualNode;
+  get nextElementSibling(): VirtualElement | null;
+  get previousElementSibling(): VirtualElement | null;
+  hasChildNodes(): boolean;
+  replaceChild(newChild: VirtualNode, oldChild: VirtualNode): VirtualNode;
+  normalize(): void;
+  dispatchEvent(event: unknown): boolean;
+  cloneNode(deep?: boolean): VirtualElement;
+  get dataset(): Record<string, string | undefined>;
+  insertAdjacentHTML(position: InsertPosition, html: string): void;
+  contains(other: VirtualNode | null): boolean;
+  querySelector(selector: string): VirtualElement | null;
+  querySelectorAll(selector: string): VirtualElement[];
+  matches(selector: string): boolean;
+  getElementsByTagName(tagName: string): VirtualElement[];
+  getElementsByClassName(className: string): VirtualElement[];
+  closest(selector: string): VirtualElement | null;
+  focus(): void;
+  blur(): void;
+  play(): void;
+  pause(): void;
+  load(): void;
+  click(): void;
+  scrollIntoView(options?: unknown): void;
+  select(): void;
+  showModal(): void;
+  close(): void;
+  /**
+   * Synchronously query the main thread for this element's bounding rect via SyncChannel.
+   * Returns a zero rect if no sync channel is available.
+   */
+  getBoundingClientRect(): {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+  };
+  /** Parse a CSS style string (e.g., "color: red; font-size: 14px") and set each property individually. */
+  private _parseAndSetStyles;
+}
+/**
+ * Virtual text node (nodeType 3). Setting nodeValue emits a setProperty mutation
+ * so the main thread updates the real text node.
+ */
+declare class VirtualTextNode {
+  readonly _nodeId: NodeId;
+  private collector;
+  static readonly ELEMENT_NODE = 1;
+  static readonly TEXT_NODE = 3;
+  static readonly COMMENT_NODE = 8;
+  static readonly DOCUMENT_NODE = 9;
+  static readonly DOCUMENT_FRAGMENT_NODE = 11;
+  readonly nodeType = 3;
+  readonly nodeName = "#text";
+  parentNode: VirtualElement | null;
+  _ownerDocument: VirtualDocument | null;
+  private _nodeValue;
+  constructor(text: string, _nodeId: NodeId, collector: MutationCollector);
+  get parentElement(): VirtualElement | null;
+  get nodeValue(): string;
+  set nodeValue(value: string);
+  get textContent(): string;
+  set textContent(value: string);
+  get nextSibling(): VirtualNode | null;
+  get previousSibling(): VirtualNode | null;
+  get childNodes(): VirtualNode[];
+  remove(): void;
+  cloneNode(_deep?: boolean): VirtualTextNode;
+}
+/**
+ * Virtual comment node (nodeType 8). Used primarily as DOM markers by frameworks.
+ * Comment nodes do not emit mutations on value changes.
+ */
+declare class VirtualCommentNode {
+  readonly _nodeId: NodeId;
+  private collector;
+  static readonly ELEMENT_NODE = 1;
+  static readonly TEXT_NODE = 3;
+  static readonly COMMENT_NODE = 8;
+  static readonly DOCUMENT_NODE = 9;
+  static readonly DOCUMENT_FRAGMENT_NODE = 11;
+  readonly nodeType = 8;
+  readonly nodeName = "#comment";
+  parentNode: VirtualElement | null;
+  _ownerDocument: VirtualDocument | null;
+  private _nodeValue;
+  constructor(text: string, _nodeId: NodeId, collector: MutationCollector);
+  get parentElement(): VirtualElement | null;
+  get nodeValue(): string;
+  set nodeValue(value: string);
+  get textContent(): string;
+  get nextSibling(): VirtualNode | null;
+  get previousSibling(): VirtualNode | null;
+  get childNodes(): VirtualNode[];
+  remove(): void;
+  cloneNode(_deep?: boolean): VirtualCommentNode;
+}
+/** DOMTokenList-compatible classList implementation that delegates to VirtualElement.className. */
+declare class VirtualClassList {
+  private element;
+  constructor(element: VirtualElement);
+  add(...names: string[]): void;
+  remove(...names: string[]): void;
+  contains(name: string): boolean;
+  toggle(name: string, force?: boolean): boolean;
+  get length(): number;
+}
+//#endregion
+//#region src/worker-thread/document.d.ts
+/**
+ * Virtual Document that exists in a worker thread.
+ *
+ * Mirrors a subset of the browser's Document API, allowing framework code
+ * to call createElement, querySelector, addEventListener, etc. without
+ * touching the real DOM. Every mutating operation records a DomMutation via
+ * the MutationCollector, which batches and sends them to the main thread.
+ *
+ * Key subsystems:
+ * - Element creation: createElement, createTextNode, createComment
+ * - Event dispatch: routes serialized events from the main thread to the
+ *   correct VirtualElement listener using O(1) listenerId lookup
+ * - ID registries: maintains both user-visible id attributes (_ids) and
+ *   internal NodeId -> VirtualElement mappings (_nodeIdToElement)
+ * - Sync channel: optional SharedArrayBuffer channel for blocking DOM queries
+ */
+declare class VirtualDocument {
+  readonly body: VirtualElement;
+  readonly head: VirtualElement;
+  readonly documentElement: VirtualElement;
+  readonly nodeType = 9;
+  readonly nodeName = "#document";
+  /** Collects mutations and batches them for transport to the main thread. */
+  readonly collector: MutationCollector;
+  /** Reference to the VirtualWindow, providing location/navigator access. */
+  _defaultView: unknown;
+  /** Optional sync channel for blocking DOM queries (e.g., getBoundingClientRect). */
+  _syncChannel: SyncChannel | null;
+  private _title;
+  private _cookie;
+  /** Map of user-visible id attribute -> VirtualElement for getElementById. */
+  private _ids;
+  /** Map of internal NodeId -> VirtualElement for event target resolution. */
+  private _nodeIdToElement;
+  /** Document-level event listeners keyed by listenerId. */
+  private _listenerMap;
+  /** Map of listenerId -> owning VirtualElement for O(1) event dispatch routing. */
+  private _listenerToElement;
+  private _listenerCounter;
+  constructor(appId: AppId);
+  /**
+   * Create a new virtual element and emit a createNode mutation.
+   * The element is registered by NodeId for event target resolution.
+   */
+  createElement(tag: string): VirtualElement;
+  /** Create a namespaced element (e.g., SVG). Delegates to createElement then sets the namespace. */
+  createElementNS(ns: string, tag: string): VirtualElement;
+  /** Create a virtual text node and emit a createNode mutation with tag "#text". */
+  createTextNode(text: string): VirtualTextNode;
+  /** Create a virtual comment node and emit a createComment mutation. */
+  createComment(text: string): VirtualCommentNode;
+  createDocumentFragment(): VirtualElement;
+  getElementById(id: string): VirtualElement | null;
+  /**
+   * Add a document-level event listener. The listener is stored locally and
+   * a mutation is emitted to tell the main thread to attach a real listener.
+   */
+  addEventListener(name: string, callback: (e: unknown) => void): void;
+  /** Remove a document-level listener by callback reference. Emits a removeEventListener mutation. */
+  removeEventListener(_name: string, callback: (e: unknown) => void): void;
+  /**
+   * Route an event from the main thread to the appropriate listener.
+   * Resolves serialized target IDs to actual VirtualElement references.
+   */
+  private _resolveTarget;
+  /**
+   * Route a serialized event from the main thread to the appropriate listener.
+   *
+   * Flow:
+   * 1. Resolve serialized target/currentTarget/relatedTarget IDs to VirtualElement refs
+   * 2. Wrap the event data in a VirtualEvent for bubbling support
+   * 3. Tag the MutationCollector with causal event info for causality tracking
+   * 4. Sync input/media state from the event to the target element
+   * 5. Dispatch to document-level listeners, or bubble through the element tree
+   */
+  dispatchEvent(listenerId: string, event: unknown): void;
+  /** Feature 16: finish performance measurement for an event dispatch */
+  private _finishEventPerf;
+  /**
+   * Register an element by its internal NodeId.
+   */
+  registerElement(id: NodeId, element: VirtualElement): void;
+  /**
+   * Unregister an element by its internal NodeId (called during cleanup on removal).
+   */
+  unregisterElement(id: NodeId): void;
+  /**
+   * Register an element by its user-visible id attribute (distinct from internal NodeId).
+   */
+  registerElementById(id: string, element: VirtualElement): void;
+  /**
+   * Unregister an element by its user-visible id attribute.
+   */
+  unregisterElementById(id: string): void;
+  /**
+   * Register a listener ID to its owning element for O(1) event dispatch.
+   */
+  registerListener(listenerId: string, element: VirtualElement): void;
+  /**
+   * Unregister a listener ID (called on removeEventListener or element cleanup).
+   */
+  unregisterListener(listenerId: string): void;
+  /** Stub implementation of document.createEvent for legacy API compatibility. */
+  createEvent(_type: string): Record<string, unknown>;
+  get activeElement(): VirtualElement;
+  /** Stub implementation of document.createRange for framework compatibility. */
+  createRange(): unknown;
+  /** Simplified TreeWalker that pre-collects all descendant nodes for sequential traversal. */
+  createTreeWalker(root: VirtualElement, _whatToShow?: number): {
+    currentNode: VirtualNode;
+    nextNode(): VirtualNode | null;
+  };
+  querySelector(selector: string): VirtualElement | null;
+  querySelectorAll(selector: string): VirtualElement[];
+  getElementsByTagName(tagName: string): VirtualElement[];
+  getElementsByClassName(className: string): VirtualElement[];
+  get title(): string;
+  set title(value: string);
+  get URL(): string;
+  get location(): unknown;
+  get cookie(): string;
+  set cookie(value: string);
+  get readyState(): string;
+  get compatMode(): string;
+  get characterSet(): string;
+  get contentType(): string;
+  get visibilityState(): string;
+  get hidden(): boolean;
+  get childNodes(): VirtualNode[];
+  get children(): VirtualElement[];
+  get firstChild(): VirtualElement;
+  contains(node: unknown): boolean;
+  get implementation(): {
+    hasFeature(): boolean;
+  };
+  get defaultView(): unknown;
+  get ownerDocument(): VirtualDocument;
+  /**
+   * Clean up all internal state. Called when the worker DOM instance is being destroyed.
+   * Clears element registries, listener maps, and resets counters.
+   */
+  destroy(): void;
+  /** Serialize the entire virtual DOM tree to a JSON-compatible structure for debugging. */
+  toJSON(): unknown;
+  private _serializeNode;
+}
+//# sourceMappingURL=document.d.ts.map
+//#endregion
+//#region src/worker-thread/events.d.ts
+/**
+ * Virtual event classes that simulate DOM event behavior
+ * including bubbling, propagation control, and default prevention.
+ */
+declare class VirtualEvent {
+  readonly type: string;
+  target: unknown;
+  currentTarget: unknown;
+  readonly bubbles: boolean;
+  readonly cancelable: boolean;
+  defaultPrevented: boolean;
+  readonly timeStamp: number;
+  readonly isTrusted: boolean;
+  eventPhase: number;
+  private _stopPropagation;
+  private _stopImmediatePropagation;
+  constructor(type: string, init?: Record<string, unknown>);
+  preventDefault(): void;
+  stopPropagation(): void;
+  stopImmediatePropagation(): void;
+  get propagationStopped(): boolean;
+  get immediatePropagationStopped(): boolean;
+}
+declare class VirtualCustomEvent extends VirtualEvent {
+  readonly detail: unknown;
+  constructor(type: string, init?: Record<string, unknown>);
+}
+//# sourceMappingURL=events.d.ts.map
+//#endregion
+//#region src/worker-thread/observers.d.ts
+/**
+ * Stub observer classes that prevent crashes when frameworks
+ * attempt to use browser observers in a worker context.
+ */
+declare class VirtualMutationObserver {
+  constructor(_callback: (mutations: unknown[], observer: unknown) => void);
+  observe(_target: unknown, _options?: unknown): void;
+  disconnect(): void;
+  takeRecords(): unknown[];
+}
+declare class VirtualResizeObserver {
+  constructor(_callback: (entries: unknown[], observer: unknown) => void);
+  observe(_target: unknown, _options?: unknown): void;
+  unobserve(_target: unknown): void;
+  disconnect(): void;
+}
+declare class VirtualIntersectionObserver {
+  readonly root: null;
+  readonly rootMargin = "0px";
+  readonly thresholds: readonly number[];
+  constructor(_callback: (entries: unknown[], observer: unknown) => void, _options?: unknown);
+  observe(_target: unknown): void;
+  unobserve(_target: unknown): void;
+  disconnect(): void;
+  takeRecords(): unknown[];
+}
+//# sourceMappingURL=observers.d.ts.map
+//#endregion
+//#region src/worker-thread/storage.d.ts
+/**
+ * Scoped Storage implementation that can optionally sync with
+ * the main thread's real localStorage/sessionStorage via the sync channel.
+ *
+ * Each worker app gets its own isolated storage with a unique prefix.
+ * When a sync channel is available, reads/writes are persisted to the
+ * real browser storage on the main thread.
+ */
+declare class ScopedStorage {
+  private cache;
+  private prefix;
+  private storageType;
+  private getSyncChannel;
+  private queryType;
+  constructor(prefix: string, storageType: "localStorage" | "sessionStorage", getSyncChannel: () => SyncChannel | null, queryType: QueryType);
+  private syncCall;
+  get length(): number;
+  key(index: number): string | null;
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  clear(): void;
+}
+//# sourceMappingURL=storage.d.ts.map
+//#endregion
+//#region src/worker-thread/index.d.ts
+/**
+ * Configuration for {@link createWorkerDom}.
+ *
+ * All fields are optional — sensible defaults are chosen for standard
+ * Web Worker usage.
+ */
+interface WorkerDomConfig {
+  /** Explicit app ID. If omitted, a unique ID is generated automatically. */
+  appId?: AppId;
+  /** Custom transport to use instead of the default `WorkerSelfTransport`. */
+  transport?: Transport;
+  /** Debug logging options (same as the main-thread `DebugOptions`). */
+  debug?: DebugOptions;
+  /**
+   * Sandbox mode for the worker environment.
+   *
+   * - `"global"` — Patches `globalThis` so bare references to `document`, `window`, etc.
+   *   resolve to the virtual DOM objects.
+   * - `"eval"` — Enables `window.eval()` with a sandboxed scope that uses the virtual DOM.
+   * - `true` — Enables both `"global"` and `"eval"` modes.
+   * - `false` (default) — No patching; access virtual DOM explicitly via the returned objects.
+   */
+  sandbox?: boolean | "global" | "eval";
+  /** Custom platform host for non-browser environments (e.g. Node.js). Auto-detected if omitted. */
+  platform?: PlatformHost;
+}
+/**
+ * The result of calling {@link createWorkerDom}.
+ *
+ * Provides a virtual `document` and `window` that mirror the real DOM API.
+ * All mutations are automatically serialized and sent to the main thread.
+ */
+interface WorkerDomResult {
+  /** Virtual document implementing a subset of the DOM `Document` API. */
+  document: VirtualDocument;
+  /** Virtual window providing `location`, `history`, `screen`, timers, observers, and more. */
+  window: WorkerWindow;
+  /** Tear down the virtual DOM, cancel timers, and close the transport. */
+  destroy: () => void;
+}
+/**
+ * Virtual `window` object available inside a worker.
+ *
+ * Provides browser-like globals (`document`, `location`, `history`, `localStorage`,
+ * observers, timers, etc.) backed by the virtual DOM and sync-channel reads.
+ */
+interface WorkerWindow {
+  /** The virtual document for this worker app. */
+  document: VirtualDocument;
+  /** Emulated `window.location` that syncs navigation to the main thread. */
+  location: WorkerLocation;
+  /** Emulated `window.history` that syncs pushState/replaceState to the main thread. */
+  history: WorkerHistory;
+  /** Screen dimensions (resolved via sync channel when available, fallback 1280x720). */
+  screen: {
+    width: number;
+    height: number;
+  };
+  /** Viewport width (resolved via sync channel when available, fallback 1280). */
+  innerWidth: number;
+  /** Viewport height (resolved via sync channel when available, fallback 720). */
+  innerHeight: number;
+  /** App-scoped localStorage backed by sync channel reads to the real `localStorage`. */
+  localStorage: ScopedStorage;
+  /** App-scoped in-memory sessionStorage (tied to worker lifecycle). */
+  sessionStorage: ScopedStorage;
+  /** Add a document-level event listener. */
+  addEventListener(name: string, callback: (e: unknown) => void): void;
+  /** Remove a document-level event listener. */
+  removeEventListener(name: string, callback: (e: unknown) => void): void;
+  /** Scroll the main-thread viewport to the given coordinates. */
+  scrollTo(x: number, y: number): void;
+  /** Read computed style for a virtual element via the sync channel. */
+  getComputedStyle(el: unknown): Record<string, string>;
+  /** Polyfilled `requestAnimationFrame` using `setTimeout` (~16ms). */
+  requestAnimationFrame(cb: (time: number) => void): number;
+  /** Cancel a pending `requestAnimationFrame` callback. */
+  cancelAnimationFrame(id: number): void;
+  /** Virtual `MutationObserver` for observing virtual DOM mutations. */
+  MutationObserver: typeof VirtualMutationObserver;
+  /** Virtual `ResizeObserver` stub. */
+  ResizeObserver: typeof VirtualResizeObserver;
+  /** Virtual `IntersectionObserver` stub. */
+  IntersectionObserver: typeof VirtualIntersectionObserver;
+  setTimeout: typeof setTimeout;
+  setInterval: typeof setInterval;
+  clearTimeout: typeof clearTimeout;
+  clearInterval: typeof clearInterval;
+  queueMicrotask: typeof queueMicrotask;
+  performance: typeof performance;
+  fetch: typeof fetch | undefined;
+  URL: typeof URL;
+  URLSearchParams: typeof URLSearchParams;
+  console: typeof console;
+  btoa: typeof btoa;
+  atob: typeof atob;
+  navigator: PlatformHost["navigator"];
+  Event: typeof VirtualEvent;
+  CustomEvent: typeof VirtualCustomEvent;
+  /** Standard DOM node type constants. */
+  Node: {
+    ELEMENT_NODE: 1;
+    TEXT_NODE: 3;
+    COMMENT_NODE: 8;
+    DOCUMENT_NODE: 9;
+    DOCUMENT_FRAGMENT_NODE: 11;
+  };
+  HTMLElement: typeof VirtualElement;
+  devicePixelRatio: number;
+  /** Stub `matchMedia` that always returns `matches: false`. */
+  matchMedia: (query: string) => {
+    matches: boolean;
+    media: string;
+    addEventListener: () => void;
+    removeEventListener: () => void;
+  };
+  /** Stub `getSelection` that returns an empty selection. */
+  getSelection: () => {
+    rangeCount: number;
+    getRangeAt: () => null;
+    addRange: () => void;
+    removeAllRanges: () => void;
+  };
+  /** Dispatch an event on the virtual document. */
+  dispatchEvent: (event: unknown) => boolean;
+  /**
+   * Evaluate code in a sandboxed scope. Only available when `sandbox` includes `"eval"`.
+   * Throws if sandbox eval is not enabled.
+   */
+  eval: (code: string) => unknown;
+}
+/** Emulated `Location` object synced from the main thread. Navigation calls generate mutations. */
+interface WorkerLocation {
+  hash: string;
+  href: string;
+  port: string;
+  host: string;
+  origin: string;
+  hostname: string;
+  pathname: string;
+  protocol: string;
+  search: string;
+  toString(): string;
+  assign(url: string): void;
+  replace(url: string): void;
+  reload(): void;
+}
+/** Emulated `History` object. `pushState`/`replaceState` calls generate navigation mutations. */
+interface WorkerHistory {
+  state: unknown;
+  pushState(state: unknown, title: string, url: string): void;
+  replaceState(state: unknown, title: string, url: string): void;
+  back(): void;
+  forward(): void;
+  go(delta?: number): void;
+  length: number;
+}
+/**
+ * Creates a virtual DOM environment inside a Web Worker.
+ *
+ * Returns a `document` and `window` that can be used by frameworks
+ * or vanilla JS. All DOM mutations are automatically collected and
+ * sent to the main thread for rendering.
+ */
+declare function createWorkerDom(config?: WorkerDomConfig): WorkerDomResult;
+//#endregion
+export { ScopedStorage as a, VirtualElement as c, MutationCollector as d, PlatformHost as f, detectPlatform as h, createWorkerDom as i, VirtualNode as l, createWorkerPlatform as m, WorkerDomResult as n, VirtualDocument as o, createNodePlatform as p, WorkerWindow as r, VirtualCommentNode as s, WorkerDomConfig as t, VirtualTextNode as u };
+//# sourceMappingURL=index3.d.cts.map