three-rb 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +38 -2
  3. data/README.md +14 -6
  4. data/docs/browser-runtime.md +10 -6
  5. data/docs/cloudflare-pages.md +205 -0
  6. data/docs/implementation-plan.md +6 -4
  7. data/docs/loaded-assets-design.md +1 -1
  8. data/docs/next-work.md +26 -25
  9. data/docs/publishing.md +4 -1
  10. data/docs/release-readiness.md +11 -11
  11. data/docs/standalone-browser-app.md +8 -2
  12. data/examples/browser/README.md +5 -1
  13. data/examples/browser/composition/index.html +65 -4
  14. data/examples/browser/composition/main.rb +2 -2
  15. data/examples/browser/cube/README.md +3 -3
  16. data/examples/browser/cube/index.html +61 -6
  17. data/examples/browser/cubemap/assets/checker.svg +11 -0
  18. data/examples/browser/cubemap/index.html +60 -5
  19. data/examples/browser/cubemap/main.rb +1 -1
  20. data/examples/browser/dango/README.md +26 -0
  21. data/examples/browser/dango/boot.mjs +6 -0
  22. data/examples/browser/dango/index.html +197 -0
  23. data/examples/browser/dango/main.rb +278 -0
  24. data/examples/browser/dango/smoke_test.mjs +232 -0
  25. data/examples/browser/gltf/index.html +60 -5
  26. data/examples/browser/gltf/main.rb +2 -2
  27. data/examples/browser/picking/index.html +61 -6
  28. data/examples/browser/postprocessing/index.html +61 -6
  29. data/examples/browser/primitives/assets/checker.svg +11 -0
  30. data/examples/browser/primitives/index.html +61 -6
  31. data/examples/browser/primitives/main.rb +1 -1
  32. data/examples/browser/ruby/README.md +2 -0
  33. data/examples/browser/ruby/assets/helvetiker_regular.typeface.json +1 -0
  34. data/examples/browser/ruby/index.html +112 -8
  35. data/examples/browser/ruby/main.rb +2 -6
  36. data/examples/browser/serialization/assets/checker.svg +11 -0
  37. data/examples/browser/serialization/index.html +61 -6
  38. data/examples/browser/serialization/main.rb +1 -1
  39. data/examples/browser/shared/boot.mjs +116 -14
  40. data/examples/browser/shared/config.mjs +3 -0
  41. data/examples/browser/shared/smoke_test_helpers.mjs +13 -8
  42. data/examples/browser/textures/assets/checker.svg +11 -0
  43. data/examples/browser/textures/index.html +61 -6
  44. data/examples/browser/textures/main.rb +2 -2
  45. data/exe/three-rb +1 -0
  46. data/lib/three/backends/threejs/parameters.rb +4 -1
  47. data/lib/three/backends/threejs/ruby_wasm_adapter.rb +8 -2
  48. data/lib/three/generators/browser_example.rb +220 -12
  49. data/lib/three/version.rb +1 -1
  50. data/package.json +9 -5
  51. data/pnpm-lock.yaml +1235 -31
  52. metadata +19 -7
  53. /data/examples/browser/{assets → composition/assets}/checker.svg +0 -0
  54. /data/examples/browser/{assets → gltf/assets}/animated_triangle.gltf +0 -0
  55. /data/examples/browser/{assets → gltf/assets}/compressed_triangle.gltf +0 -0
  56. /data/examples/browser/{assets → gltf/assets}/triangle.gltf +0 -0
  57. /data/examples/browser/{assets → textures/assets}/studio.hdr +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ab46f2291f0b0adcb818d9a079c341333adeec066588ed09e8c189b798819725
4
- data.tar.gz: 3ca4184c327a2abf28dc6b081a5f0e4df8b31a183942ed82da94103146ef3922
3
+ metadata.gz: 3b2c30088eb50ea175bcfb1acff5671557efaec52ef06d8a8f262ee89a89d386
4
+ data.tar.gz: ca52f61e2113f82bc752801e48fcb80ddf8f128b48c9ff6b8b9e2f001ae82805
5
5
  SHA512:
