three-rb 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab46f2291f0b0adcb818d9a079c341333adeec066588ed09e8c189b798819725
-  data.tar.gz: 3ca4184c327a2abf28dc6b081a5f0e4df8b31a183942ed82da94103146ef3922
+  metadata.gz: 1b6b3331ebb395126e0bbd0003e8cb8e9da2648107319e4c0953e6a1d33ddbfd
+  data.tar.gz: 1867f60db80fc386322c82ebc35b5bbda234712f2b9370164487e0105066001c
 SHA512:
-  metadata.gz: e2c3710079194f6860b05827679bb8e5797b52164e33016f2dcf95feabffd22da475edd2640e6f76e854606785be92c27772c679b969f73808ac0821b5b8b7ea
-  data.tar.gz: 9edb5c3dac961c7798e45e9901f408a3896c36e7db50ddedc1cd439ec7d3e5d54fdbeface42df108f679517fed14d81e23fe9e0d0730b24147ee37aecd430f82
+  metadata.gz: ee90d10b58348b809c087d7c25dc29dd62c4173e83892bfe09710002c83dac9ccd65c8aaa1af91538100d262d595278904267273f1a0d4baa75ed2fe4dca6c45
+  data.tar.gz: f65cf3c1132a728e54601ca7b4f0de2433755320b1d9d842844118606e4391c4d286be65386c2d1a548132b406759e7d6af45be2fe604fad08034f1e9a50759a

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.1 - 2026-05-17
+
+### Added
+
+- Added a generated Ruby browser example template that copies the full gemstone example, including its local HDR asset.
+- Added generator coverage for Ruby example asset copying and Ruby-only browser entrypoints.
+
+### Changed
+
+- Moved browser example assets into example-local asset directories so generated examples and smoke tests use self-contained paths.
+- Strengthened release readiness checks for the browser generator template and installed executable.
+
 ## 0.2.0 - 2026-05-17
 
 ### Added

data/README.md

@@ -137,6 +137,8 @@ pnpm install
 ruby -run -e httpd . -p 8000
 ```
 
+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/`.
+
 The generated Ruby entrypoint uses `Three::Browser.run`, so ordinary scene code does not need `require "js"` or `JS.global`.
 
 Run the optional browser smoke tests:

data/docs/browser-runtime.md

@@ -183,7 +183,9 @@ For standalone projects, install the gem and generate a Ruby-only browser exampl
 three-rb browser examples/browser/quickstart
 ```
 
-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.
+`quickstart` generates an asset-free rotating cube. Use `three-rb browser examples/browser/ruby` to generate the richer Ruby gemstone sample; its HDR asset is copied under `examples/browser/ruby/assets/`.
+
+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. Templates that need local files keep them under the generated example's `assets/` directory.
 
 ## JavaScript Escape Hatch
 

data/docs/loaded-assets-design.md

@@ -122,7 +122,7 @@ Local source locations:
 
 The existing glTF browser smoke test verifies:
 
-- `Three::Loaders::GLTFLoader` loads `examples/browser/assets/triangle.gltf`.
+- `Three::Loaders::GLTFLoader` loads assets from `examples/browser/gltf/assets/`.
 - The returned `gltf.scene` can be added to a Ruby `Scene`.
 - The loaded JavaScript scene renders through `Three::Renderers::ThreeJSRenderer`.
 - The animation loop can mutate the external root transform.

data/docs/publishing.md

@@ -136,6 +136,9 @@ three-rb --help
 three-rb browser examples/browser/quickstart
 test -f examples/browser/quickstart/main.rb
 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"'
+three-rb browser examples/browser/ruby
+test -f examples/browser/ruby/main.rb
+test -f examples/browser/ruby/assets/studio.hdr
 ```
 
 Both Ruby commands must print:
@@ -144,7 +147,7 @@ Both Ruby commands must print:
 $VERSION
 ```
 
-The `three-rb browser` command must create `examples/browser/quickstart/main.rb`, and the final Ruby command must print:
+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:
 
 ```text
 generated Ruby entrypoint is Ruby-only

