Documentation / @ripl/dom

@ripl/dom

DOM utilities for Ripl — a unified API for 2D graphics rendering in the browser.

Installation

npm install @ripl/dom

Overview

DOM utilities and a lightweight virtual DOM reconciler used internally by browser contexts. This package is primarily an internal dependency — most users won't need to interact with it directly.

API

reconcileNode(domParent, vnode, domCache, options)

Reconciles a virtual node tree against the real DOM, creating, updating, and removing elements as needed.

ensureGroupPath(root, groupIds, defaultTag?)

Ensures a nested group structure exists within the virtual tree, creating intermediate nodes as needed.

getAncestorGroupIds(element)

Returns the chain of ancestor group IDs for a given element reference.

createVNode(id, tag, children?, element?)

Creates a new virtual node.

Documentation

Full documentation is available at ripl.run.

License

MIT

Classes

Class	Description
DOMContext	DOM-aware rendering context that extends the base Context with element mounting, resize observation, and interaction handling.
DOMNavigator	DOM-bound Navigator that translates real wheel/pointer/touch gestures into the base navigator's imperative commands — the pan/zoom/brush analogue of how DOMContext adds real event listeners on top of the abstract Context. The base class in @ripl/core owns the view model and stays context-agnostic; this subclass owns input.

Interfaces

Interface	Description
DOMElementResizeEvent	Simplified resize event containing the new dimensions of the observed element.
DOMNavigatorOptions	Options for constructing a DOMNavigator, adding interaction wiring to the base options.
ParentRef	A linked-list reference to an element's parent chain, used to resolve ancestor group paths.
ReconcilerOptions	Configuration for the DOM reconciler, providing element lifecycle callbacks and filtering.
VNode	A virtual DOM node representing an element in the reconciled tree.

Type Aliases

Type Alias	Description
DOMElementEventMap	Resolves the correct event map for a given DOM element type.
DOMElementResizeHandler	Callback invoked when an observed element is resized.
DOMEventHandler	A strongly-typed DOM event handler bound to a specific element and event type.

Variables

Variable	Description
hasWindow	Whether the current environment has a window object (i.e. is a browser context).

Functions

Function	Description
createCanvasExport	Builds a ContextExport from an HTMLCanvasElement, shared by every canvas-backed context (Canvas 2D, 3D, WebGPU). The canvas is snapshotted immediately by copying its current pixels onto a detached 2D canvas, so the returned exporters are unaffected by subsequent rendering. This works for any canvas regardless of the API used to draw it, because the source canvas is a valid drawImage source even when backed by WebGL/WebGPU — so callers should ensure a frame has been rendered before exporting (WebGPU present textures are transient).
createNavigator	Factory that creates a DOM-bound DOMNavigator for the given context.
createVNode	Creates a new virtual node with the given id, tag, optional children, and optional backing element.
ensureGroupPath	Ensures that a nested group path exists in the virtual tree, creating missing intermediate nodes as needed.
getAncestorGroupIds	Walks the parent chain of an element and collects group IDs from root to leaf (excluding the scene root).
onDOMElementResize	Observes an element for size changes using ResizeObserver (with a window.resize fallback) and returns a disposable.
onDOMEvent	Attaches a strongly-typed event listener to a DOM element and returns a disposable for cleanup.
reconcileNode	Reconciles a virtual node tree against the live DOM, creating, updating, reordering, and removing child elements as needed.