# Viselora DOM WebGL

让网页保留自己的结构，也拥有空间与运动。

面向 React 与浏览器应用的 DOM-first WebGL 运行时。保留网页的布局和交互语义，以公开声明连接文字、媒体和三维对象，统一管理渲染、资源、输入与生命周期。

[网站原文](https://zzzxc.com/projects/viselora)

## 当网页内容进入三维画面

文字、图片、链接和阅读顺序原本由网页组织。当它们进入 WebGL 画面，布局、坐标、鼠标命中、滚动响应和资源释放也需要相互配合。每一种视觉效果单独维护这些关系，会让后续组合与修改越来越困难。

Viselora 从 DOM 出发：网页保留内容、布局与可访问性的基础，运行时把需要视觉表现的目标连接到 WebGL。应用描述想呈现的对象与效果，底层统一处理渲染和资源生命周期。

## 用声明连接内容与视觉

DOM 文字、图片、视频、序列帧和模型可以成为运行时管理的视觉来源。应用通过目标声明提供来源与效果；需要程序化几何或场景原生模型时，则使用相应的网格与模型声明。

这让视觉表达有了清楚的入口：网页内容由语义元素承载，效果描述变换、材质或运动意图。更复杂的画面可以声明场景、相机、灯光和渲染通道，并通过受控接口更新对象。应用代码始终使用公开接口，底层对象的创建和销毁由运行时负责。

## 把生命周期放在同一处

每个运行时拥有一个透明画布和渲染循环，并集中处理 DOM 测量、场景投影、资源加载与缓存、离屏策略和清理。效果离开页面或组件卸载时，对应资源也有明确的释放路径。

对于依附 DOM 的目标，加载、错误和离屏状态还要与原内容的显示策略配合。这个设计的价值，在于让文字、图片、视频和三维效果能够组合在同一页面中，并保持可理解的资源与状态关系。

## 让滚动和交互成为共同输入

Viselora 提供进度信号、时间线与滚动适配能力，可以连接原生滚动，也可以接入 Lenis、GSAP 和 ScrollTrigger。多个视觉对象能够使用一致的进度来源，表达靠近、旋转、展开、阅读和退回等阶段。

指针输入同样进入运行时管理。应用通过目标或场景对象的指针状态设计反馈，无需自行维护另一套底层拾取工具。逐帧视觉变化在效果逻辑中完成，让组件继续承担声明与界面组织。

## 从运行时走到一个实际网站

这个个人网站是 Viselora 的实际应用之一。四面体随滚动靠近，面上的内容逐渐与屏幕对齐，再交给可阅读、可交互的正文；人物模型、文章纸卡和项目空间继续使用同一套公开运行时能力。

网页布局、链接与移动端阅读由站点负责，三维投影、材质和运动通过运行时表达。站点作为独立项目安装已发布的 npm 包，也让公共接口接受真实使用场景的检验。

## 将具体效果整理成可复用示例

示例项目进一步把纸卡阅读、项目空间、模型叙事、面投影转场、指针预览和透视时间线整理为可复用模块。它们使用中立内容和公开接口，开发者可以阅读模块说明、替换数据，再组合进自己的应用。

这些模块属于应用层示例，视觉与内容由调用方组织；运行时包继续承担通用能力。接口文档、能力状态说明和面向 Agent 的使用指引，帮助使用者区分公开入口、实际证据与应用自己的责任。

## 当前阶段与适用范围

项目处于预发布阶段，核心运行时与滚动适配器分别通过 npm 提供。当前实现覆盖 DOM 与媒体目标、托管场景、网格、模型、交互、灯光、受控材质扩展和后期处理，具体能力的验证成熟度并不完全相同。

使用这一结构需要接受运行时对渲染和资源生命周期的管理。场景原生模型与网格需要应用自行安排语义说明和回退内容，物理能力也只覆盖有限范围。真实设备表现、复杂场景性能和最终视觉效果，仍需要在具体产品中验证。

## 从网页内容到空间表达

### 组织 DOM

由语义元素保留内容、链接、布局与阅读顺序。

### 声明视觉目标

通过公开声明提供文字、媒体、网格或模型。

### 测量与投影

运行时连接 DOM 几何与场景坐标。

### 接入共同输入

以滚动进度、时间线与指针状态驱动效果。

### 渲染画面

在托管效果与通道中表达材质、灯光和运动。

### 管理生命周期

协调可见性、加载、缓存与资源清理。

## 继续查看项目

- [源码与项目文档](https://github.com/agenticnoob/dom-webgl-workspace)

[内容目录](https://zzzxc.com/agent/zh/index.md)