data/docs/standalone-browser-app.md

@@ -22,6 +22,8 @@ If you installed through Bundler, run:
 bundle exec three-rb browser examples/browser/quickstart
 ```
 
+Use `three-rb browser examples/browser/ruby` instead when you want the richer Ruby gemstone sample. It generates the same browser runtime shape and keeps its HDR file under `examples/browser/ruby/assets/`.
+
 The generator creates:
 
 - `package.json` and `pnpm-lock.yaml`
@@ -32,6 +34,8 @@ The generator creates:
 - `examples/browser/quickstart/main.rb`
 - `examples/browser/quickstart/README.md`
 
+For templates that need assets, the generator also creates an `assets/` directory inside the example.
+
 Copying `lib/` puts the installed gem's Ruby source in the served app directory. The browser Ruby VM loads Ruby files over HTTP, so this is the current standalone workflow.
 
 Pass `--force` only when you want to overwrite generated example files:

data/examples/browser/README.md

@@ -2,6 +2,8 @@
 
 These examples are the browser-facing coverage map for three-rb's browser-first alpha. They run Ruby through ruby.wasm, load pnpm-managed three.js packages, and render through `Three::Renderers::ThreeJSRenderer`.
 
+Examples that need fixtures keep those files under their own `assets/` directory so each sample remains self-contained.
+
 ## Run Examples
 
 Install browser dependencies and serve the repository root:

data/examples/browser/composition/main.rb

@@ -41,7 +41,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   rig.name = "composition-rig"
   scene.add(rig)
 
-  primary_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  primary_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/composition/assets/checker.svg")
   primary_texture.wrap_s = Three::RepeatWrapping
   primary_texture.wrap_t = Three::RepeatWrapping
   primary_texture.mag_filter = Three::NearestFilter
@@ -164,7 +164,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
     renderer: renderer
   )
 
-  disposable_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  disposable_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/composition/assets/checker.svg")
   disposable_material = Three::MeshBasicMaterial.new(map: disposable_texture)
   renderer.on_dispose(disposable_texture) { app.set(:texture_dispose_event, true) }
   renderer.on_dispose(disposable_material) { app.set(:material_dispose_event, true) }

data/examples/browser/cubemap/assets/checker.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" fill="#eef3f7"/>
+  <rect width="32" height="32" fill="#22313f"/>
+  <rect x="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="64" y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="96" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="96" width="32" height="32" fill="#6ed69a"/>
+</svg>

data/examples/browser/cubemap/main.rb

@@ -7,7 +7,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   camera = Three::PerspectiveCamera.new(45, aspect: 1.0, near: 0.1, far: 100)
   camera.position.set(0, 0.7, 4.0)
 
-  cube_sources = Array.new(6, "/examples/browser/assets/checker.svg")
+  cube_sources = Array.new(6, "/examples/browser/cubemap/assets/checker.svg")
   cube_texture = Three::Loaders::CubeTextureLoader.new.load(cube_sources)
   scene.background = cube_texture
   scene.environment = cube_texture

data/examples/browser/gltf/main.rb

@@ -21,7 +21,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   )
   renderer.set_clear_color(0x11151a, 1)
 
-  gltf = Three::Loaders::GLTFLoader.new(backend: renderer.backend).load("/examples/browser/assets/animated_triangle.gltf")
+  gltf = Three::Loaders::GLTFLoader.new(backend: renderer.backend).load("/examples/browser/gltf/assets/animated_triangle.gltf")
   model = gltf.scene
   model.position.x = -0.75
   model.scale.set(1.2, 1.2, 1.2)
@@ -31,7 +31,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   compressed_gltf = Three::Loaders::GLTFLoader.new(
     backend: renderer.backend,
     draco_decoder_path: draco_decoder_path
-  ).load("/examples/browser/assets/compressed_triangle.gltf")
+  ).load("/examples/browser/gltf/assets/compressed_triangle.gltf")
   compressed_model = compressed_gltf.scene
   compressed_model.position.x = 1.05
   compressed_model.scale.set(0.82, 0.82, 0.82)

data/examples/browser/primitives/assets/checker.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" fill="#eef3f7"/>
+  <rect width="32" height="32" fill="#22313f"/>
+  <rect x="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="64" y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="96" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="96" width="32" height="32" fill="#6ed69a"/>
+</svg>

data/examples/browser/primitives/main.rb

@@ -43,7 +43,7 @@ Three::Browser.run(starting: "Starting primitives scene") do |app|
     Three::PointsMaterial.new(color: 0xffcc4d, size: 12, size_attenuation: false)
   )
 
-  sprite_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  sprite_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/primitives/assets/checker.svg")
   sprite_material = Three::SpriteMaterial.new(
     color: 0xffffff,
     map: sprite_texture,

data/examples/browser/ruby/README.md

@@ -2,6 +2,8 @@
 
 This browser example is the first visual sample for three-rb. It builds a faceted red gemstone in Ruby with `BufferGeometry`, renders it with `MeshPhysicalMaterial`, and adds an extruded `three-rb` title through the three.js `TextGeometry` addon.
 
+Its HDR environment file lives under `examples/browser/ruby/assets/` with the sample.
+
 Run it from the repository root:
 
 ```sh