6
- metadata.gz: e2c3710079194f6860b05827679bb8e5797b52164e33016f2dcf95feabffd22da475edd2640e6f76e854606785be92c27772c679b969f73808ac0821b5b8b7ea
7
- data.tar.gz: 9edb5c3dac961c7798e45e9901f408a3896c36e7db50ddedc1cd439ec7d3e5d54fdbeface42df108f679517fed14d81e23fe9e0d0730b24147ee37aecd430f82
6
+ metadata.gz: b0f152273904c156e653278e7d90cc9809bc3e064cd2e58f7866aedf04a7a6578775ce6f3cec3c67d687b13137ecfaf8eeee9d0889a0476cddf4b1908bd2e8ee
7
+ data.tar.gz: 12cd57afccf132fcf8e413a8c251eba6f6821a8087adb40ff96c7faa8fffbce0005a09d35072297aa51aa0eae8cad801875dab7c543614fa85e60a292c0575c9
data/CHANGELOG.md CHANGED
@@ -1,5 +1,42 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0 - 2026-11-20
4
+
5
+ ### Added
6
+
7
+ - Added a dango browser example that builds a three-color dango from primitive meshes with lighting, shadows, and `OrbitControls`.
8
+ - Added a Cloudflare Pages deployment guide. In a repository checkout, `pnpm build:pages:ruby` builds a static `dist/` for the Ruby gemstone example. It bundles the Ruby entrypoint into one file, serves the browser packages under `/vendor/`, and loads ruby.wasm from jsDelivr, because the file is over the Pages 25 MiB asset limit.
9
+ - Added `examples/browser/shared/config.mjs`, which sets the URL the shared boot loads ruby.wasm from. It defaults to the local `node_modules` copy, and `globalThis.__threeRbRubyWasmUrl` overrides it. `three-rb browser` copies it into generated apps and keeps an existing copy even with `--force`.
10
+ - Browser examples and generated apps show a progress bar while ruby.wasm downloads and compiles, and suggest reloading if the page is still loading after 15 seconds.
11
+
12
+ ### Changed
13
+
14
+ - three-rb now requires Ruby 3.3 or later. Ruby 3.2 reached end of life on 2026-03-31. CI now also runs the Ruby tests on 3.3 and 4.0.
15
+ - Updated the pinned ruby.wasm packages, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi`, from a 2.9.4 nightly build to the 2.10.1 release.
16
+ - Updated the pinned three.js to 0.187.0 (r187). `MeshPhysicalMaterial#iridescence_thickness_range` is now sent to three.js as `iridescenceThicknessMinimum` and `iridescenceThicknessMaximum`, which require r187 or later.
17
+ - The Ruby gemstone and dango examples now request `PCFShadowMap`. three.js had already been rendering them with it in place of the deprecated `PCFSoftShadowMap`, which r187 removes.
18
+ - Removed the HDR environment from the Ruby gemstone example and its generated template. The bundled `studio.hdr` was a 2x2 uniform gray image that three.js r186 and earlier never applied, so the gem never showed it; from r187 on it only washed the gem out.
19
+ - `three-rb browser` now writes a `package.json` that lists only the browser runtime packages, and a `pnpm-lock.yaml` cut down to match, instead of copying the gem's own files with its test tooling and scripts. An existing `package.json` is kept, and no lockfile is written next to it.
20
+ - The shared boot aborts a ruby.wasm download that makes no progress for 20 seconds and retries it up to three times. It now chooses between `WebAssembly.compileStreaming` and `WebAssembly.compile` from the response's content type, instead of downloading the file again after a failed streaming compile.
21
+ - The browser smoke tests now generate apps with `three-rb browser`, install them with `pnpm install --frozen-lockfile`, and render them. They also fail on three.js console warnings.
22
+
23
+ ### Fixed
24
+
25
+ - Textures from `TextureLoader` and the other loaders no longer make three.js warn "Texture marked for update but no image data found" on every frame until their image arrives.
26
+ - `MeshToonMaterial` no longer makes three.js warn that `flatShading` is not a property. `flat_shading` still takes effect.
27
+
28
+ ## 0.2.1 - 2026-05-17
29
+
30
+ ### Added
31
+
32
+ - Added a generated Ruby browser example template that copies the full gemstone example, including its local HDR asset.
33
+ - Added generator coverage for Ruby example asset copying and Ruby-only browser entrypoints.
34
+
35
+ ### Changed
36
+
37
+ - Moved browser example assets into example-local asset directories so generated examples and smoke tests use self-contained paths.
38
+ - Strengthened release readiness checks for the browser generator template and installed executable.
39
+
3
40
  ## 0.2.0 - 2026-05-17
4
41
 
5
42
  ### Added
@@ -27,12 +64,11 @@
27
64
  - Mesh, instanced mesh, line, points, and sprite object support.
28
65
  - Common material APIs including basic, Lambert, Phong, standard, physical, matcap, toon, normal, shadow, line, points, and sprite materials.
29
66
  - Browser rendering through ruby.wasm and a delegated three.js backend.
30
- - `Three::Browser` helpers and a `three-rb browser` generator for Ruby-only browser entrypoints that avoid application-level `require "js"` and `JS.global` calls.
31
67
  - Browser examples and Playwright smoke tests for cube, composition, textures, cubemap, glTF/DRACO, serialization, picking, primitives, and postprocessing.
32
68
  - Texture loading, cube textures, RGBE environment textures, glTF loading, DRACO decoder configuration, animation mixers, OrbitControls, instancing, picking, shadows, and loaded-asset traversal/disposal helpers.
33
69
  - Initial postprocessing wrappers for `EffectComposer`, `RenderPass`, `UnrealBloomPass`, `DotScreenPass`, and `OutputPass`.
34
70
  - Deterministic JSON fixture regression coverage for exporter/loader compatibility.
35
- - Release install smoke and preflight tasks for validating the built gem, installed executable, and generated browser app outside the repository load path.
71
+ - Release install smoke and preflight tasks for validating the built gem outside the repository load path.
36
72
 
37
73
  ### Notes
38
74
 
data/README.md CHANGED
@@ -4,19 +4,23 @@ Ruby 3D Library.
4
4
 
5
5
  Published to RubyGems as `three-rb`; require it in Ruby as `three`.
6
6
 
