Architecture

Dependency direction

@fluxglass/core owns immutable defaults, option normalization, optical math, displacement-map generation, quality policy, scheduler contracts, and the renderer lifecycle type. It does not access browser globals or import a framework.

@fluxglass/dom owns capability detection, DOM lifecycle, one shared frame scheduler per document, one reference-counted map generator per document, its worker entry, and SVG/CSS/no-op renderers. Detection and resource creation use the target element's owning window, including in same-origin iframes.

@fluxglass/react owns only refs, effects, component markup, and hooks. Prop updates mutate the existing DOM controller; they do not duplicate optics or create a renderer during server render.

WebKit reference-filter compatibility

The SVG content-filter renderer is the degraded path on WebKit, including iOS browsers. Its refraction is clipped to a moving lens subregion while the shadow is positioned from the same container-space origin.

Some shipping WebKit versions cache filter: url(#...) output after the referenced SVG primitives change. Fluxglass detects that engine family and assigns a fresh filter ID only after a filter attribute changes, then re-points the content filter to the new ID. This keeps the refracted lens and shadow synchronized without adding work to Chromium or Firefox. Reduced-transparency users continue to receive the CSS fallback instead.

All exported TypeScript object shapes use type aliases. Public exports are explicit and deep imports are not part of the contract.