data/examples/browser/ruby/main.rb

@@ -106,7 +106,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   camera = Three::PerspectiveCamera.new(42, aspect: 1.0, near: 0.1, far: 100)
   camera.position.set(0, 0.42, 6.9)
 
-  environment_texture = Three::Loaders::RGBELoader.new.load("/examples/browser/assets/studio.hdr")
+  environment_texture = Three::Loaders::RGBELoader.new.load("/examples/browser/ruby/assets/studio.hdr")
   scene.environment = environment_texture
 
   scene.add(Three::AmbientLight.new(0xffffff, 0.82))

data/examples/browser/serialization/assets/checker.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" fill="#eef3f7"/>
+  <rect width="32" height="32" fill="#22313f"/>
+  <rect x="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="64" y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="96" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="96" width="32" height="32" fill="#6ed69a"/>
+</svg>

data/examples/browser/serialization/main.rb

@@ -6,7 +6,7 @@ Three::Browser.run(starting: "Exporting Ruby scene") do |app|
   source_scene = Three::Scene.new
   source_scene.name = "serialization-source"
 
-  shared_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  shared_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/serialization/assets/checker.svg")
   shared_texture.wrap_s = Three::RepeatWrapping
   shared_texture.wrap_t = Three::RepeatWrapping
   shared_texture.mag_filter = Three::NearestFilter

data/examples/browser/shared/boot.mjs

