three-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b66b39cafbc0163bffb3b177eeaf1d397ac87fbed27046ca6f5673675fe001b9
+  data.tar.gz: 93dfc4ba66293d5090912b3082b2a84f87ba1d73d284606c9896d9a4b7f9d794
+SHA512:
+  metadata.gz: 14776a59074de5a790244fc27c698988e7b98fb5c54abd7c8837368d8b029c1a5f3410814377aab663f466aa4e619228622590804d4b9fd261e9ced68877ce0d
+  data.tar.gz: 8292752e152f1aa24751e5b2b7468ca641c0beaaa36c17cfc8439466408214b7fca6fae65b3e0e8226c679586fd0aa532140b6d06fa22eda0205f7abbd57699a

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 - 2026-05-15
+
+### Added
+
+- Ruby scene graph, math primitives, cameras, lights, geometries, textures, layers, raycasting helpers, and JSON export/load.
+- Mesh, instanced mesh, line, points, and sprite object support.
+- Common material APIs including basic, Lambert, Phong, standard, physical, matcap, toon, normal, shadow, line, points, and sprite materials.
+- Browser rendering through ruby.wasm and a delegated three.js backend.
+- Browser examples and Playwright smoke tests for cube, composition, textures, cubemap, glTF/DRACO, serialization, picking, primitives, and postprocessing.
+- Texture loading, cube textures, RGBE environment textures, glTF loading, DRACO decoder configuration, animation mixers, OrbitControls, instancing, picking, shadows, and loaded-asset traversal/disposal helpers.
+- Initial postprocessing wrappers for `EffectComposer`, `RenderPass`, `UnrealBloomPass`, `DotScreenPass`, and `OutputPass`.
+- Deterministic JSON fixture regression coverage for exporter/loader compatibility.
+- Release install smoke and preflight tasks for validating the built gem outside the repository load path.
+
+### Notes
+
+- The first release is browser-first alpha quality. Native rendering, full three.js compatibility, broad addon coverage, WebGPU, and XR are intentionally outside the initial public scope.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LEF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# three-rb
+
+Ruby 3D Library.
+
+Published to RubyGems as `three-rb`; require it in Ruby as `three`.
+
+## Status
+
+This project is in browser-first alpha. The current code covers the gem foundation, math primitives, scene graph basics, geometry/material objects, dirty-tracked backend sync, JSON export/load, browser examples, and a three.js backend/renderer bridge through ruby.wasm.
+
+## Browser-first alpha scope
+
+Supported scope for the first public release:
+
+- Pure Ruby scene construction, math, cameras, lights, geometry, materials, textures, layers, raycasting helpers, and JSON export/load.
+- Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and pnpm-managed `three@0.184.0`.
+- JavaScript-delegated browser features for texture loading, cube/RGBE textures, glTF/DRACO loading, OrbitControls, animation mixers, instancing, picking, shadows, and an initial postprocessing pipeline.
+
+Out of scope for the first public release:
+
+- A Ruby-native OpenGL/Vulkan/software renderer.
+- Full three.js API compatibility.
+- Stable APIs for every addon loader, render target, postprocessing pass, WebGPU, or XR workflow.
+
+## Installation
+
+After a release is published:
+
+```sh
+gem install three-rb
+```
+
+Or add it to a Gemfile:
+
+```ruby
+gem "three-rb", "~> 0.1"
+```
+
+## Quick Start
+
+```ruby
+require "three"
+
+scene = Three::Scene.new
+camera = Three::PerspectiveCamera.new(75, aspect: 16.0 / 9.0)
+camera.position.z = 5
+
+geometry = Three::BoxGeometry.new(1, 1, 1)
+material = Three::MeshBasicMaterial.new(color: 0x00ff00)
+cube = Three::Mesh.new(geometry, material)
+
+scene.add(cube)
+```
+
+Browser rendering is available through `Three::Renderers::ThreeJSRenderer`, which targets three.js from ruby.wasm.
+
+## Browser Example
+
+Install browser dependencies, serve the repository root, and open one of the browser examples:
+
+```sh
+pnpm install
+ruby -run -e httpd . -p 8000
+```
+
+```text
+http://localhost:8000/examples/browser/cube/
+http://localhost:8000/examples/browser/composition/
+http://localhost:8000/examples/browser/textures/
+http://localhost:8000/examples/browser/cubemap/
+http://localhost:8000/examples/browser/gltf/
+http://localhost:8000/examples/browser/serialization/
+http://localhost:8000/examples/browser/picking/
+http://localhost:8000/examples/browser/primitives/
+http://localhost:8000/examples/browser/postprocessing/
+```
+
+See [Browser Examples](examples/browser/README.md) for the feature coverage map and per-example smoke commands. See [Browser Runtime](docs/browser-runtime.md) for the current embedding and boot contract.
+
+The examples load pnpm-managed browser packages from `node_modules/`: `@ruby/3.4-wasm-wasi@2.9.4-2026-05-11-a`, `@ruby/wasm-wasi@2.9.4-2026-05-11-a`, and `three@0.184.0`.
+
+Run the optional browser smoke tests:
+
+```sh
+pnpm install
+pnpm exec playwright install chromium
+pnpm test:browser
+```
+
+Run the optional browser sync benchmarks:
+
+```sh
+pnpm benchmark:browser
+pnpm benchmark:browser:mesh-sync
+pnpm benchmark:browser:instanced-mesh-sync
+```
+
+## Development
+
+Install dependencies:
+
+```sh
+bundle install
+```
+
+Run tests:
+
+```sh
+bundle exec rake test
+```
+
+Build and install the gem into a temporary `GEM_HOME`, then run the install smoke test:
+
+```sh
+bundle exec rake release:gem_smoke
+```
+
+Export a Ruby-authored scene to a deterministic JSON-friendly hash:
+
+```ruby
+exported = Three::Exporters::ThreeJSONExporter.new.export(scene)
+fixture = Three::Exporters::ThreeJSONExporter.new(deterministic_ids: true).export(scene)
+json = scene.to_json
+loaded_scene = Three::Loaders::ThreeJSONLoader.new.parse(json)
+```
+
+Run the local release preflight check:
+
+```sh
+pnpm install
+pnpm exec playwright install chromium
+bundle exec rake release:preflight
+```
+
+Run the full local CI-equivalent check, including dependency audits:
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm audit --audit-level moderate
+pnpm audit signatures
+pnpm exec playwright install chromium
+bundle exec rake release:preflight
+```
+
+## Documents
+
+- [Implementation Plan](docs/implementation-plan.md)
+- [Next Work](docs/next-work.md)
+- [Browser Runtime](docs/browser-runtime.md)
+- [Browser Examples](examples/browser/README.md)
+- [Loaded Asset Traversal and Disposal Design](docs/loaded-assets-design.md)
+- [Release Readiness](docs/release-readiness.md)
+- [Publishing](docs/publishing.md)

data/docs/browser-runtime.md

@@ -0,0 +1,153 @@
+# Browser Runtime
+
+This guide describes the current browser runtime shape for embedding three-rb outside the repository examples. The browser runtime is still browser-first alpha: Ruby builds the scene graph, ruby.wasm runs the Ruby code, and pnpm-managed three.js modules do the actual WebGL rendering.
+
+For the example coverage map and per-example smoke commands, see `examples/browser/README.md`.
+
+## Runtime Shape
+
+A browser page using three-rb needs four pieces:
+
+1. An HTTP-served page with a canvas element.
+2. An import map or bundler setup that resolves ruby.wasm, three.js, and three.js addon modules.
+3. A JavaScript boot module that exposes the required three.js constructors to Ruby and starts ruby.wasm.
+4. A Ruby entrypoint that waits for three.js, requires `three`, creates a scene, and renders through `Three::Renderers::ThreeJSRenderer`.
+
+Do not use `file://` for browser runs. The examples assume an HTTP server because browser module loading, wasm loading, and asset loading all need stable URL resolution.
+
+## Browser Dependencies
+
+The runtime currently follows the pinned versions in `package.json`:
+
+- `@bjorn3/browser_wasi_shim@0.4.2`
+- `@ruby/3.4-wasm-wasi@2.9.4-2026-05-11-a`
+- `@ruby/wasm-wasi@2.9.4-2026-05-11-a`
+- `three@0.184.0`
+
+Install them from the repository root with:
+
+```sh
+pnpm install
+```
+
+Keep these pins synchronized with browser smoke coverage. The public Ruby API and the JavaScript delegated backend are coupled closely enough that dependency drift should go through `pnpm test:browser` before release work.
+
+## HTML Requirements
+
+The page needs a canvas that Ruby can select:
+
+```html
+<canvas id="scene"></canvas>
+```
+
+When using import maps like the examples, the page also needs mappings for ruby.wasm, three.js, and three.js addons:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@bjorn3/browser_wasi_shim": "/node_modules/@bjorn3/browser_wasi_shim/dist/index.js",
+      "@ruby/wasm-wasi/browser": "/node_modules/@ruby/wasm-wasi/dist/esm/browser.js",
+      "three": "/node_modules/three/build/three.module.js",
+      "three/addons/": "/node_modules/three/examples/jsm/"
+    }
+  }
+</script>
+```
+
+Applications can use a bundler instead of an import map, but the same modules and addon paths must be available to the JavaScript boot module.
+
+## JavaScript Boot Contract
+
+Use `examples/browser/shared/boot.mjs` as the reference implementation. Example-local boot files are intentionally small; they pass the Ruby entrypoint and clear color into the shared boot helper.
+
+The boot module is responsible for:
+
+- Importing `DefaultRubyVM` from `@ruby/wasm-wasi/browser`.
+- Importing `three` and any addon constructors used by Ruby.
+- Assigning `globalThis.THREE` before Ruby creates `Three::Renderers::ThreeJSRenderer`.
+- Assigning addon constructors before Ruby calls addon wrappers:
+  - `globalThis.THREE_GLTF_LOADER`
+  - `globalThis.THREE_DRACO_LOADER`
+  - `globalThis.THREE_RGBE_LOADER`
+  - `globalThis.THREE_ORBIT_CONTROLS`
+  - `globalThis.THREE_EFFECT_COMPOSER`
+  - `globalThis.THREE_RENDER_PASS`
+  - `globalThis.THREE_UNREAL_BLOOM_PASS`
+  - `globalThis.THREE_DOT_SCREEN_PASS`
+  - `globalThis.THREE_OUTPUT_PASS`
+- Setting `globalThis.__threeReady` to a promise Ruby can wait on.
+- Loading `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm`.
+- Starting the Ruby VM and loading the Ruby entrypoint through `JS::RequireRemote`.
+
+The shared helper also installs optional render helpers used by smoke tests to draw immediately from Ruby renderer calls and expose render counters for deterministic assertions. Custom applications can keep that behavior or call directly into three.js through the renderer backend fallback.
+
+Write a custom boot module when the application has different asset paths, a bundler output path, a smaller addon set, a custom status/error UI, or a deployment layout that does not match the repository root. Keep the same global constructor contract unless the Ruby backend gains a different injection API.
+
+## Ruby Entrypoint
+
+The Ruby side should wait for the JavaScript boot module, require the library, create a scene, and attach the renderer to the existing canvas:
+
+```ruby
+require "js"
+
+JS.global[:__threeReady].await
+
+require_relative "../../../lib/three"
+
+scene = Three::Scene.new
+camera = Three::PerspectiveCamera.new(70, aspect: 1.0, near: 0.1, far: 100)
+camera.position.z = 3
+
+mesh = Three::Mesh.new(
+  Three::BoxGeometry.new(1, 1, 1),
+  Three::MeshBasicMaterial.new(color: 0x4ed08f)
+)
+scene.add(mesh)
+
+renderer = Three::Renderers::ThreeJSRenderer.new(
+  canvas: "#scene",
+  antialias: true,
+  alpha: false
+)
+
+renderer.set_size(640, 480)
+renderer.render(scene, camera)
+```
+
+`canvas:` may be a CSS selector string or a JavaScript canvas object. Selector strings are resolved with `document.querySelector`.
+
+For responsive layouts, follow the browser examples: read the containing element's client width and height, update the camera aspect/projection matrix, call `renderer.set_size(width, height)`, and listen for `resize`.
+
+For animation, call `renderer.animation_loop`:
+
+```ruby
+renderer.animation_loop do
+  mesh.rotation.x += 0.01
+  mesh.rotation.y += 0.015
+  renderer.render(scene, camera)
+end
+```
+
+For postprocessing, render through `composer.render(scene, camera)` instead of `renderer.render(scene, camera)` after configuring `Three::Postprocessing::EffectComposer` and its passes.
+
+## Current Limits
+
+The browser runtime intentionally does not promise full three.js compatibility yet.
+
+- There is no Ruby-native OpenGL, Vulkan, WebGPU, or software renderer.
+- Rendering is delegated to three.js through ruby.wasm.
+- Addon wrappers only work when their JavaScript constructors are registered on `globalThis`.
+- The first public scope does not include stable APIs for every loader, material, render target, postprocessing pass, WebGPU, or XR workflow.
+- `examples/browser/shared/boot.mjs` is a reference implementation for this repository's examples, not a separate stable package.
+- `preserveDrawingBuffer: true` is useful for deterministic canvas smoke tests, but applications do not need it by default.
+
+## Verification
+
+Use the browser examples as executable documentation:
+
+```sh
+pnpm test:browser
+```
+
+Before release work, run the release gates documented in `docs/release-readiness.md` and the publishing checklist in `docs/publishing.md`. Browser boot changes should go through `bundle exec rake release:preflight` because that includes the Ruby tests, gem install smoke, and browser smoke tests.