@atolljs/islands 0.1.12 → 0.1.14

package/dist/worker/dom/document.d.ts

@@ -0,0 +1,274 @@
+import type { HostInstance } from '../instance.js';
+import type { EventPayload, MeasuredRect } from '../../ops.js';
+import { ProxyNode, ProxyText, ProxyComment, ProxyFragment, type ProxyEventHandler } from './node.js';
+import { ProxyElement } from './element.js';
+import type { WindowShim, WindowFacadeBundle } from './window.js';
+export interface ProxyDocument {
+    /**
+     * The island's root container — driver-side id 0. `body` and
+     * `documentElement` are aliases of it; appending to either lands elements
+     * at the island root. Its own attr/style/listen mutations target the real
+     * container element.
+     */
+    readonly body: ProxyElement;
+    readonly documentElement: ProxyElement;
+    createElement(tag: string): ProxyElement;
+    /**
+     * Namespaced creation for SVG/MathML trees — the `create` op carries the
+     * namespace so the driver uses `createElementNS`. Needed by libraries that
+     * build SVG imperatively (d3-style code).
+     */
+    createElementNS(ns: string, tag: string): ProxyElement;
+    createTextNode(text: string): ProxyText;
+    /**
+     * A comment node — nodeType 8 backed by a REAL empty text node
+     * driver-side (the wire has no comment op) so it anchors `before:`
+     * positions like a real comment. `data` writes stay shadow-only.
+     */
+    createComment(data?: string): ProxyComment;
+    /**
+     * A phantom container for batching — appending the fragment splices its
+     * children into the target like the DOM does (each child emits its own
+     * append op). Fragments never exist driver-side.
+     */
+    createDocumentFragment(): ProxyFragment;
+    /** DOM `importNode` semantics — a deep/shallow clone through this
+     *  document (proxy nodes are single-instance, so cloning IS importing). */
+    importNode(node: ProxyNode, deep?: boolean): ProxyNode;
+    /** 'about:blank' — no real document URL exists worker-side. */
+    readonly baseURI: string;
+    /**
+     * Document-level listeners: emitted as `listen` ops on id 0 — the driver
+     * attaches them to the island's real container element, so delegated
+     * handlers see every event that bubbles inside the island. This is what
+     * library-style `document.addEventListener('click', delegate)` needs.
+     * `options` carries `{once, passive, capture}` onto the wire.
+     */
+    addEventListener(type: string, fn: ProxyEventHandler, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, fn: ProxyEventHandler, options?: boolean | EventListenerOptions): void;
+    /** id-map lookup over the CONNECTED shadow tree (disconnected nodes with
+     *  an id set are remembered but not returned, matching real-DOM scoping). */
+    getElementById(id: string): ProxyElement | null;
+    /** Simple matcher: tag/.class/#id/[attr]/[attr="v"] + descendant
+     *  combinators. Anything else throws a clear unsupported-selector error. */
+    querySelector(selector: string): ProxyElement | null;
+    querySelectorAll(selector: string): ProxyElement[];
+    /** Wrap an existing host-instance record (e.g. a React-rendered element
+     *  reached via the shared `instances` map) so imperative code can navigate
+     *  or mutate around it — the bridge for nesting proxy trees inside
+     *  React-rendered parents and vice versa. */
+    adopt(instance: HostInstance): ProxyNode;
+    /**
+     * Mark `el` as reporting the pushed container size — the driver's only
+     * measured box is the island container, so geometry reads
+     * (`clientWidth/Height`, `offsetWidth/Height`, `getBoundingClientRect`)
+     * on marked elements return the last `setSize` push exactly like
+     * `doc.body`/`documentElement`. Only honest for elements that actually
+     * fill the island's box (a map viewport, a canvas host).
+     */
+    markContainer(el: ProxyElement): void;
+    /**
+     * Request REAL geometry for `el` — emits a `measure` op asking the driver
+     * to measure the actual node and ResizeObserver it. `cb` fires inside the
+     * instance's task scope on every `setRects` push (the first arrives as
+     * soon as the driver answers, then on every element resize), so observer
+     * mutations emit ops like onResize handlers. The element's geometry reads
+     * (`clientWidth`, `getBoundingClientRect`, …) serve the last pushed rect
+     * from then on. Returns a detacher — removing the last observer emits
+     * `unmeasure`. This backs the `ResizeObserver` shim; call it directly for
+     * the plain (rect) => void form.
+     */
+    observeSize(el: ProxyElement, cb: (rect: MeasuredRect) => void): () => void;
+    /**
+     * Register a handler fired every time the driver pushes a new container
+     * size — the app's resize signal. Handlers run inside the instance's task
+     * scope, so their proxy-DOM mutations emit ops and `emit` routes.
+     */
+    onResize(cb: (w: number, h: number) => void): void;
+    /**
+     * The window facade `installDomShim` installed this document under —
+     * what `document.defaultView` reads as (`window.getComputedStyle` etc).
+     * undefined until the shim installs.
+     */
+    readonly defaultView?: WindowShim;
+    /** No measurement channel — returns an all-empty declaration (warns once). */
+    getComputedStyle(el: ProxyElement): CSSStyleDeclaration;
+    /** Unregister every handler this document's listeners hold. Called by the
+     *  worker on rebuild so stale handler ids can't be dispatched into dead
+     *  nodes; mutating a disposed document throws. */
+    dispose(): void;
+}
+export declare class InternalDocument implements ProxyDocument {
+    readonly instance: string;
+    readonly _root: ProxyElement;
+    readonly _wrappers: Map<number, ProxyNode>;
+    readonly _ids: Map<string, ProxyElement>;
+    /** handler ids this document registered — disposed on rebuild. */
+    readonly _handlerIds: Set<number>;
+    /**
+     * instance ids geometry reads answer for — id 0 (the root) plus every
+     * markContainer()ed element. The pushed box is the ISLAND CONTAINER's,
+     * so a marked element claims "my box is the container's box".
+     */
+    readonly _containerIds: Set<number>;
+    /** Handlers fired when a setSize task pushes a new container size. */
+    private readonly _resizeHandlers;
+    /** element id → observeSize callbacks, fired on each setRects push. */
+    private readonly _sizeObservers;
+    /** ids a `measure` op was already emitted for — dedupes observeSize and
+     *  the lazy auto-request a bare geometry read performs. */
+    readonly _measureRequested: Set<number>;
+    /** The window facade bundle — built lazily by windowFacadeFor, shared by
+     *  installDomShim and the instance dispatcher. */
+    _windowBundle?: WindowFacadeBundle;
+    /** what `document.defaultView` reads as (`window.getComputedStyle` etc). */
+    get defaultView(): WindowShim | undefined;
+    /** Document-level listeners — separate table from the root element's, so
+     *  doc.addEventListener and body.addEventListener don't wrongly dedupe
+     *  against each other. Both emit `listen` on id 0. */
+    private readonly _docListeners;
+    private readonly _warned;
+    _disposed: boolean;
+    /** Set by installDomShim — restore globals when this document dies. */
+    _uninstallShim: (() => void) | null;
+    constructor(instance: string);
+    get body(): ProxyElement;
+    get documentElement(): ProxyElement;
+    /** No hit-testing exists worker-side — honest null (a11y-layer probing). */
+    elementFromPoint(_x: number, _y: number): null;
+    _assertAlive(): void;
+    _warn(feature: string, message?: string): void;
+    /** Scroll-geometry warn — the measure channel delivers border boxes, not
+     *  scroll offsets/overflow extents, so scroll* reads stay honest 0. */
+    _scrollWarn(feature: string): void;
+    markContainer(el: ProxyElement): void;
+    /**
+     * Emit `measure` for `el` exactly once — shared by observeSize (explicit
+     * subscription) and by geometry reads on unmarked connected elements (the
+     * lazy path: a library reading clientWidth gets the honest 0 for now, and
+     * REAL geometry on subsequent reads once the driver's push lands).
+     * Disconnected/phantom nodes have no driver-side element to measure;
+     * requesting is skipped until the read happens while connected.
+     */
+    _requestMeasure(el: ProxyElement): void;
+    observeSize(el: ProxyElement, cb: (rect: MeasuredRect) => void): () => void;
+    /**
+     * Store pushed rects and fire per-element observers — the `setRects`
+     * task calls this inside the instance's scope, so observer mutations
+     * emit ops and ride back in the task's return batch.
+     */
+    _notifyRects(rects: MeasuredRect[]): void;
+    /**
+     * The rect a geometry read on `el` may report: the element's own measured
+     * box when a setRects push arrived for it, else the pushed CONTAINER box
+     * when `el` is the root or was markContainer()ed (the old contract — a
+     * marked element claims "my box is the container's"), undefined otherwise
+     * (also undefined when nothing has been pushed yet — reads return 0).
+     */
+    _rectFor(el: ProxyElement): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | undefined;
+    onResize(cb: (w: number, h: number) => void): void;
+    /**
+     * Fire the doc's resize handlers — the worker's `setSize` task calls this
+     * inside the instance's scope, so handler mutations emit ops on the instance
+     * queue and come back in the task's return batch.
+     */
+    _notifySize(w: number, h: number): void;
+    /** Keep the getElementById map pointing at each element's CURRENT id. */
+    _trackId(el: ProxyElement): void;
+    /** The synthetic text child an element's `textContent` setter leaves in
+     *  the shadow tree — no driver-side node, so its writes retarget parent. */
+    _phantomText(parent: ProxyNode, text: string): ProxyText;
+    /**
+     * Enrich a dispatched payload before handing it to a proxy listener:
+     *  - `target` = the proxy node for targetId, looked up in the shared
+     *    instance space and wrapped in THIS document's wrapper map (so
+     *    `e.target.closest`/`.dataset`/`.contains` behave like the real DOM
+     *    for proxy-created nodes).
+     *  - `currentTarget` = `self` — the node/document/facade the listener was
+     *    attached to (the handler is also invoked with `this` = self). For
+     *    document/window listeners this is the document/facade OBJECT, not
+     *    the id-0 root element dispatch() would otherwise stamp.
+     *  - `composedPath()` = synthesized from the enriched target's parent
+     *    chain, with `self` appended when the chain doesn't already reach it
+     *    (delegated handlers iterate the path until they hit their own
+     *    element — Svelte's handle_event_propagation terminates there).
+     *  - `preventDefault`/`stopPropagation`/`stopImmediatePropagation` =
+     *    synthesized NO-OPS. They cannot cancel anything — the real event
+     *    already dispatched on the main thread before this payload crossed
+     *    postMessage — but library code written against real DOM events calls
+     *    them unconditionally, so the wrapper supplies them.
+     */
+    _enrichEvent(payload: EventPayload, self?: unknown): EventPayload;
+    createElement(tag: string): ProxyElement;
+    createElementNS(ns: string, tag: string): ProxyElement;
+    private _newElement;
+    createTextNode(text: string): ProxyText;
+    adopt(instance: HostInstance): ProxyNode;
+    createDocumentFragment(): ProxyFragment;
+    /**
+     * A comment — nodeType 8 over a real EMPTY text instance. The wire has no
+     * comment op: the `text` op with '' gives it a driver-side node that can
+     * anchor `before:` positions, while `data` stays shadow-only (emitting it
+     * would render comment text on the page).
+     */
+    createComment(data?: string): ProxyComment;
+    /**
+     * DOM `importNode` — a clone through this document. Foreign (non-proxy)
+     * nodes have no shadow shape to copy; they're rejected like any other
+     * foreign child.
+     */
+    importNode(node: ProxyNode, deep?: boolean): ProxyNode;
+    /**
+     * 'about:blank' — no real document URL exists worker-side. A plain field
+     * (not a getter) so adapters may assign it like a normal document prop.
+     */
+    readonly baseURI: string;
+    /** Wrap (or return the existing wrapper for) a shared instance record. */
+    _wrap(instance: HostInstance): ProxyNode;
+    /**
+     * Document-level listener — same currency as element addEventListener but
+     * targeting id 0 (the island's container element). The driver's listen op
+     * attaches a real DOM listener on the container, so events bubbling up
+     * from any island child dispatch back here. Used by library code doing
+     * delegated `document.addEventListener(...)`.
+     */
+    addEventListener(type: string, fn: ProxyEventHandler, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, fn: ProxyEventHandler, options?: boolean | EventListenerOptions): void;
+    getElementById(id: string): ProxyElement | null;
+    querySelector(selector: string): ProxyElement | null;
+    querySelectorAll(selector: string): ProxyElement[];
+    getComputedStyle(el: ProxyElement): CSSStyleDeclaration;
+    dispose(): void;
+}
+export declare const createProxyDocument: (instance: string) => ProxyDocument;
+/**
+ * The instance's proxy document, creating it lazily — the getPublicInstance
+ * path (React mounts only need a document when a library holds a ref or a
+ * portal target).
+ */
+export declare const docForInstance: (instance: string) => InternalDocument;
+/** The instance's proxy document if one was materialized — never creates.
+ *  Rendered instances may hold none (React's host config writes instance
+ *  records, not proxy nodes, until a ref/portal adopts them). */
+export declare const peekInstanceDoc: (instance: string) => InternalDocument | undefined;
+/** Dispose the instance's proxy document if one exists — covers docs
+ *  materialized through `docForInstance`, not just `ctx.doc`, so unmount
+ *  can't leave a stale entry for ambient-document resolution. */
+export declare const disposeInstanceDoc: (instance: string) => void;
+/**
+ * The document `globalThis.document` should mean right now: the active
+ * instance's when a task holds one; the single registered document when only
+ * one instance exists (every real island worker — timers and promise
+ * continuations run outside instance tasks but unambiguously belong to it);
+ * the most recently active instance's otherwise (multi-instance in-process tests
+ * still route deferred library callbacks sensibly).
+ */
+export declare const activeInstanceDoc: () => InternalDocument | undefined;
+/** The ambient document: the sole registered doc, or the most recently
+ *  active instance's — for out-of-task readers (timers, continuations). */
+export declare const ambientDoc: () => InternalDocument | undefined;