@@ -90,7 +90,7 @@ function shouldBypassCache(input) {
   if (pathname.startsWith("/lib/")) return true;
   if (!pathname.startsWith("/examples/browser/")) return false;
 
-  return !pathname.startsWith("/examples/browser/assets/");
+  return !pathname.includes("/assets/");
 }
 
 async function compileWasm(url) {

data/examples/browser/textures/assets/checker.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" fill="#eef3f7"/>
+  <rect width="32" height="32" fill="#22313f"/>
+  <rect x="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="32" width="32" height="32" fill="#6ed69a"/>
+  <rect y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="64" y="64" width="32" height="32" fill="#22313f"/>
+  <rect x="32" y="96" width="32" height="32" fill="#6ed69a"/>
+  <rect x="96" y="96" width="32" height="32" fill="#6ed69a"/>
+</svg>

data/examples/browser/textures/assets/studio.hdr

@@ -0,0 +1,5 @@
+#?RADIANCE
+FORMAT=32-bit_rle_rgbe
+
+-Y 2 +X 2
+~~~~~~~~~~~~~~~~

data/examples/browser/textures/main.rb

@@ -7,7 +7,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   camera = Three::OrthographicCamera.new(-2.5, 2.5, 1.6, -1.6, near: 0.1, far: 100)
   camera.position.z = 5
 
-  environment_texture = Three::Loaders::RGBELoader.new.load("/examples/browser/assets/studio.hdr")
+  environment_texture = Three::Loaders::RGBELoader.new.load("/examples/browser/textures/assets/studio.hdr")
   scene.environment = environment_texture
 
   scene.add(Three::AmbientLight.new(0xffffff, 0.45))
@@ -16,7 +16,7 @@ Three::Browser.run(starting: "Starting Ruby scene") do |app|
   key_light.position.set(2.5, 3.0, 4.0)
   scene.add(key_light)
 
-  texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  texture = Three::Loaders::TextureLoader.new.load("/examples/browser/textures/assets/checker.svg")
   texture.wrap_s = Three::RepeatWrapping
   texture.wrap_t = Three::RepeatWrapping
   texture.mag_filter = Three::NearestFilter

data/exe/three-rb

@@ -14,6 +14,7 @@ def usage
 
     Example:
       three-rb browser examples/browser/quickstart
+      three-rb browser examples/browser/ruby
   TEXT
 end
 

data/lib/three/generators/browser_example.rb

@@ -67,10 +67,42 @@ module Three
       end
 
       def write_example_files
-        write_file(example_path("index.html"), index_html, overwrite: @force)
-        write_file(example_path("boot.mjs"), boot_js, overwrite: @force)
-        write_file(example_path("main.rb"), main_rb, overwrite: @force)
-        write_file(example_path("README.md"), readme, overwrite: @force)
+        if ruby_example?
+          copy_ruby_example_files
+        else
+          write_file(example_path("index.html"), index_html, overwrite: @force)
+          write_file(example_path("boot.mjs"), boot_js, overwrite: @force)
+          write_file(example_path("main.rb"), main_rb, overwrite: @force)
+          write_file(example_path("README.md"), readme, overwrite: @force)
+        end
+      end
+
+      def copy_ruby_example_files
+        {
+          "index.html" => "index.html",
+          "boot.mjs" => "boot.mjs",
+          "main.rb" => "main.rb",
+          "assets/studio.hdr" => "assets/studio.hdr"
+        }.each do |source_name, destination_name|
+          copy_generated_file(
+            runtime_path(File.join("examples/browser/ruby", source_name)),
+            example_path(destination_name),
+            overwrite: @force
+          )
+        end
+
+        write_ruby_readme
+      end
+
+      def write_ruby_readme
+        source = runtime_path("examples/browser/ruby/README.md")
+        destination = example_path("README.md")
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
+        write_file(destination, ruby_readme, overwrite: @force)
       end
 
       def copy_tree(source, destination, overwrite:)
@@ -83,6 +115,11 @@ module Three
       end
 
       def copy_file(source, destination, overwrite:)
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
         if File.exist?(destination) && !overwrite
           @skipped << relative_path(destination)
           return
@@ -93,6 +130,21 @@ module Three
         @created << relative_path(destination)
       end
 
+      def copy_generated_file(source, destination, overwrite:)
+        if File.exist?(destination) && File.identical?(source, destination)
+          @skipped << relative_path(destination)
+          return
+        end
+
+        if File.exist?(destination) && !overwrite
+          raise ArgumentError, "#{relative_path(destination)} already exists; pass --force to overwrite generated example files"
+        end
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.cp(source, destination)
+        @created << relative_path(destination)
+      end
+
       def write_file(path, content, overwrite:)
         if File.exist?(path) && !overwrite
           raise ArgumentError, "#{relative_path(path)} already exists; pass --force to overwrite generated example files"
@@ -114,7 +166,9 @@ module Three
       end
 
       def example_files
-        %w[index.html boot.mjs main.rb README.md].map { |name| example_path(name) }
+        names = %w[index.html boot.mjs main.rb README.md]
+        names << "assets/studio.hdr" if ruby_example?
+        names.map { |name| example_path(name) }
       end
 
       def example_path(name)
@@ -155,6 +209,10 @@ module Three
         JSON.generate(text)
       end
 
+      def ruby_example?
+        relative_path(@target) == "examples/browser/ruby"
+      end
+
       def index_html
         <<~HTML
           <!doctype html>
@@ -310,6 +368,29 @@ module Three
           Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example over HTTP.
         MARKDOWN
       end
+
+      def ruby_readme
+        <<~MARKDOWN
+          # three-rb Ruby Example
+
+          This generated browser example runs Ruby through ruby.wasm and renders a faceted red gemstone with a three-dimensional `three-rb` title.
+
+          From the project root:
+
+          ```sh
+          pnpm install
+          ruby -run -e httpd . -p 8000
+          ```
+
+          Open:
+
+          ```text
+          http://localhost:8000/#{relative_path(@target)}/
+          ```
+
+          Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example's local `assets/` directory over HTTP.
+        MARKDOWN
+      end
     end
   end
 end

data/lib/three/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Three
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: three-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - LEF
@@ -56,12 +56,8 @@ files:
 - docs/release-readiness.md
 - docs/standalone-browser-app.md
 - examples/browser/README.md
-- examples/browser/assets/animated_triangle.gltf
-- examples/browser/assets/checker.svg
-- examples/browser/assets/compressed_triangle.gltf
-- examples/browser/assets/studio.hdr
-- examples/browser/assets/triangle.gltf
 - examples/browser/composition/README.md
+- examples/browser/composition/assets/checker.svg
 - examples/browser/composition/boot.mjs
 - examples/browser/composition/index.html
 - examples/browser/composition/main.rb
@@ -72,11 +68,15 @@ files:
 - examples/browser/cube/main.rb
 - examples/browser/cube/smoke_test.mjs
 - examples/browser/cubemap/README.md
+- examples/browser/cubemap/assets/checker.svg
 - examples/browser/cubemap/boot.mjs
 - examples/browser/cubemap/index.html
 - examples/browser/cubemap/main.rb
 - examples/browser/cubemap/smoke_test.mjs
 - examples/browser/gltf/README.md
+- examples/browser/gltf/assets/animated_triangle.gltf
+- examples/browser/gltf/assets/compressed_triangle.gltf
+- examples/browser/gltf/assets/triangle.gltf
 - examples/browser/gltf/boot.mjs
 - examples/browser/gltf/index.html
 - examples/browser/gltf/main.rb
@@ -92,16 +92,19 @@ files:
 - examples/browser/postprocessing/main.rb
 - examples/browser/postprocessing/smoke_test.mjs
 - examples/browser/primitives/README.md
+- examples/browser/primitives/assets/checker.svg
 - examples/browser/primitives/boot.mjs
 - examples/browser/primitives/index.html
 - examples/browser/primitives/main.rb
 - examples/browser/primitives/smoke_test.mjs
 - examples/browser/ruby/README.md
+- examples/browser/ruby/assets/studio.hdr
 - examples/browser/ruby/boot.mjs
 - examples/browser/ruby/index.html
 - examples/browser/ruby/main.rb
 - examples/browser/ruby/smoke_test.mjs
 - examples/browser/serialization/README.md
+- examples/browser/serialization/assets/checker.svg
 - examples/browser/serialization/boot.mjs
 - examples/browser/serialization/index.html
 - examples/browser/serialization/main.rb
@@ -109,6 +112,8 @@ files:
 - examples/browser/shared/boot.mjs
 - examples/browser/shared/smoke_test_helpers.mjs
 - examples/browser/textures/README.md
+- examples/browser/textures/assets/checker.svg
+- examples/browser/textures/assets/studio.hdr
 - examples/browser/textures/boot.mjs
 - examples/browser/textures/index.html
 - examples/browser/textures/main.rb