# Viselora DOM WebGL

Giving web pages depth and motion while preserving their structure.

A DOM-first WebGL runtime for React and browser applications. It preserves web layout and interaction semantics, connects text, media and 3D objects through public declarations, and manages rendering, resources, input and lifecycle in one place.

[Website source](https://zzzxc.com/projects/viselora)

## When web content enters a 3D scene

Text, images, links and reading order are already organized by the web page. When they enter a WebGL scene, layout, coordinates, pointer hits, scroll responses and resource disposal must work together too. Maintaining those relationships separately for every visual effect makes later composition and changes increasingly difficult.

Viselora starts from the DOM. The page keeps the foundation for content, layout and accessibility, while the runtime connects targets that need visual treatment to WebGL. The application describes the objects and effects it wants to present; the runtime coordinates rendering and resource lifecycles underneath.

## Connecting content and visuals through declarations

DOM text, images, video, frame sequences and models can become visual sources managed by the runtime. Target declarations provide their sources and effects. Procedural geometry and scene-native models use the corresponding mesh and model declarations.

This gives visual expression a clear entry point: semantic elements carry web content, while effects describe transformations, materials or intended motion. More complex visuals can declare scenes, cameras, lights and render passes, then update objects through controlled interfaces. Application code uses public APIs throughout; the runtime creates and destroys the underlying objects.

## Keeping lifecycle management in one place

Each runtime owns one transparent canvas and render loop, coordinating DOM measurement, scene projection, resource loading and caching, off-screen policy and cleanup. When an effect leaves the page or a component unmounts, its resources have an explicit disposal path.

For targets attached to the DOM, loading, error and off-screen states must also work with the visibility policy for the original content. This design allows text, images, video and 3D effects to coexist on a page while keeping the relationships between resources and states understandable.

## Using shared inputs for scrolling and interaction

Viselora provides progress signals, timelines and scroll adapters. It can follow native scrolling or integrate with Lenis, GSAP and ScrollTrigger. Multiple visual objects can use the same progress source to express stages such as approaching, rotating, unfolding, reading and retreating.

Pointer input is also managed by the runtime. Applications design feedback from pointer state on targets or scene objects, without maintaining another low-level picking system. Visual changes from frame to frame stay in effect logic, leaving components responsible for declarations and interface organization.

## Bringing the runtime into a real website

This personal website is one application of Viselora. A tetrahedron approaches as the page scrolls; content on its faces gradually aligns with the screen, then hands off to readable, interactive prose. The profile model, article sheets and project room continue to use the same public runtime capabilities.

The site owns web layout, links and mobile reading, while the runtime expresses 3D projection, materials and motion. The site is an independent project that installs published npm packages, putting the public interfaces to work in an actual application.

## Turning specific effects into reusable examples

The example application packages paper-card reading, a project room, model storytelling, face-projection transitions, pointer previews and a perspective timeline as reusable modules. They use neutral content and public APIs. Developers can read the module guides, replace the data and combine them in their own applications.

These modules are application-level examples whose visuals and content are organized by the caller. Runtime packages continue to provide general capabilities. API documentation, capability status records and agent-facing guidance help users distinguish public entry points, available evidence and their own application responsibilities.

## Current stage and scope

The project is in prerelease, with the core runtime and scroll adapters distributed separately through npm. The current implementation covers DOM and media targets, managed scenes, meshes, models, interaction, lighting, controlled material extensions and postprocessing. The maturity of verification varies across these capabilities.

Using this structure means letting the runtime manage rendering and resource lifecycles. Applications must supply semantic descriptions and fallback content for scene-native models and meshes, and physics support is limited in scope. Real-device behavior, complex-scene performance and final visual quality still need verification in each product.

## From web content to spatial expression

### Organize the DOM

Keep content, links, layout and reading order in semantic elements.

### Declare visual targets

Provide public declarations for text, media, meshes or models.

### Measure & project

Connect DOM geometry and scene coordinates through the runtime.

### Connect shared inputs

Use scroll progress, timelines and pointer state to drive effects.

### Render the scene

Apply materials, lighting and motion through managed effects and passes.

### Handle lifecycle

Coordinate visibility, loading, caching and resource cleanup.

## Explore the project

- [Source & project documentation](https://github.com/agenticnoob/dom-webgl-workspace)

[Contents](https://zzzxc.com/agent/en/index.md)