Liquid DOM

Liquid DOM is organized into packages based on your rendering target and preferred programming model. Select the package that matches your existing stack:

• Direct Control / Custom Renderer: Use @liquid-dom/core for an imperative DOM-backed scene graph, the WebGPU renderer, and layout classes.
• React (Declarative): Use @liquid-dom/react to describe glass UI using React 19 components. This is ideal if you want LiquidCanvas to manage the canvas or if you need a headless scene.
• Three.js (WebGPU): Use @liquid-dom/three to composite liquid glass over an existing Three.js WebGPU renderer.
• React Three Fiber (R3F): Use @liquid-dom/r3f if you are using R3F with Three's WebGPU renderer and want React-based liquid-glass UI.
• Layout Only: Use @liquid-dom/layout if you only need the renderer-agnostic, SwiftUI-style measurement and placement engine without any rendering dependency.

The Component API provides a structured way to wrap your R3F and Liquid-Glass content using a hierarchy of components:

• LiquidGlassR3F.Root: The top-level provider that shares the scene ref and invalidation bridge between the R3F canvas and the liquid-glass scene.
• LiquidGlassR3F.Scene: Creates a headless LiquidScene specifically for @liquid-dom/react layout components.
• LiquidGlassR3F.Render (or simply <LiquidGlassR3F />): Placed inside the R3F <Canvas>. It takes over the final rendering with a positive frame priority.

Component Props Reference

<LiquidGlassR3F.Root>
  <Canvas gl={createWebGpuRenderer}>
    <LiquidGlassR3F.Render renderPriority={1} />
  </Canvas>

  <LiquidGlassR3F.Scene>
    {/* @liquid-dom/react layout */}
  </LiquidGlassR3F.Scene>
</LiquidGlassR3F.Root>

The Liquid DOM scene graph is a hierarchical structure of nodes that defines how elements are composed, transformed, and rendered. The hierarchy follows specific relationship rules based on the type of parent node.

Core Node Types

• Scene: The root node. Accepts Container, Html, and Group children.
• Container: Controls optical behavior (blur, refraction, etc.) for its children. Accepts Glass and Group children. Multiple Glass children in the same container are fused into a single SDF field.
• Glass: Defines a shaped glass surface. Accepts Html and Group children. Each Html child is sampled through the glass.
• Html: Wraps live DOM content. It owns a host element and can mount an HTMLElement into it.
• Group: Composes transforms (position, scale, rotation) without affecting the stacking order.
• StackingContext: Groups children under a shared zIndex.

Relationship Rules

Nodes must match the requirements of their nearest non-group parent. For example, a Glass node must eventually be nested under a Container; it cannot be a direct child of another Glass, even if wrapped in a Group or StackingContext.

Transform Properties

All transformable nodes expose:

• x, y, origin (in CSS pixels)
• scaleX, scaleY
• rotation (in radians)

import {
  Container,
  Glass,
  Group,
  Html,
  Scene,
  StackingContext,
} from '@liquid-dom/core'

The adaptive blur pipeline optimizes performance by selecting a downsample level based on the blur radius. The pipeline follows these steps:

1. Level Selection: Chooses a downsample level using ceil(log2(radiusPx / denseRadiusPx)).
2. Downsampling: Performs a series of downsamples using a 4-sample box pass.
3. Blurring: Executes a horizontal and vertical separable blur at the selected level.
4. Upsampling: Performs a series of upsamples using a linear sampler.

Performance is measured in normalized full-resolution texture-read area units (A). A value of 1.000 A represents approximately one texture read for every full-size output pixel in the target area.

For a selected level L and shader samples per blur pass S, the cost is calculated as:

• downsample(L) = 4/3 * (1 - 4^-L)
• upsample(L) = 4/3 * (1 - 4^-L)
• blur(L) = 2 * S * 4^-L
• total(L) = downsample(L) + blur(L) + upsample(L)

In the hypothetical design, placement for transparent nodes occurs in two distinct phases to ensure correct coordinate rebasing:

Phase 1: Record Effective Child Placements

When a parent layout places projected children, it does not call placeNode immediately. Instead, it records a PlacementRecord for each effective child:

type PlacementRecord = {
  node: Layout
  transparentPath: Layout[]
  bounds: Rect
  proposal: ProposedSize
}

Phase 2: Resolve Transparent Ancestor Bounds

After all projected children are placed, the engine computes a union for each transparent ancestor. Because a later child might expand the union of a transparent ancestor, the engine must rebase all layout rects in parent-local coordinates.

Example of coordinate rebasing: If HStack places children X, Y, Z, and W, and A is a transparent ancestor of X, Y, and Z:

• A's rect is calculated as the union of X, Y, and Z relative to HStack.
• X's rect is then rebased to be local to A.

This two-phase approach ensures that even if an ancestor's bounds change due to a later sibling, all descendants receive correct local coordinates.

LayoutNodes are mutable objects that form the layout tree. They have stable IDs and support parent-child relationships similar to the DOM (e.g., appending a node to a new parent automatically detaches it from the old one).

Node Properties:

• id, kind, parent, children, layout (the calculated geometry).
• isLayoutActive(): Returns true if the node is reachable from an active LayoutEngine.root.

Geometry Types:

• layout.rect: The node's rectangle relative to its parent.
• layout.absoluteRect: The node's rectangle relative to the LayoutEngine.root (accumulated through ancestors).

Node Methods:

• append, prepend, insertBefore, replaceChildren, remove, dispose.

Lifecycle Hooks: Subclasses of Layout can override onLayoutActive() and onLayoutInactive() to manage external resources. These fire synchronously during tree mutations.

Core Types:

• ProposedSize: { width?: number; height?: number }
• Size: { width: number; height: number }
• Rect: { x: number; y: number; width: number; height: number }
• NodeLayout: { rect: Rect; absoluteRect: Rect }

This document describes a hypothetical future design for noop layout nodes in Liquid DOM. Currently, noop nodes are layout-neutral wrappers that require exactly one child because they pass measurement and placement through to that single child.

The proposed design transforms noop nodes into transparent projection nodes.

Key Characteristics:

• No measurement/placement behavior: They do not participate in the layout process themselves.
• Flattening: They are flattened into their nearest real layout parent. A parent like HStack would see the noop's children as its own direct effective children.
• Projection: When a layout node asks for children, the engine returns 'projected effective children' along with their transparent ancestor path (e.g., X -> [A, B]).
• Bounds derivation: While they don't have their own layout behavior, they still receive a layout rect derived from the union of their effective descendants. This allows wrappers (like scene graph nodes) to use that rect for transforms or state.
• Restrictions: A noop cannot be the layout root and should not be measured directly (doing so is considered a bug).