7
+ ![three-rb](https://github.com/user-attachments/assets/150a3639-459d-4836-bbde-411eef146c61)
8
+
9
+ YouTube Demo: https://youtu.be/6JTtSg1pRp0
10
+
7
11
  ## Status
8
12
 
9
13
  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.
10
14
 
11
15
  ## Browser-first alpha scope
12
16
 
13
- Supported scope for the first public release:
17
+ Supported scope for the alpha releases:
14
18
 
15
19
  - Pure Ruby scene construction, math, cameras, lights, geometry, materials, textures, layers, raycasting helpers, and JSON export/load.
16
- - Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and pnpm-managed `three@0.184.0`.
20
+ - Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and pnpm-managed `three@0.187.0`.
17
21
  - JavaScript-delegated browser features for texture loading, cube/RGBE textures, glTF/DRACO loading, OrbitControls, animation mixers, instancing, picking, shadows, and an initial postprocessing pipeline.
18
22
 
19
- Out of scope for the first public release:
23
+ Out of scope for the alpha releases:
20
24
 
21
25
  - A Ruby-native OpenGL/Vulkan/software renderer.
22
26
  - Full three.js API compatibility.
@@ -60,7 +64,7 @@ http://localhost:8000/examples/browser/ruby/
60
64
 
61
65
  This page runs the Ruby entrypoint at `examples/browser/ruby/main.rb` through ruby.wasm and renders a transparent red gemstone and extruded `three-rb` title with three.js. Use `http://localhost:8000/...`; do not open the files with `file://`, because the browser runtime loads ES modules, wasm, and assets over HTTP.
62
66
 
63
- After the ruby example works, inspect `examples/browser/ruby/main.rb` to see the Ruby scene code. For the smallest possible browser scene, see `examples/browser/cube/main.rb`. For a standalone app directory with your own Ruby entrypoint, see [Standalone Browser App](docs/standalone-browser-app.md).
67
+ After the ruby example works, inspect `examples/browser/ruby/main.rb` to see the Ruby scene code. For the smallest possible browser scene, see `examples/browser/cube/main.rb`. For a standalone app directory with your own Ruby entrypoint, see [Standalone Browser App](docs/standalone-browser-app.md). For Cloudflare Pages deployment, see [Cloudflare Pages Deployment](docs/cloudflare-pages.md).
64
68
 
65
69
  ## Plain Ruby Check
66
70
 
@@ -94,7 +98,7 @@ ruby hello_three.rb
94
98
  You should see the library load and create Ruby scene objects:
95
99
 
96
100
  ```text
97
- three-rb 0.1.0
101
+ three-rb 0.3.0
98
102
  Three::Scene
99
103
  Three::Mesh
100
104
  ```
@@ -115,6 +119,7 @@ If `ruby -run -e httpd` reports that `webrick` is not found, run `gem install we
115
119
  ```text
116
120
  http://localhost:8000/examples/browser/ruby/
117
121
  http://localhost:8000/examples/browser/cube/
122
+ http://localhost:8000/examples/browser/dango/
118
123
  http://localhost:8000/examples/browser/composition/
119
124
  http://localhost:8000/examples/browser/textures/
120
125
  http://localhost:8000/examples/browser/cubemap/
@@ -127,7 +132,7 @@ http://localhost:8000/examples/browser/postprocessing/
127
132
 
128
133
  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.
129
134
 
130
- 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`.
135
+ The examples load pnpm-managed browser packages from `node_modules/`: `@ruby/3.4-wasm-wasi@2.10.1`, `@ruby/wasm-wasi@2.10.1`, and `three@0.187.0`.
131
136
 
132
137
  To start a standalone browser app from the installed gem:
133
138
 
@@ -137,6 +142,8 @@ pnpm install
137
142
  ruby -run -e httpd . -p 8000
138
143
  ```
139
144
 
145
+ Use `three-rb browser examples/browser/ruby` instead when you want the richer Ruby gemstone sample with its assets kept under `examples/browser/ruby/assets/`.
146
+
140
147
  The generated Ruby entrypoint uses `Three::Browser.run`, so ordinary scene code does not need `require "js"` or `JS.global`.
141
148
 
142
149
  Run the optional browser smoke tests:
@@ -209,6 +216,7 @@ bundle exec rake release:preflight
209
216
  - [Browser Runtime](docs/browser-runtime.md)
210
217
  - [Browser Examples](examples/browser/README.md)
211
218
  - [Standalone Browser App](docs/standalone-browser-app.md)
219
+ - [Cloudflare Pages Deployment](docs/cloudflare-pages.md)
212
220
  - [Loaded Asset Traversal and Disposal Design](docs/loaded-assets-design.md)
213
221
  - [Release Readiness](docs/release-readiness.md)
214
222
  - [Publishing](docs/publishing.md)
@@ -20,9 +20,9 @@ Do not use `file://` for browser runs. The examples assume an HTTP server becaus
20
20
  The runtime currently follows the pinned versions in `package.json`:
21
21
 
22
22
  - `@bjorn3/browser_wasi_shim@0.4.2`
23
- - `@ruby/3.4-wasm-wasi@2.9.4-2026-05-11-a`
24
- - `@ruby/wasm-wasi@2.9.4-2026-05-11-a`
25
- - `three@0.184.0`
23
+ - `@ruby/3.4-wasm-wasi@2.10.1`
24
+ - `@ruby/wasm-wasi@2.10.1`
25
+ - `three@0.187.0`
26
26
 
27
27
  Install them from the repository root with:
28
28
 
@@ -70,6 +70,8 @@ The boot module is responsible for:
70
70
  - `globalThis.THREE_GLTF_LOADER`
71
71
  - `globalThis.THREE_DRACO_LOADER`
72
72
  - `globalThis.THREE_RGBE_LOADER`
73
+ - `globalThis.THREE_FONT_LOADER`
74
+ - `globalThis.THREE_TEXT_GEOMETRY`
73
75
  - `globalThis.THREE_ORBIT_CONTROLS`
74
76
  - `globalThis.THREE_EFFECT_COMPOSER`
75
77
  - `globalThis.THREE_RENDER_PASS`
@@ -77,7 +79,7 @@ The boot module is responsible for:
77
79
  - `globalThis.THREE_DOT_SCREEN_PASS`
78
80
  - `globalThis.THREE_OUTPUT_PASS`
79
81
  - Setting `globalThis.__threeReady` to a promise Ruby can wait on.
80
- - Loading `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm`.
82
+ - Loading ruby.wasm from the URL exported by `examples/browser/shared/config.mjs`. It defaults to `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm`; set `globalThis.__threeRbRubyWasmUrl` before the boot module loads, or edit `config.mjs`, to load it from another host.
81
83
  - Starting the Ruby VM and loading the Ruby entrypoint through `JS::RequireRemote`.
82
84
 
83
85
  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.
@@ -183,7 +185,9 @@ For standalone projects, install the gem and generate a Ruby-only browser exampl
183
185
  three-rb browser examples/browser/quickstart
184
186
  ```
185
187
 
186
- The generator copies the browser runtime files, `package.json`, `pnpm-lock.yaml`, and `lib/` into the served project root, then creates `index.html`, `boot.mjs`, `main.rb`, and `README.md` for the example.
188
+ `quickstart` generates an asset-free rotating cube. Use `three-rb browser examples/browser/ruby` to generate the richer Ruby gemstone sample; its title font is copied under `examples/browser/ruby/assets/`.
189
+
190
+ The generator writes a `package.json` and `pnpm-lock.yaml` that list only the browser runtime packages, and copies the browser runtime files and `lib/` into the served project root, then creates `index.html`, `boot.mjs`, `main.rb`, and `README.md` for the example. Templates that need local files keep them under the generated example's `assets/` directory.
187
191
 
188
192
  ## JavaScript Escape Hatch
189
193
 
@@ -204,7 +208,7 @@ The browser runtime intentionally does not promise full three.js compatibility y
204
208
  - Rendering is delegated to three.js through ruby.wasm.
205
209
  - Addon wrappers only work when their JavaScript constructors are registered on `globalThis`.
206
210
  - The JavaScript boot module is still required to import ES modules and start ruby.wasm, even though ordinary Ruby scene entrypoints can stay Ruby-only.
207
- - The first public scope does not include stable APIs for every loader, material, render target, postprocessing pass, WebGPU, or XR workflow.
211
+ - The alpha scope does not include stable APIs for every loader, material, render target, postprocessing pass, WebGPU, or XR workflow.
208
212
  - `examples/browser/shared/boot.mjs` is a reference implementation for this repository's examples, not a separate stable package.
209
213
  - `preserveDrawingBuffer: true` is useful for deterministic canvas smoke tests, but applications do not need it by default.
210
214
 
@@ -0,0 +1,205 @@
1
+ # Cloudflare Pages Deployment
2
+
3
+ This guide shows how to deploy a three-rb browser example to Cloudflare Pages.
4
+
5
+ Cloudflare Pages does not run the example's Ruby code on the server. Pages serves static files, the browser downloads ruby.wasm, and ruby.wasm runs the Ruby entrypoint in the user's browser.
6
+
7
+ The build scripts under `scripts/` belong to the three-rb repository and are not included in the gem, so run these steps from a clone of the repository.
8
+
9
+ ## What Must Be Deployed
10
+
11
+ The current browser examples use root-relative URLs. The deployed output must preserve these paths:
12
+
13
+ - `/examples/browser/ruby/` for the Ruby gemstone example page, boot file, Ruby entrypoint, and local assets.
14
+ - `/examples/browser/shared/` for the shared JavaScript boot runtime.
15
+ - `/vendor/@ruby/wasm-wasi/` for the browser Ruby VM JavaScript package.
16
+ - `/vendor/@bjorn3/browser_wasi_shim/` for WASI browser support.
17
+ - `/vendor/three/` for three.js and its addons.
18
+ - `/` for the public demo entrypoint generated from the Ruby example page.
19
+
20
+ `/lib` is not deployed. The build script bundles the Ruby entrypoint and everything it reaches through `require_relative` into a single `dist/examples/browser/ruby/main.rb`, so the browser Ruby VM fetches one file instead of one per source file. See "Bundled Ruby Source" below.
21
+
22
+ Do not set `examples/browser/ruby` itself as the Cloudflare Pages output directory. That directory alone does not contain `/examples/browser/shared` or the required browser packages.
23
+
24
+ Cloudflare Pages has a 25 MiB maximum size for each static asset. The current `ruby+stdlib.wasm` file is larger than that limit, so the Pages build script does not upload it as a Pages asset. Instead, the generated `dist/examples/browser/shared/config.mjs` points at a CDN URL for the pinned `@ruby/3.4-wasm-wasi` package by default. If you prefer to own that asset, upload `node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm` to Cloudflare R2 or another static host that supports large files and set `RUBY_WASM_URL` to that public URL in the Pages environment.
25
+
26
+ Do not point `RUBY_WASM_URL` at an R2 `pub-*.r2.dev` URL. That endpoint is rate limited, is documented as development-only, and is not served through the Cloudflare CDN cache, so every visitor downloads the full 30 MB from the bucket itself. Attach a custom domain to the bucket, or serve it from a Worker, so the file is cached at the edge.
27
+
28
+ The Pages build script copies browser packages under `/vendor/` instead of `/node_modules/`. This avoids Pages deployments that omit or fail to serve `node_modules` paths, and keeps the deployed URLs separate from package-manager internals.
29
+
30
+ ## Local Verification
31
+
32
+ Install the browser dependencies and run the existing smoke test:
33
+
34
+ ```sh
35
+ pnpm install
36
+ pnpm test:browser:ruby
37
+ ```
38
+
39
+ The smoke test starts a local static HTTP server and verifies that the Ruby VM boots, the Ruby scene loads, and three.js renders visible pixels. Use `http://...` URLs for manual testing; `file://` will not work because the runtime fetches ES modules, wasm, Ruby files, and assets.
40
+
41
+ ## Recommended Output Directory
42
+
43
+ Create a deployment directory that contains only the static files required by the example:
44
+
45
+ ```sh
46
+ pnpm run build:pages:ruby
47
+ ```
48
+
49
+ This script rebuilds `dist/` from scratch, copies the Ruby example, shared browser boot runtime, and required browser packages, and bundles the Ruby entrypoint. It also generates `dist/index.html` and `dist/boot.mjs` so the public Pages root URL runs the Ruby example directly. It uses `cp -RL` for packages copied from local `node_modules` so pnpm symlinks are resolved into real files, then deploys those package files under `/vendor/`. Cloudflare Pages uploads the output directory contents, and a copied symlink to `.pnpm/...` will not work unless the referenced package store is also present in the deployment.
50
+
51
+ By default, the script writes a Pages-specific wasm URL into `dist/examples/browser/shared/config.mjs`, pinned to the `@ruby/3.4-wasm-wasi` version in `package.json`:
52
+
53
+ ```text
54
+ https://cdn.jsdelivr.net/npm/@ruby/3.4-wasm-wasi@<version>/dist/ruby+stdlib.wasm
55
+ ```
56
+
57
+ The build fails if `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are on different versions, because the wasm binary and the JavaScript glue that loads it must match.
58
+
59
+ To use an R2-hosted copy or another large-file host, set `RUBY_WASM_URL` before the build command.
60
+
61
+ Run the same shape locally before deploying:
62
+
63
+ ```sh
64
+ ruby -run -e httpd dist -p 8000
65
+ ```
66
+
67
+ Open:
68
+
69
+ ```text
70
+ http://localhost:8000/
71
+ ```
72
+
73
+ If you rebuild `dist/` locally, start from an empty output directory so stale files do not hide missing copy steps.
74
+
75
+ ## Bundled Ruby Source
76
+
77
+ The browser Ruby VM resolves `require_relative` over HTTP, one request per source file, and those requests are sequential. The gemstone example reaches 83 files, so an unbundled deployment pays 83 round trips before the scene can run. On a connection with 200 ms of latency that is roughly 17 seconds of waiting on its own.
78
+
79
+ `scripts/bundle-ruby.mjs` inlines those files into a single entrypoint at build time:
80
+
81
+ ```sh
82
+ node scripts/bundle-ruby.mjs examples/browser/ruby/main.rb dist/examples/browser/ruby/main.rb
83
+ ```
84
+
85
+ Only literal top-level `require_relative "path"` lines are inlined, matching what `JS::RequireRemote` itself resolves. `require "json"` and other standard library requires are left alone, and each file is included once, in the order Ruby would have loaded it.
86
+
87
+ Local development and the smoke tests still serve the repository root and still load the unbundled sources, so `require_relative` stays the way you edit the code.
88
+
89
+ ## Optional Headers
90
+
91
+ Cloudflare Pages normally serves static assets with appropriate content types. The runtime also falls back when `.wasm` is not served as `application/wasm`, but using the wasm content type is faster because it allows streaming compilation.
92
+
93
+ Add this file at `dist/_headers` if you want to force the wasm MIME type:
94
+
95
+ ```text
96
+ /*.wasm
97
+ Content-Type: application/wasm
98
+ ```
99
+
100
+ If you later add a Content Security Policy, make sure it still allows same-origin JavaScript modules, WebAssembly compilation, same-origin fetches, and WebGL. The example does not need a custom CSP by default.
101
+
102
+ ## Cloudflare Pages Settings
103
+
104
+ Create a Pages project from the repository and use these settings:
105
+
106
+ ```text
107
+ Framework preset: None
108
+ Build command: pnpm run build:pages:ruby
109
+ Build output directory: dist
110
+ ```
111
+
112
+ Set this environment variable to match the package manager version declared in `package.json`:
113
+
114
+ ```text
115
+ PNPM_VERSION=11.1.1
116
+ ```
117
+
118
+ Optional, if you host `ruby+stdlib.wasm` yourself:
119
+
120
+ ```text
121
+ RUBY_WASM_URL=https://<your-static-host>/ruby+stdlib.wasm
122
+ ```
123
+
124
+ Cloudflare Pages installs dependencies from `package.json` before the build command unless dependency installation is disabled. The build command creates `dist/` on Cloudflare during each deployment, so `dist/` should not be committed to the repository. The build only runs `sh` and Node, so Pages needs no Ruby at build time either, and the deployed site is static files.
125
+
126
+ After deployment, open:
127
+
128
+ ```text
129
+ https://<project>.pages.dev/
130
+ ```
131
+
132
+ ## Direct Upload With Wrangler
133
+
134
+ For a manual deployment, build the output directory locally and upload it:
135
+
136
+ ```sh
137
+ pnpm install
138
+ pnpm run build:pages:ruby
139
+ pnpm exec wrangler pages deploy dist --project-name <project>
140
+ ```
141
+
142
+ Open the deployed Pages root URL after Wrangler prints it.
143
+
144
+ ## Deploying A Different Example
145
+
146
+ For another browser example, copy that example directory instead of `examples/browser/ruby`:
147
+
148
+ ```sh
149
+ cp -R examples/browser/cube dist/examples/browser/cube
150
+ ```
151
+
152
+ Then open:
153
+
154
+ ```text
155
+ https://<project>.pages.dev/examples/browser/cube/
156
+ ```
157
+
158
+ Keep `examples/browser/shared` and the same browser packages in the output directory, and bundle that example's entrypoint the same way. The build script also replaces `/node_modules/` with `/vendor/` in the Ruby example's `index.html` and bundled `main.rb`; do the same for the copied example, or its import map and asset URLs will point at paths that are not deployed. Examples with local files under `assets/` need those assets copied with the example directory.
159
+
160
+ ## Troubleshooting
161
+
162
+ `Failed to load ruby.wasm: 404`
163
+
164
+ The configured wasm URL is not reachable. For Cloudflare Pages, do not rely on `/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm` as a Pages asset: that file is larger than Pages' 25 MiB single-file limit. Use the default CDN URL generated by `pnpm run build:pages:ruby`, or set `RUBY_WASM_URL` to a public R2/CDN URL.
165
+
166
+ `Failed to resolve module specifier`
167
+
168
+ The import map in the example page points at a package path that is missing from the output directory. After the build script, the import map should point at `/vendor/...`; a page that still points at `/node_modules/...` was copied without that rewrite.
169
+
170
+ `/node_modules/three/examples/jsm/... not found`
171
+
172
+ The deployed site is using an older output layout or the output directory contains pnpm symlinks instead of package files. Rebuild `dist/` from an empty directory with `pnpm run build:pages:ruby`, then confirm the expected addon exists under `/vendor/`:
173
+
174
+ ```sh
175
+ test -f dist/vendor/three/examples/jsm/postprocessing/UnrealBloomPass.js
176
+ ```
177
+
178
+ Ruby `require_relative` errors
179
+
180
+ The deployed `main.rb` was copied instead of bundled, or the example was moved without updating its relative Ruby paths. Confirm the deployed entrypoint is the generated bundle:
181
+
182
+ ```sh
183
+ head -2 dist/examples/browser/ruby/main.rb
184
+ grep -c require_relative dist/examples/browser/ruby/main.rb
185
+ ```
186
+
187
+ The second command should print `0`.
188
+
189
+ The status stays at `Loading ruby.wasm`
190
+
191
+ The boot runtime aborts and retries the wasm download up to three times if it stops making progress for 20 seconds, and the status line shows `Retrying ruby.wasm download (n/3)` while it does. If it still fails, check the browser network tab for failed `.wasm`, `.mjs`, `.rb`, font `.json`, or three.js addon requests. A missing static asset is the most common cause.
192
+
193
+ If the download completes but is simply slow for everyone, the wasm host is the problem rather than the page. Check whether the host returns a `cf-cache-status` header; an endpoint that never does is not being cached at the edge.
194
+
195
+ The canvas is blank after the status says `Running`
196
+
197
+ Run `pnpm test:browser:ruby` locally first. If the smoke test passes locally, compare the deployed network responses and browser console errors with the local server.
198
+
199
+ ## Limitations
200
+
201
+ The Ruby source files are public static assets because the browser Ruby VM fetches them over HTTP.
202
+
203
+ Cloudflare Pages Functions are not a Ruby server runtime. If the app needs server-side behavior, implement it in Pages Functions or Workers and keep the three-rb browser scene as a static client.
204
+
205
+ The current examples assume root-relative paths. If you need to serve them from a nested path behind another proxy, update the import map, wasm URL, `JS::RequireRemote.instance.base_url`, and any asset URLs in the Ruby entrypoint.
@@ -63,7 +63,7 @@ These can be future extensions. Adding them too early would expand the scope bef
63
63
 
64
64
  ### three.js
65
65
 
66
- The local three.js reference has package version `0.184.0`. Its public API is assembled through `src/Three.Core.js` and `src/Three.js`, which re-export many modules.
66
+ When this plan was written, the local three.js reference had package version `0.184.0`; the browser runtime now pins `0.187.0` (see `docs/browser-runtime.md`). Its public API is assembled through `src/Three.Core.js` and `src/Three.js`, which re-export many modules.
67
67
 
68
68
  The main module boundaries are:
69
69
 
@@ -81,7 +81,7 @@ The key architectural observation is that the renderer is much more complex than
81
81
 
82
82
  ### ruby.wasm
83
83
 
84
- ruby.wasm provides CRuby builds for WebAssembly/WASI. It includes npm packages such as `@ruby/wasm-wasi` and Ruby-version-specific packages. In the local repository, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are version `2.9.4`.
84
+ ruby.wasm provides CRuby builds for WebAssembly/WASI. It includes npm packages such as `@ruby/wasm-wasi` and Ruby-version-specific packages. In the local repository, `@ruby/3.4-wasm-wasi` and `@ruby/wasm-wasi` are version `2.10.1`.
85
85
 
86
86
  Ruby can access JavaScript through `require "js"`. This enables Ruby code to use the DOM, call JavaScript constructors, pass callbacks, and await JavaScript promises.
87
87
 
@@ -497,6 +497,8 @@ Current implementation status:
497
497
  - `Three::Renderers::ThreeJSRenderer` exists and delegates renderer creation, sizing, animation loops, scene syncing, and render calls to the backend.
498
498
  - The bridge can materialize `Scene`, `Group`, `Object3D`, external loaded `Object3D` handles, `PerspectiveCamera`, `OrthographicCamera`, `Mesh`, `Line`, `Points`, `Sprite`, `AmbientLight`, `DirectionalLight`, `PointLight`, `HemisphereLight`, `Texture`, `CubeTexture`, `RGBETexture`, `BoxGeometry`, `PlaneGeometry`, `SphereGeometry`, generic `BufferGeometry`, `BufferAttribute`, `MeshBasicMaterial`, `LineBasicMaterial`, `PointsMaterial`, `SpriteMaterial`, `MeshLambertMaterial`, `MeshMatcapMaterial`, `MeshToonMaterial`, `MeshStandardMaterial`, `MeshPhysicalMaterial`, `MeshNormalMaterial`, and `ShadowMaterial`.
499
499
  - Unit tests cover materialization, handle caching, transform syncing, rendering delegation, and disposal through a fake three.js adapter.
500
+ - `examples/browser/ruby` renders a Ruby-authored faceted gemstone from a generic `BufferGeometry` with `MeshPhysicalMaterial`, a three-dimensional `TextGeometry` title loaded through `FontLoader`, shadows, and `OrbitControls`.
501
+ - `examples/browser/dango` composes a three-color dango from `SphereGeometry` and `BoxGeometry` meshes in `Group`s, lit by directional, hemisphere, and point lights with shadows, under an `OrthographicCamera` with `OrbitControls`.
500
502
  - `examples/browser/cube` loads pnpm-managed ruby.wasm and three.js browser packages, loads this library from `lib/`, and renders a rotating cube through `Three::Renderers::ThreeJSRenderer`.
501
503
  - `examples/browser/cube/smoke_test.mjs` provides an opt-in Playwright smoke test that serves the repository root, waits for the example to reach `Running`, and samples the WebGL canvas for nonblank pixels.
502
504
  - `examples/browser/composition` renders an `OrthographicCamera` view with ambient/directional/point/hemisphere lights, directional shadow mapping, `PlaneGeometry`, `SphereGeometry`, grouped meshes, `TextureLoader` repeat/wrap/filter settings, `MeshLambertMaterial`, `MeshPhongMaterial`, `MeshStandardMaterial`, `MeshNormalMaterial`, `ShadowMaterial`, backend material/texture disposal, and a material color update through the same renderer path.
@@ -866,9 +868,9 @@ The MVP is complete when:
866
868
  The original MVP decisions are now resolved:
867
869
 
868
870
  - Use `minitest` for the first public release test suite.
869
- - Use pnpm-managed local browser dependencies for ruby.wasm and three.js, avoiding CDN runtime drift and browser ORB failures.
871
+ - Use pnpm-managed local browser dependencies for ruby.wasm and three.js, avoiding CDN runtime drift and browser ORB failures. The Cloudflare Pages build is the one exception: ruby.wasm is over the Pages asset size limit, so it loads from jsDelivr, pinned to the version in `package.json`.
870
872
  - Defer broad camelCase three.js compatibility aliases until after the first public release; snake-case Ruby methods are the documented API style.
871
873
  - Start geometry and attribute data with standard Ruby `Array` values instead of requiring `numo-narray`.
872
874
  - Publish the gem as `three-rb`.
873
875
 
874
- The first public target is `0.1.0` browser-first alpha. Its completion definition and release gate are tracked in `docs/release-readiness.md`.
876
+ `0.1.0` was the first public browser-first alpha release. The release gate for later releases is tracked in `docs/release-readiness.md`.
@@ -122,7 +122,7 @@ Local source locations:
122
122
 
123
123
  The existing glTF browser smoke test verifies:
124
124
 
125
- - `Three::Loaders::GLTFLoader` loads `examples/browser/assets/triangle.gltf`.
125
+ - `Three::Loaders::GLTFLoader` loads assets from `examples/browser/gltf/assets/`.
126
126
  - The returned `gltf.scene` can be added to a Ruby `Scene`.
127
127
  - The loaded JavaScript scene renders through `Three::Renderers::ThreeJSRenderer`.
128
128
  - The animation loop can mutate the external root transform.
data/docs/next-work.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  This document is the resume point for the next implementation session. It is intentionally narrower than `docs/implementation-plan.md`: use it to decide what to do next after conversation context is lost.
4
4
 
5
- Last updated: 2026-05-17.
5
+ Last updated: 2026-11-20.
6
6
 
7
7
  ## Current Position
8
8
 
9
- The project is past the original MVP and is in Phase 8, renderer maturity. The `0.1.0` browser-first alpha target is implemented and release-gate ready; the remaining release work is manual metadata finalization and publishing after owner confirmation.
9
+ The project is past the original MVP and is in Phase 8, renderer maturity. `0.1.0` through `0.3.0` are published on RubyGems. Record changes made after `0.3.0` under an `## Unreleased` heading at the top of `CHANGELOG.md`.
10
10
 
11
11
  Recent completed work:
12
12
 
@@ -29,30 +29,33 @@ Recent completed work:
29
29
  - Browser examples were moved to Ruby-only entrypoints that use `Three::Browser` helpers instead of application-level `require "js"` or `JS.global`.
30
30
  - Added the `three-rb browser` executable and generator for standalone Ruby-only browser examples.
31
31
  - Release install smoke now validates the installed executable and generated browser app shape outside the repository load path.
32
- - Local release gate and latest `main` CI are green for the `0.1.0` release candidate.
32
+ - Local release gate and `main` CI were green for each published release.
33
+
34
+ Released in `0.3.0`:
35
+
36
+ - Dango browser example with primitive meshes, lighting, shadows, and smoke coverage.
37
+ - Cloudflare Pages deployment guide and the repository's `pnpm build:pages:ruby` build, which bundles the Ruby entrypoint and loads ruby.wasm from jsDelivr.
38
+ - Shared `config.mjs` for the ruby.wasm URL, a loading progress bar, and stalled-download retries in the shared boot.
39
+ - ruby.wasm 2.10.1 and three.js 0.187.0 (r187), including the r187 iridescence and shadow-map changes.
40
+ - Generated apps get a runtime-only `package.json` and matching lockfile, and a smoke test generates, installs, and renders them.
41
+ - Browser smoke tests fail on three.js console warnings.
33
42
 
34
43
  Do not start Phase 9 native renderer work yet. The implementation plan still recommends keeping browser rendering delegated to three.js through ruby.wasm until the browser-first API is more stable.
35
44
 
36
45
  ## Recommended Next Task
37
46
 
38
- Keep the `0.1.0` release candidate current while the release is deferred. Publish only after the release owner confirms the date and RubyGems credentials.
47
+ Pick one feature target and keep the change small enough to verify through one browser example.
39
48
 
40
49
  This is the best next step because:
41
50
 
42
- - The representative JSON fixture covers the current primitive/material surface, including `Sprite` / `SpriteMaterial`.
43
- - The public docs now cover release readiness, publishing, browser example coverage, browser runtime boot contract, and the current implemented API scope.
44
- - `lib/three/version.rb` already contains `0.1.0`.
45
- - `CHANGELOG.md` currently records `## 0.1.0 - 2026-05-15`; if the release date changes before publishing, update that heading during release metadata finalization.
46
- - The release candidate now includes the Ruby-only browser generator and installed-generator smoke coverage.
47
- - Further feature scope should wait until after the `0.1.0` release unless an already-advertised example breaks.
51
+ - `0.3.0` brought the pinned runtime up to three.js r187 and ruby.wasm 2.10.1 and fixed the generated-app install, so no release work is pending.
52
+ - The release gate, CI on Ruby 3.3, 3.4, and 4.0, and the browser smoke tests all pass on `main`.
48
53
 
49
54
  ## Scope
50
55
 
51
- For deferred-release maintenance, keep `CHANGELOG.md`, `docs/release-readiness.md`, and this resume point aligned with the implemented release-candidate surface. Do not tag, push, or publish until the release owner confirms the release window. If the confirmed release date differs from the current changelog heading, update it as release metadata work.
52
-
53
- When the owner is ready to publish, follow `docs/publishing.md`: confirm the release date, update `CHANGELOG.md`, run `bundle exec rake release:preflight`, commit the metadata update, publish the gem, tag `v0.1.0`, push `main` and the tag, then verify installation from RubyGems.
56
+ Between releases, keep `CHANGELOG.md`, `docs/release-readiness.md`, and this resume point aligned with what is on `main`. Do not tag, push, or publish until the release owner confirms.
54
57
 
55
- After the release is published, pick one feature target and keep the change small enough to verify through one browser example.
58
+ When the owner is ready to publish, follow `docs/publishing.md`: bump `lib/three/version.rb`, replace the current changelog heading `## Unreleased` with the version and date, run `bundle exec rake release:preflight`, commit the metadata update, publish the gem, tag the release, push `main` and the tag, then verify installation from RubyGems.
56
59
 
57
60
  Candidate targets, in recommended order when there is no stronger product signal:
58
61
 
@@ -64,16 +67,14 @@ Candidate targets, in recommended order when there is no stronger product signal
64
67
 
65
68
  ## Suggested Implementation Plan
66
69
 
67
- 1. While release is deferred, keep the current changelog heading, release-readiness docs, and publishing checklist aligned with the release candidate without changing the version, tag, or published artifact.
68
- 2. When release is confirmed, adjust `CHANGELOG.md` only if the confirmed release date differs from the current heading.
69
- 3. Run `bundle exec rake release:preflight`.
70
- 4. Commit the release metadata with a message that does not include co-author trailers.
71
- 5. Publish and tag using `docs/publishing.md`.
72
- 6. After publishing, start the next feature from a user-visible workflow and choose exactly one feature target.
73
- 7. Add Ruby API coverage, fake adapter/backend tests, JSON export/load coverage when the object is serializable, and resource-disposal coverage when it owns GPU resources.
74
- 8. Add or extend one browser example and keep `examples/browser/README.md` in sync.
75
- 9. Add or update a deterministic Playwright smoke command in `package.json`.
76
- 10. Run Ruby tests, the affected browser smoke test, `bundle exec rake release:gem_smoke`, and `bundle exec rake release:preflight` before release work.
70
+ 1. Start the next feature from a user-visible workflow and choose exactly one feature target.
71
+ 2. Add Ruby API coverage, fake adapter/backend tests, JSON export/load coverage when the object is serializable, and resource-disposal coverage when it owns GPU resources.
72
+ 3. Add or extend one browser example and keep `examples/browser/README.md` in sync.
73
+ 4. Add or update a deterministic Playwright smoke command in `package.json`.
74
+ 5. Record the change under an `## Unreleased` heading in `CHANGELOG.md`.
75
+ 6. Run Ruby tests, the affected browser smoke test, `bundle exec rake release:gem_smoke`, and `bundle exec rake release:preflight` before release work.
76
+ 7. Before the next release, keep the current changelog heading, release-readiness docs, and publishing checklist aligned with `main` without changing the version, tag, or published artifact until the release owner confirms.
77
+ 8. When the release is confirmed, publish and tag using `docs/publishing.md`, with a release commit message that does not include co-author trailers.
77
78
 
78
79
  ## Acceptance Criteria
79
80
 
@@ -100,7 +101,7 @@ Do not prioritize these without a clear product need:
100
101
  - Native renderer.
101
102
  - Broad public API documentation beyond the current README, release readiness, implementation plan, browser examples overview, and browser runtime guide.
102
103
 
103
- Those are valid later tasks, but they expand feature scope. The immediate gap is keeping the deferred release candidate accurate, then getting final release-owner confirmation and publishing before choosing future feature work by visible workflow and smoke-testability instead of API breadth.
104
+ Those are valid later tasks, but they expand feature scope. The immediate gap is publishing the unreleased changes, then choosing future feature work by visible workflow and smoke-testability instead of API breadth.
104
105
 
105
106
  ## After This Task
106
107
 
data/docs/publishing.md CHANGED
@@ -136,6 +136,9 @@ three-rb --help
136
136
  three-rb browser examples/browser/quickstart
137
137
  test -f examples/browser/quickstart/main.rb
138
138
  ruby -e 'main = File.read("examples/browser/quickstart/main.rb"); abort "generated Ruby entrypoint used JS bridge" if main.include?("require \"js\"") || main.include?("JS.global"); puts "generated Ruby entrypoint is Ruby-only"'
139
+ three-rb browser examples/browser/ruby
140
+ test -f examples/browser/ruby/main.rb
141
+ test -f examples/browser/ruby/assets/helvetiker_regular.typeface.json
139
142
  ```
140
143
 
141
144
  Both Ruby commands must print:
@@ -144,7 +147,7 @@ Both Ruby commands must print:
144
147
  $VERSION
145
148
  ```
146
149
 
147
- The `three-rb browser` command must create `examples/browser/quickstart/main.rb`, and the final Ruby command must print:
150
+ The `three-rb browser` command must create `examples/browser/quickstart/main.rb` and `examples/browser/ruby/main.rb`, and the final Ruby command must print:
148
151
 
149
152
  ```text
150
153
  generated Ruby entrypoint is Ruby-only