package/dist/worker/dom/element.d.ts

@@ -0,0 +1,199 @@
+import type { ElementInstance } from '../instance.js';
+import { ProxyNode, ProxyFragment, type ProxyEventHandler } from './node.js';
+import { type ProxyClassList } from './css.js';
+/** Positions `insertAdjacentHTML`/`insertAdjacentElement` accept. */
+export type AdjacentPosition = 'beforebegin' | 'afterbegin' | 'beforeend' | 'afterend';
+export declare class ProxyElement extends ProxyNode {
+    readonly instance: ElementInstance;
+    readonly _attrs: Map<string, string>;
+    _classes: Set<string>;
+    readonly _styleProps: Record<string, string>;
+    private readonly _listeners;
+    get nodeType(): number;
+    get tagName(): string;
+    /** The element's namespace URI — HTML for ordinary elements, the `create`
+     *  op's `ns` for namespaced (svg/mathml) ones. */
+    get namespaceURI(): string;
+    /** Element children only — the shadow tree's HTMLCollection equivalent. */
+    get children(): ProxyElement[];
+    get id(): string;
+    set id(v: string);
+    get className(): string;
+    set className(v: string);
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    setAttributeNS(_ns: string | null, qualifiedName: string, value: string): void;
+    getAttributeNS(_ns: string | null, name: string): string | null;
+    removeAttributeNS(_ns: string | null, name: string): void;
+    get classList(): ProxyClassList;
+    /**
+     * Inline style — a Proxy over a plain prop record. Writes re-send only
+     * the changed key; `delete style.x`/`style.removeProperty('x')` send ''
+     * (the protocol's "clear this key"). `setProperty`/`getPropertyValue`
+     * accept kebab-case and camelize it, like the real CSSStyleDeclaration.
+     */
+    get style(): CSSStyleDeclaration;
+    /**
+     * dataset — a Proxy mapping camelCase keys to `data-*` attribute ops.
+     * `swatch.dataset.color = c` emits attr {name:'data-color', value:c};
+     * `delete el.dataset.x` emits the removal form.
+     */
+    get dataset(): DOMStringMap;
+    /**
+     * Focus/blur — NO-OPS. Real focus can't be delivered over async postMessage
+     * (the driver's dispatch fires after the event; there is no focus op).
+     * They exist because gesture libraries call `el.focus()` unconditionally
+     * during mousedown paths (Leaflet's Keyboard handler does).
+     */
+    focus(): void;
+    blur(): void;
+    addEventListener(type: string, fn: ProxyEventHandler, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, fn: ProxyEventHandler, options?: boolean | EventListenerOptions): void;
+    /** Live-descendant search over the shadow tree. Nodes mounted by the
+     *  reconciler aren't reachable (the op stream doesn't mirror React's
+     *  structure into _children) — adopted subtrees match only their own
+     *  proxy-built descendants. Class matching reads _classes AND the
+     *  instance's serialized className prop, so adopted React elements with
+     *  className set still match. */
+    getElementsByClassName(name: string): ProxyElement[];
+    getElementsByTagName(tag: string): ProxyElement[];
+    getBBox(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    getTotalLength(): number;
+    getComputedTextLength(): number;
+    matches(selector: string): boolean;
+    /** Nearest element (self inclusive) matching the selector — walks the
+     *  shadow tree upward through ancestors. */
+    closest(selector: string): ProxyElement | null;
+    /** Scoped local-tree query — descendants only, same engine and the same
+     *  supported-selector subset as document.querySelectorAll. */
+    querySelector(selector: string): ProxyElement | null;
+    querySelectorAll(selector: string): ProxyElement[];
+    /** Serialized shadow-tree children — the only innerHTML there CAN be over
+     *  an async op channel (it reflects writes made through this facade, not
+     *  the real DOM's current markup). */
+    get innerHTML(): string;
+    get outerHTML(): string;
+    /**
+     * Parse `html` worker-side (htmlparser2 — pure JS, worker-safe) and
+     * rebuild this element's children as proxy nodes: each parsed element is
+     * createElement + setAttribute + recursive children, each text run a
+     * createTextNode — all emitting ordinary create/attr/append ops. Existing
+     * children are removed first (one remove op each). Comments and
+     * directives are skipped.
+     */
+    set innerHTML(html: string);
+    /**
+     * Parse `html` and insert the resulting nodes relative to this element —
+     * 'beforebegin'/'afterend' require a parent and no-op without one (like
+     * the DOM on detached elements).
+     */
+    insertAdjacentHTML(position: AdjacentPosition, html: string): void;
+    /** insertAdjacentElement — returns the inserted element like the DOM. */
+    insertAdjacentElement(position: AdjacentPosition, el: ProxyElement): ProxyElement | null;
+    private _insertAt;
+    /**
+     * `<template>.content` — a fragment VIEW sharing the element's shadow
+     * child array (same backing store) AND the element's instance id, so
+     * `content.appendChild` emits `append` ops targeted at the template. The
+     * driver routes template-parented ops into `el.content` — the DOM spec's
+     * home for template children anyway. Non-template elements read
+     * undefined.
+     */
+    get content(): ProxyFragment | undefined;
+    /**
+     * Clone as new ops — the copy gets its own instance id (it's a real new
+     * element on the main thread, not a shared record). Attributes, the
+     * namespace and the style-proxy properties are copied; listeners are NOT
+     * (matches the DOM). `deep` clones children polymorphically — comment
+     * children keep nodeType 8, texts and nested elements/fragments their
+     * own kind.
+     */
+    cloneNode(deep?: boolean): ProxyElement;
+    getBoundingClientRect(): DOMRect;
+    get clientWidth(): number;
+    get clientHeight(): number;
+    get offsetWidth(): number;
+    get offsetHeight(): number;
+    /** Border edge widths — honestly 0 (the pushed box doesn't measure borders). */
+    get clientLeft(): number;
+    get clientTop(): number;
+    /** Position within offsetParent — not measured; 0 is honest for root-level boxes. */
+    get offsetLeft(): number;
+    get offsetTop(): number;
+    get offsetParent(): null;
+    get scrollTop(): number;
+    set scrollTop(_v: number);
+    get scrollLeft(): number;
+    set scrollLeft(_v: number);
+    get scrollHeight(): number;
+    get scrollWidth(): number;
+    /**
+     * Reflected properties. Library code assigns `img.src = url`,
+     * `el.tabIndex = 0`, `link.href = '#'` — on a bare class instance those
+     * become silent expandos and nothing crosses the wire. The attribute-backed
+     * accessors below (defined for the properties real libraries poke) make
+     * those assignments emit ordinary `attr` ops. Everything else still falls
+     * through to a plain own-property — which is also exactly what library
+     * expandos like `_leaflet_pos` need, so proxy elements are deliberately
+     * NOT frozen/sealed.
+     */
+    get src(): string;
+    set src(v: string);
+    get srcset(): string;
+    set srcset(v: string);
+    get href(): string;
+    set href(v: string);
+    get alt(): string;
+    set alt(v: string);
+    get title(): string;
+    set title(v: string);
+    get tabIndex(): number;
+    set tabIndex(v: number);
+    get draggable(): boolean;
+    set draggable(v: boolean);
+    get crossOrigin(): string | null;
+    set crossOrigin(v: string | null);
+    get width(): number;
+    set width(v: number);
+    get height(): number;
+    set height(v: number);
+    get type(): string;
+    set type(v: string);
+    get loading(): string;
+    set loading(v: string);
+    get decoding(): string;
+    set decoding(v: string);
+    get value(): string;
+    set value(v: string);
+    get checked(): boolean;
+    set checked(v: boolean);
+    get disabled(): boolean;
+    set disabled(v: boolean);
+    /** Geometry read shared by the size getters above. */
+    _geom(feature: string, pick: (rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => number): number;
+    _writeStyle(key: string, value: string): void;
+    /** style.cssText — a FULL replace, not another key. Parse the declarations
+     *  and write each through the dedup path; keys absent from the new text
+     *  clear. Storing the text under a 'cssText' key left stale per-key values
+     *  that deduped real writes away (a hide's `visibility:hidden` stuck after
+     *  a show's cssText replay). */
+    _replaceStyleText(cssText: string): void;
+    private _setAttr;
+    private _afterAttrChange;
+}

package/dist/worker/dom/html.d.ts

@@ -0,0 +1,7 @@
+import { ProxyNode } from './node.js';
+import type { InternalDocument } from './document.js';
+export declare function parseChildren(doc: InternalDocument, html: string): ProxyNode[];
+/** Serialize a shadow node — elements with attrs (+ inline style from the
+ *  style proxy), text escaped, comments round-tripping as `<!--data-->`.
+ *  Reads the shadow tree only; nothing the proxy didn't write appears here. */
+export declare function serializeNode(node: ProxyNode): string;

package/dist/worker/dom/node.d.ts

@@ -0,0 +1,172 @@
+import type { HostInstance, TextInstance } from '../instance.js';
+import type { EventPayload, Op } from '../../ops.js';
+import type { InternalDocument, ProxyDocument } from './document.js';
+/** Handler signature for proxy addEventListener — the wire payload plus a
+ *  synthesized `target` (the proxy node for `targetId`, when known).
+ *  `this` is bound to the node/document/facade the listener was attached
+ *  to, like the real DOM's currentTarget. */
+export type ProxyEventHandler = (this: unknown, payload: EventPayload) => void;
+/** The subset of AddEventListenerOptions the `listen`/`unlisten` ops carry. */
+export interface WireListenerOpts {
+    once?: boolean;
+    passive?: boolean;
+    capture?: boolean;
+}
+/** Normalize the DOM's `options | captureFlag` argument into concrete flags. */
+export declare const normalizeListenerOptions: (options?: boolean | AddEventListenerOptions | EventListenerOptions | null) => {
+    once: boolean;
+    passive: boolean;
+    capture: boolean;
+};
+/** The `opts` field for a listen/unlisten op — undefined when every flag is
+ *  off so plain listeners emit the same op shape as before. */
+export declare const listenerOptsForWire: (options?: boolean | AddEventListenerOptions | EventListenerOptions | null) => WireListenerOpts | undefined;
+export declare const hyphenate: (k: string) => string;
+export declare const camelize: (k: string) => string;
+export declare const allocPhantomId: () => number;
+/**
+ * A node that isn't a ProxyNode can only arrive via a foreign `document`
+ * (the dispatcher's real-DOM fallback or a poisoned override) — typically a
+ * library's deferred callback running after its instance was torn down, or
+ * globals restored while worker-side timers still fire. Adopting it would
+ * crash later on `child.instance`; reject it here with the actual cause.
+ */
+export declare const rejectForeignChild: (child: unknown) => never;
+/**
+ * Detach `child` from its recorded parent, tolerating a stale/foreign
+ * `_parent` link (undefined, or a non-proxy object) instead of crashing on
+ * `_detach` — a corrupted link is cleared, a valid one is honored.
+ */
+export declare const detachFromParent: (child: ProxyNode) => void;
+export declare class ProxyNode {
+    /** The shared host-instance record — same objects `instances` holds. */
+    readonly instance: HostInstance;
+    /** The document that created/wrapped this node (internal fields below). */
+    readonly doc: InternalDocument;
+    _parent: ProxyNode | null;
+    _children: ProxyNode[];
+    constructor(doc: InternalDocument, instance: HostInstance);
+    get nodeType(): number;
+    /**
+     * '#text'/'#comment'/'#document-fragment' for character/fragment nodes;
+     * the tag name for elements — uppercase in the HTML namespace, verbatim
+     * for namespaced elements (svg 'foreignObject' keeps its case, matching
+     * the real DOM).
+     */
+    get nodeName(): string;
+    /** The proxy document that owns this node — what real DOM code reads as
+     *  `el.ownerDocument`. */
+    get ownerDocument(): ProxyDocument;
+    get parentNode(): ProxyNode | null;
+    get parentElement(): ProxyNode | null;
+    /** A copy of the shadow child list — structural changes go through
+     *  appendChild/insertBefore/removeChild so ops stay in sync. */
+    get childNodes(): ProxyNode[];
+    get firstChild(): ProxyNode | null;
+    get lastChild(): ProxyNode | null;
+    get nextSibling(): ProxyNode | null;
+    get previousSibling(): ProxyNode | null;
+    /** Attached to the document's root (driver-side id 0 container)? */
+    get isConnected(): boolean;
+    /**
+     * The topmost shadow-tree ancestor — the root container element when the
+     * node is connected. (The facade has no separate Document node object;
+     * `doc.body`/`documentElement` ARE that root.)
+     */
+    getRootNode(): ProxyNode;
+    /** Concatenated descendant text — walked from the shadow tree. Comments
+     *  are excluded: the DOM's descendant text content is Text-node data only. */
+    get textContent(): string;
+    set textContent(value: string);
+    contains(other: ProxyNode): boolean;
+    appendChild<T extends ProxyNode>(child: T): T;
+    insertBefore<T extends ProxyNode>(child: T, ref: ProxyNode | null): T;
+    removeChild<T extends ProxyNode>(child: T): T;
+    /** Detach from the parent — no-op when already orphaned (like the DOM). */
+    remove(): void;
+    before(...nodes: Array<ProxyNode | string>): void;
+    after(...nodes: Array<ProxyNode | string>): void;
+    replaceWith(...nodes: Array<ProxyNode | string>): void;
+    /** append(...nodes) — strings become text nodes, like the DOM. */
+    append(...nodes: Array<ProxyNode | string>): void;
+    /** prepend(...nodes) — inserts at the front, in argument order. */
+    prepend(...nodes: Array<ProxyNode | string>): void;
+    /** replaceChildren(...nodes) — remove every child, then append the set. */
+    replaceChildren(...nodes: Array<ProxyNode | string>): void;
+    /**
+     * Structural clone — each concrete kind implements it. The copy is a
+     * FRESH instance (own id, own create op), not a shared record; listeners
+     * never cross, matching the DOM.
+     */
+    cloneNode(_deep?: boolean): ProxyNode;
+    /**
+     * Queue an op on this node's instance — the same routing hostConfig uses for
+     * instance-bound ops. Outside a instance task the op still lands on the right
+     * queue, and the doorbell is bumped so push-mode islands pick it up.
+     */
+    _op(op: Op): void;
+    /** Detach a child from the shadow list WITHOUT emitting an op — used when
+     *  a following append op will move the real node on the main thread. */
+    _detach(child: ProxyNode): void;
+    /** Handler ids this node's records own: addEventListener hids (element
+     *  subclass only) plus the prop-listener slots on the instance record. */
+    _recordHandlerIds(): number[];
+    /** Tombstone this subtree's instance/handler records (removeChild). */
+    _detachRecords(): void;
+    /** Restore this subtree's records on re-append (idempotent — a live node
+     *  is simply not in the tombstone maps). */
+    _attachRecords(): void;
+}
+export declare class ProxyText extends ProxyNode {
+    readonly instance: TextInstance;
+    constructor(doc: InternalDocument, instance: TextInstance);
+    get nodeType(): number;
+    /**
+     * The driver-side id a text write targets. Real text instances write
+     * their own id; phantoms (created by an element's `textContent` setter)
+     * have no driver-side node, so writes retarget the parent — whose real
+     * `textContent` IS this node's whole text.
+     */
+    get _utextTarget(): number;
+    get data(): string;
+    set data(v: string);
+    get nodeValue(): string;
+    set nodeValue(v: string);
+    get textContent(): string;
+    set textContent(v: string);
+    private _write;
+    /** Fresh text node — the clone is a new `text` op, not a shared record. */
+    cloneNode(_deep?: boolean): ProxyText;
+}
+/**
+ * Comment — nodeType 8, backed by a REAL empty text node driver-side: the
+ * wire has no comment op, so `createComment` emits a `text` op with ''
+ * giving the node a `before:`-addressable position for anchors (Svelte's
+ * `<!>` block boundaries, Vue/Angular comment anchors).
+ *
+ * `data`/`nodeValue`/`textContent` writes update the shadow record ONLY —
+ * emitting `utext` would render the comment's data as visible page text.
+ */
+export declare class ProxyComment extends ProxyText {
+    get nodeType(): number;
+    get data(): string;
+    set data(v: string);
+    get nodeValue(): string;
+    set nodeValue(v: string);
+    get textContent(): string;
+    set textContent(v: string);
+    private _shadowWrite;
+    cloneNode(_deep?: boolean): ProxyComment;
+}
+/**
+ * DocumentFragment — a PHANTOM parent: it never exists driver-side, so its
+ * `instance.id` is negative (no ops ever target it). Appending it to a real
+ * parent splices its children out like the DOM does; libraries use it to
+ * batch insertions (Leaflet's GridLayer builds each zoom level in one).
+ */
+export declare class ProxyFragment extends ProxyNode {
+    get nodeType(): number;
+    /** Fresh fragment; `deep` clones children polymorphically so comment
+     *  anchors keep nodeType 8. */
+    cloneNode(deep?: boolean): ProxyFragment;
+}