Documentation / @ripl/dom

@ripl/dom

The DOM layer shared by Ripl's browser contexts: element mounting, pointer interaction, a virtual-DOM reconciler and the pan/zoom navigator.

This is an internal dependency. @ripl/canvas, @ripl/svg and @ripl/3d install it for you, and @ripl/web re-exports the parts you would reach for. Install it directly only when writing a custom browser context.

Features

• DOMContext — the abstract base every browser context extends, adding element mounting, resize observation and pointer interaction to @ripl/core's Context.
• Pointer plumbing — hit tests are buffered to a frame, drags are tracked from press to release, and the click that ends a drag is suppressed, so mouseenter/mousemove/click/dragstart/drag/dragend arrive on the right element.
• DOMNavigator — turns real wheel, pointer and touch gestures into the base Navigator's pan, zoom and brush commands: drag to pan, wheel or pinch to zoom toward the pointer, shift-drag to brush. It feature-detects its host element, so a non-DOM context declines to attach instead of crashing.
• Virtual DOM reconciler — reconcileNode diffs a virtual tree against real nodes, creating, updating and removing only what changed. This is what keeps the SVG context's per-frame DOM writes proportional to the change rather than to the scene.
• Canvas export — createCanvasExport snapshots any HTMLCanvasElement (2D, WebGL or WebGPU) into a ContextExport, tracking object URLs so release() can revoke them.
• Listener helpers — onDOMEvent and onDOMElementResize return disposables, so teardown is one call.

Installation

# npm
npm install @ripl/dom

# yarn
yarn add @ripl/dom

# pnpm
pnpm add @ripl/dom

Quick start

import {
    createNavigator,
} from '@ripl/dom';

import {
    createContext,
    createScene,
} from '@ripl/web';

const context = createContext('.mount-element');
const scene = createScene(context);

const navigator = createNavigator(context, {
    interactions: true,
});

navigator.on('change', () => scene.render());

createNavigator and DOMNavigator are re-exported by @ripl/web, so a browser project never imports this package for them.

Key API

Export	What it does
DOMContext	Base class for a browser rendering context
createNavigator / DOMNavigator	Wheel, pointer and touch gestures driving pan, zoom and brush
reconcileNode / createVNode / ensureGroupPath	The virtual-DOM reconciler behind the SVG context
createCanvasExport	Builds a ContextExport from a canvas element
onDOMEvent / onDOMElementResize	Disposable DOM listener helpers

Related packages

• @ripl/web — the browser entry point, and what most projects should install
• @ripl/canvas / @ripl/svg — the contexts built on DOMContext
• @ripl/core — the context, element and navigator abstractions this layer extends

Documentation

Guides and the full API reference are at ripl.run/docs/core.

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. Degrades to an inert disposable outside a browser, so an SSR or Node consumer of this module gets a no-op rather than a ReferenceError.
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.