◈ lib · optical-engine
Optical Engine
One shared WebGL2 context serving every optical instrument on the page, with an intersection-gated render loop, a frame-budget ladder, and permanent CSS fallback on context loss.
Watch the surface lifecycle.
- Register: detached or static
- Enter viewport: visible surfaces become eligible.
- Render: the fallback stays visible.
- Leave viewport: drawing pauses; unmounting disposes registration.
- Fallback: tier static; reduced motion or context loss keeps the poster.
{}"use client";
import { useOpticalSurface } from '@/components/optics/useOpticalSurface';
import { createDispersionRenderer } from '@/components/optics/renderers/dispersion';
// Install prism-lens to supply this renderer. Wrap this component in MovementProvider.
export function Surface() {
const {hostRef,canvasRef,ready} = useOpticalSurface({createRenderer:createDispersionRenderer});
return <div ref={hostRef} style={{position:'relative',height:360}}>
<p>Static optical illustration</p>
<canvas ref={canvasRef} style={{position:'absolute',inset:0,width:'100%',height:'100%',opacity:ready?1:0}} />
</div>;
}Copies component source and tokens directly into your repository with requirements listed for this item: no additional npm dependencies beyond the host framework.
Open-source under MIT. We preserve the source header comment, and invite you to credit the archive on your project's /about, /colophon, or footer. Display our Archival Colophon Seal or copy a citation snippet below. Sites displaying the seal are welcome to submit to our Federation Showcase!
Mount it in your application.
React examples use a client component. Optical surfaces need a sized host, the installed optical stylesheet, and a MovementProvider above the preview. Import your chosen movement tokens and load the fonts separately.
"use client";
import { MovementProvider } from '@/components/MovementProvider';
import '@/registry/optical-components.css';
// Install movement-themes separately for the ten authored palettes.
// import '@/registry/movement-themes.css';
export default function Example() {
return <MovementProvider>{/* place the selected preview here */}</MovementProvider>;
}Source
styles/optical-components.csscomponents/optics/types.tscomponents/optics/glUtils.tscomponents/optics/opticalEngine.tscomponents/optics/useOpticalSurface.tslib/shaderTokens.tslib/opticalPreference.tslib/materialOptics.ts
Registry item: /r/optical-engine.json