# Viselora DOM WebGL 让网页保留自己的结构，也拥有空间与运动。 面向 React 19 与 Next.js 的 DOM-first WebGL 协调运行时。以公开接口连接语义 DOM 和单一 React Three Fiber 场景，负责测量、共享进度与回退状态；渲染、材质、模型和运动由 R3F 与 Three.js 承担。 [网站原文](https://zzzxc.com/projects/viselora) ## 当网页内容进入三维画面 文字、图片、链接和阅读顺序原本由网页组织。当它们进入 WebGL 画面，布局、坐标、鼠标命中、滚动响应和资源释放也需要相互配合。每一种视觉效果单独维护这些关系，会让后续组合与修改越来越困难。 Viselora 从 DOM 出发：网页保留内容、布局与可访问性的基础，运行时把需要视觉表现的目标连接到 WebGL。0.2 版本收拢到 DOM 协调，让应用直接使用 R3F 组件表达场景，减少另一套渲染抽象。 ## 用声明连接内容与视觉 语义元素通过 WebGLTarget 注册，应用用 useDOMTarget 读取实时几何、可见性和内容版本。文字测量与纹理工具连接 DOM 排版；图片、视频与模型使用 Three.js、R3F 或 Drei 加载。 网页内容留在 children，原生 R3F 组件放入同一运行时的 scene。网格、材质、相机和灯光直接使用生态接口，逐帧变化在 useFrame 中完成；应用负责自身资源的创建与释放，不再经过旧版对象或材质 facade。 ## 把生命周期放在同一处 每个运行时承载一个 R3F Canvas，由 R3F 独占渲染与帧循环。Viselora 集中处理 DOM 测量、共享输入、离屏可见性和观察器清理；应用负责纹理、模型实例与材质等资源，共享加载缓存有单独的释放边界。 替代 DOM 绘制的视觉对象需要明确报告 readiness，并携带加载时捕获的目标身份，避免旧加载结果影响新节点。WebGL 不可用时恢复语义内容；离屏策略控制原内容的可见性，应用决定是否保留或卸载视觉资源。 ## 让滚动和交互成为共同输入 Viselora 提供进度信号、时间线与滚动适配能力，可以连接原生滚动，也可以接入 Lenis、GSAP 和 ScrollTrigger。多个视觉对象能够使用一致的进度来源，表达靠近、旋转、展开、阅读和退回等阶段。 三维命中和指针事件交给 R3F，普通链接与键盘操作仍使用 DOM 事件。应用负责交互优先级、触屏替代和减少动态效果；逐帧变化直接更新原生对象，不把每帧进度传入 React state。 ## 从运行时走到一个实际网站 这个个人网站是 Viselora 的实际应用之一。四面体随滚动靠近，面上的内容逐渐与屏幕对齐，再交给可阅读、可交互的正文；人物模型、文章纸卡和项目空间继续使用同一套公开运行时能力。 网页布局、链接与移动端阅读由站点负责，三维投影、材质和运动由同一场景中的原生 R3F 组件表达。站点作为独立项目安装已发布的 0.2 npm 包，让精简后的公共接口接受真实使用场景的检验。 ## 将具体效果整理成可复用示例 示例项目展示原生 R3F 场景与 DOM 目标、文字纹理、模型和滚动进度的组合。开发者可以阅读公开接口示例与迁移指引，再使用熟悉的 Three.js/R3F 生态组织自己的视觉组件。 这些模块属于应用层示例，视觉与内容由调用方组织；运行时包继续承担通用能力。接口文档、能力状态说明和面向 Agent 的使用指引，帮助使用者区分公开入口、实际证据与应用自己的责任。 ## 当前阶段与适用范围 项目处于 0.2.0-alpha.0 预发布阶段，核心运行时与滚动适配器分别通过 npm 提供。公开范围集中在单一 Canvas host、DOM 注册与测量、回退可见性、共享进度和文字纹理工具；场景、加载器、拾取、物理与后期处理使用 R3F/Three.js 生态。 当前版本要求 React 19、R3F 9 与 Three.js 0.184，不再支持框架无关调用或旧版托管 API。应用需要安排语义说明、回退内容和资源生命周期；真实设备表现、复杂场景性能和最终视觉效果仍需在具体产品中验证。 ## 从网页内容到空间表达 ### 组织 DOM 由语义元素保留内容、链接、布局与阅读顺序。 ### 声明视觉目标 注册需要视觉替代的语义 DOM 目标。 ### 测量与投影 运行时连接 DOM 几何与场景坐标。 ### 接入共同输入 以滚动进度、时间线与指针状态驱动效果。 ### 渲染画面 在原生 R3F 组件中表达材质、灯光和运动。 ### 管理生命周期 报告视觉就绪，并按资源归属处理缓存与清理。 ## 继续查看项目 - [源码与项目文档](https://github.com/agenticnoob/dom-webgl-workspace) [内容目录](https://zzzxc.com/agent/zh/index.md)