three-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b66b39cafbc0163bffb3b177eeaf1d397ac87fbed27046ca6f5673675fe001b9
-  data.tar.gz: 93dfc4ba66293d5090912b3082b2a84f87ba1d73d284606c9896d9a4b7f9d794
+  metadata.gz: ab46f2291f0b0adcb818d9a079c341333adeec066588ed09e8c189b798819725
+  data.tar.gz: 3ca4184c327a2abf28dc6b081a5f0e4df8b31a183942ed82da94103146ef3922
 SHA512:
-  metadata.gz: 14776a59074de5a790244fc27c698988e7b98fb5c54abd7c8837368d8b029c1a5f3410814377aab663f466aa4e619228622590804d4b9fd261e9ced68877ce0d
-  data.tar.gz: 8292752e152f1aa24751e5b2b7468ca641c0beaaa36c17cfc8439466408214b7fca6fae65b3e0e8226c679586fd0aa532140b6d06fa22eda0205f7abbd57699a
+  metadata.gz: e2c3710079194f6860b05827679bb8e5797b52164e33016f2dcf95feabffd22da475edd2640e6f76e854606785be92c27772c679b969f73808ac0821b5b8b7ea
+  data.tar.gz: 9edb5c3dac961c7798e45e9901f408a3896c36e7db50ddedc1cd439ec7d3e5d54fdbeface42df108f679517fed14d81e23fe9e0d0730b24147ee37aecd430f82

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.2.0 - 2026-05-17
+
+### Added
+
+- Expanded `Three::Browser` helpers so browser examples can stay in Ruby without direct application-level `require "js"` or `JS.global` usage.
+- Added the `three-rb browser` generator for creating standalone browser apps with Ruby-only entrypoints.
+- Added a Ruby gemstone browser example with deterministic smoke coverage.
+- Added scene fog and override material support.
+- Added manual `Object3D` matrix support.
+- Added text geometry and font loader APIs.
+- Added JSON resource metadata preservation for exported and loaded scenes.
+
+### Changed
+
+- Converted browser examples to the Ruby browser helper API and shared browser boot path.
+- Improved browser addon error messages with more actionable guidance.
+- Strengthened release checks for installed gem behavior, the installed executable, and generated browser apps.
+- Expanded browser runtime and standalone app documentation.
+
 ## 0.1.0 - 2026-05-15
 
 ### Added
@@ -8,11 +27,12 @@
 - 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.
+- `Three::Browser` helpers and a `three-rb browser` generator for Ruby-only browser entrypoints that avoid application-level `require "js"` and `JS.global` calls.
 - 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.
+- Release install smoke and preflight tasks for validating the built gem, installed executable, and generated browser app outside the repository load path.
 
 ### Notes
 

data/README.md

@@ -24,7 +24,7 @@ Out of scope for the first public release:
 
 ## Installation
 
-After a release is published:
+Install the released gem from RubyGems:
 
 ```sh
 gem install three-rb
@@ -36,11 +36,41 @@ Or add it to a Gemfile:
 gem "three-rb", "~> 0.1"
 ```
 
+Browser rendering examples also need `pnpm`, because ruby.wasm, three.js, and three.js addons are installed from `package.json`.
+
 ## Quick Start
 
+three-rb is browser-first. The fastest way to try the released gem is to unpack a writable copy of the gem and run one of the included browser examples:
+
+```sh
+gem install three-rb
+mkdir hello-three-rb
+cd hello-three-rb
+gem unpack three-rb
+cd three-rb-*/
+pnpm install
+ruby -run -e httpd . -p 8000
+```
+
+If Ruby reports that `webrick` is not found, install it once with `gem install webrick`. Ruby 3.0 and later no longer include WEBrick as a standard library.
+
+```text
+http://localhost:8000/examples/browser/ruby/
+```
+
+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.
+
+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).
+
+## Plain Ruby Check
+
+If you only want to confirm the Ruby API loads without browser rendering, create `hello_three.rb`:
+
 ```ruby
 require "three"
 
+puts "three-rb #{Three::VERSION}"
+
 scene = Three::Scene.new
 camera = Three::PerspectiveCamera.new(75, aspect: 16.0 / 9.0)
 camera.position.z = 5
@@ -50,20 +80,40 @@ material = Three::MeshBasicMaterial.new(color: 0x00ff00)
 cube = Three::Mesh.new(geometry, material)
 
 scene.add(cube)
+
+puts scene.class
+puts cube.class
+```
+
+Run it:
+
+```sh
+ruby hello_three.rb
+```
+
+You should see the library load and create Ruby scene objects:
+
+```text
+three-rb 0.1.0
+Three::Scene
+Three::Mesh
 ```
 
 Browser rendering is available through `Three::Renderers::ThreeJSRenderer`, which targets three.js from ruby.wasm.
 
-## Browser Example
+## Browser Examples In This Repository
 
-Install browser dependencies, serve the repository root, and open one of the browser examples:
+When developing this repository, install browser dependencies, serve the repository root, and open one of the browser examples:
 
 ```sh
 pnpm install
 ruby -run -e httpd . -p 8000
 ```
 
+If `ruby -run -e httpd` reports that `webrick` is not found, run `gem install webrick` and retry. Ruby 3.0 and later require WEBrick to be installed separately.
+
 ```text
+http://localhost:8000/examples/browser/ruby/
 http://localhost:8000/examples/browser/cube/
 http://localhost:8000/examples/browser/composition/
 http://localhost:8000/examples/browser/textures/
@@ -79,6 +129,16 @@ See [Browser Examples](examples/browser/README.md) for the feature coverage map
 
 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`.
 
+To start a standalone browser app from the installed gem:
+
+```sh
+three-rb browser examples/browser/quickstart
+pnpm install
+ruby -run -e httpd . -p 8000
+```
+
+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:
 
 ```sh
@@ -148,6 +208,7 @@ bundle exec rake release:preflight
 - [Next Work](docs/next-work.md)
 - [Browser Runtime](docs/browser-runtime.md)
 - [Browser Examples](examples/browser/README.md)
+- [Standalone Browser App](docs/standalone-browser-app.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

@@ -11,7 +11,7 @@ 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`.
+4. A Ruby entrypoint that requires `three`, creates a scene inside `Three::Browser.run`, 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.
 
@@ -84,45 +84,45 @@ The shared helper also installs optional render helpers used by smoke tests to d
 
 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.
 
+If a Ruby wrapper needs an addon constructor that the boot module did not register, three-rb raises an error naming the missing `globalThis.THREE_*` value and the import/assignment lines to add to `boot.mjs`.
+
 ## 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:
+The Ruby side should require the library, create a scene inside `Three::Browser.run`, and attach the renderer to the existing canvas. `Three::Browser.run` waits for the JavaScript boot module and handles the example status/error UI, so application scene code does not need to call `JS.global` directly:
 
 ```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
+Three::Browser.run(starting: "Starting Ruby scene") do |app|
+  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)
+  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 = Three::Renderers::ThreeJSRenderer.new(
+    canvas: "#scene",
+    antialias: true,
+    alpha: false
+  )
 
-renderer.set_size(640, 480)
-renderer.render(scene, camera)
+  app.resize_renderer(renderer, camera)
+  renderer.render(scene, camera)
+end
 ```
 
 `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 responsive layouts, use `app.resize_renderer(renderer, camera)` for perspective cameras. For custom orthographic sizing, pass a block and update the camera before the helper sets the renderer size.
 
-For animation, call `renderer.animation_loop`:
+For animation, prefer `app.animation_loop(renderer)`. It delegates to the renderer's browser animation loop and keeps the entrypoint on the `Three::Browser` API surface:
 
 ```ruby
-renderer.animation_loop do
+app.animation_loop(renderer) do
   mesh.rotation.x += 0.01
   mesh.rotation.y += 0.015
   renderer.render(scene, camera)
@@ -131,6 +131,71 @@ end
 
 For postprocessing, render through `composer.render(scene, camera)` instead of `renderer.render(scene, camera)` after configuring `Three::Postprocessing::EffectComposer` and its passes.
 
+## Three::Browser API
+
+`Three::Browser` is the public convenience layer for browser entrypoints. It keeps ordinary scene code Ruby-only while the JavaScript boot module handles ruby.wasm and ES module setup. Treat these methods as the first-choice browser API before reaching for direct JS bridge calls.
+
+Lifecycle and sizing:
+
+- `Three::Browser.run(starting: "...") { |app| ... }` waits for the boot module, creates an application helper, updates the status UI, and reports boot failures.
+- `app.resize_renderer(renderer, camera)` reads the default `#viewport`, updates a perspective camera's aspect/projection matrix, calls `renderer.set_size`, and registers a resize listener.
+- `app.resize_renderer(renderer, camera) { |width, height, aspect| ... }` supports custom camera sizing such as orthographic views.
+- `app.on_resize { |width, height, aspect| ... }` registers a lower-level resize callback and runs it once immediately.
+- `app.animation_loop(renderer) { ... }` delegates to `renderer.animation_loop`.
+- `app.animation_loop { |time| ... }` uses `requestAnimationFrame` directly when a renderer loop is not appropriate.
+
+DOM and events:
+
+- `app.element(renderer.dom_element)` wraps a browser element for event handling and pointer coordinate helpers.
+- `element.on("click") { |event| ... }` registers a DOM event without exposing `JS.global`.
+- `element.pointer_ndc(event)` converts pointer events to normalized device coordinates for `Raycaster#set_from_camera`.
+- `app.pointer_ndc(event, target: "#viewport")` performs the same conversion against a selector, raw element, or `Three::Browser::Element`.
+- `app.on_pointer("click", target: renderer.dom_element) { |event, x, y| ... }` registers a pointer event and yields normalized device coordinates.
+- `app.on_key("keydown", key: "Escape") { |event| ... }` registers keyboard events on `window` by default. Omit `key:` to receive every event.
+
+State and diagnostics:
+
+- `app.storage` wraps `localStorage`; `app.storage(:session)` wraps `sessionStorage`.
+- `storage.set(:name, value)`, `storage.get(:name)`, `storage.delete(:name)`, `storage.clear`, `storage.length`, and `storage.key(index)` cover simple browser storage access.
+- `app.expose(...)`, `app.set`, `app.get`, and `app.increment` are intended for diagnostics, smoke tests, and small browser-visible state values.
+
+Escape hatch:
+
+- `Three::Browser.js` returns `JS.global` and is the explicit escape hatch for advanced browser integrations that three-rb does not wrap yet. Keep usage isolated and prefer adding a Ruby helper when the pattern is reusable.
+
+Example pointer picking:
+
+```ruby
+pointer = Three::Vector2.new
+raycaster = Three::Raycaster.new(backend: renderer.backend)
+
+app.on_pointer("click", target: renderer.dom_element) do |_event, x, y|
+  pointer.set(x, y)
+  raycaster.set_from_camera(pointer, camera)
+end
+```
+
+## Generator
+
+For standalone projects, install the gem and generate a Ruby-only browser example:
+
+```sh
+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.
+
+## JavaScript Escape Hatch
+
+Most browser scene code should not need `require "js"` or `JS.global`. JavaScript is still the right layer for:
+
+- The boot module that imports ES modules and starts ruby.wasm.
+- Custom HTML UI outside the helpers in `Three::Browser`.
+- Browser APIs that three-rb does not wrap yet, such as WebSocket, drag/drop, pointer lock, fullscreen, WebXR session setup, or application-specific JavaScript callbacks.
+- three.js addons that do not yet have Ruby wrappers.
+
+When a feature needs direct JavaScript access, prefer adding a small Ruby wrapper or `Three::Browser` helper first. Use `Three::Browser.js` as the explicit escape hatch for application-specific integrations, and keep it isolated from scene construction code.
+
 ## Current Limits
 
 The browser runtime intentionally does not promise full three.js compatibility yet.
@@ -138,6 +203,7 @@ The browser runtime intentionally does not promise full three.js compatibility y
 - 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 JavaScript boot module is still required to import ES modules and start ruby.wasm, even though ordinary Ruby scene entrypoints can stay Ruby-only.
 - 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.

data/docs/next-work.md

@@ -2,7 +2,7 @@
 
 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.
 
-Last updated: 2026-05-14.
+Last updated: 2026-05-17.
 
 ## Current Position
 
@@ -26,6 +26,9 @@ Recent completed work:
 - `Sprite` / `SpriteMaterial` support with textured billboard marker sync, JSON export/load, resource disposal, and primitives browser smoke coverage.
 - Saved JSON fixture coverage now includes `Sprite` / `SpriteMaterial` so the representative exporter/loader regression fixture matches the current primitive surface.
 - Completed public API and documentation consistency pass for the current browser-first alpha scope.
+- Browser examples were moved to Ruby-only entrypoints that use `Three::Browser` helpers instead of application-level `require "js"` or `JS.global`.
+- Added the `three-rb browser` executable and generator for standalone Ruby-only browser examples.
+- Release install smoke now validates the installed executable and generated browser app shape outside the repository load path.
 - Local release gate and latest `main` CI are green for the `0.1.0` release candidate.
 
 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.
@@ -39,12 +42,13 @@ This is the best next step because:
 - The representative JSON fixture covers the current primitive/material surface, including `Sprite` / `SpriteMaterial`.
 - The public docs now cover release readiness, publishing, browser example coverage, browser runtime boot contract, and the current implemented API scope.
 - `lib/three/version.rb` already contains `0.1.0`.
-- `CHANGELOG.md` intentionally remains `## 0.1.0 - Unreleased` until the owner confirms the release date, but its contents should continue to reflect the current release-candidate surface.
+- `CHANGELOG.md` currently records `## 0.1.0 - 2026-05-15`; if the release date changes before publishing, update that heading during release metadata finalization.
+- The release candidate now includes the Ruby-only browser generator and installed-generator smoke coverage.
 - Further feature scope should wait until after the `0.1.0` release unless an already-advertised example breaks.
 
 ## Scope
 
-For deferred-release maintenance, keep `CHANGELOG.md`, `docs/release-readiness.md`, and this resume point aligned with the implemented release-candidate surface. Do not date the changelog, tag, push, or publish until the release owner confirms the release window.
+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.
 
 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.
 
@@ -60,8 +64,8 @@ Candidate targets, in recommended order when there is no stronger product signal
 
 ## Suggested Implementation Plan
 
-1. While release is deferred, keep the unreleased changelog and release-readiness docs current without changing the version, date, tag, or published artifact.
-2. When release is confirmed, finalize `CHANGELOG.md` with the confirmed release date.
+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.
+2. When release is confirmed, adjust `CHANGELOG.md` only if the confirmed release date differs from the current heading.
 3. Run `bundle exec rake release:preflight`.
 4. Commit the release metadata with a message that does not include co-author trailers.
 5. Publish and tag using `docs/publishing.md`.

data/docs/publishing.md

@@ -1,64 +1,157 @@
 # Publishing
 
-This document records the manual steps for publishing `three-rb`. Do not run the publish step until the release owner has confirmed the version, changelog date, and RubyGems credentials.
+This is the manual release checklist for publishing `three-rb` to RubyGems.
 
-## Preflight
+`three-rb` is the RubyGems package name. The public Ruby require path is `three`, with `three-rb` kept as a compatibility require shim.
 
-Start from a clean `main` branch:
+Do not publish until the release owner has confirmed:
+
+- The target version.
+- The release date for `CHANGELOG.md`.
+- RubyGems credentials with MFA enabled.
+
+## Release Checklist
+
+Run these commands from the repository root.
 
 ```sh
+cd /path/to/three-rb
+```
+
+Choose the target version before starting. If this is not already the version in `lib/three/version.rb`, update that file first.
+
+```ruby
+module Three
+  VERSION = "X.Y.Z"
+end
+```
+
+Set the version being released from the code. All later commands use this value.
+
+```sh
+VERSION="$(ruby -Ilib -e 'require "three/version"; print Three::VERSION')"
+GEM_FILE="three-rb-${VERSION}.gem"
+TAG="v${VERSION}"
+echo "$VERSION"
+echo "$GEM_FILE"
+echo "$TAG"
+```
+
+Start from the latest clean `main`:
+
+```sh
+git switch main
+git pull --ff-only origin main
 git status --short
+```
+
+`git status --short` should be empty before release metadata changes.
+
+Install and audit the Node/browser dependencies:
+
+```sh
 pnpm install --frozen-lockfile --ignore-scripts
 pnpm audit --audit-level moderate
 pnpm audit signatures
 pnpm exec playwright install chromium
+```
+
+Run the full non-publishing release gate:
+
+```sh
 bundle exec rake release:preflight
 ```
 
 `release:preflight` runs Ruby tests, builds and installs the gem into a temporary `GEM_HOME`, runs the install smoke test, runs all browser smoke tests, and builds the gem. It does not publish anything.
 
-## Prepare Release Metadata
+Confirm release metadata:
+
+```sh
+test "$(ruby -Ilib -e 'require "three/version"; print Three::VERSION')" = "$VERSION"
+```
+
+The command must exit successfully. If it fails, fix `VERSION` or `lib/three/version.rb` before continuing. Do not build or publish a gem until the code version is the intended release version.
 
-For version `0.1.0`:
+Update `CHANGELOG.md` from an unreleased heading to the final release date. Replace `$VERSION` with the actual version value:
+
+```md
+## $VERSION - YYYY-MM-DD
+```
 
-1. Confirm `lib/three/version.rb` contains `VERSION = "0.1.0"`.
-2. Change `CHANGELOG.md` from `## 0.1.0 - Unreleased` to the release date.
-3. Run `bundle exec rake release:preflight` again.
-4. Commit the metadata update:
+Run the full gate again after metadata changes:
 
 ```sh
-git add CHANGELOG.md lib/three/version.rb
-git commit -m "Prepare 0.1.0 release"
+bundle exec rake release:preflight
 ```
 
-Skip `lib/three/version.rb` in the commit if the version was already correct.
+Commit the release metadata, including `lib/three/version.rb` when it changed. Do not add co-author trailers.
 
-## Publish
+```sh
+git status --short
+git add -A
+git commit -m "Prepare ${VERSION} release"
+```
 
-Publishing requires RubyGems credentials with MFA enabled.
+Build the exact gem artifact that will be pushed:
 
 ```sh
 gem build three-rb.gemspec
-gem push three-rb-0.1.0.gem
 ```
 
-After RubyGems accepts the gem, create and push the git tag:
+The build output must include the selected version and gem file:
+
+```text
+Name: three-rb
+Version: $VERSION
+File: $GEM_FILE
+```
+
+Publish to RubyGems:
 
 ```sh
-git tag -a v0.1.0 -m "Release 0.1.0"
-git push origin main
-git push origin v0.1.0
+gem push "$GEM_FILE"
 ```
 
-If `gem push` fails, do not create the tag until the published artifact is confirmed.
+RubyGems MFA is required because the gemspec sets `rubygems_mfa_required`. If RubyGems reports that MFA must be enabled, enable MFA on the publishing account and rerun the same `gem push` command.
+
+If `gem push` fails for any reason, stop. Do not create or push the git tag until RubyGems confirms the gem was registered.
 
-## Post-publish
+After RubyGems prints a successful registration message, create and push the git tag:
+
+```sh
+git tag -a "$TAG" -m "Release ${VERSION}"
+git push origin main
+git push origin "$TAG"
+```
 
 Verify the public install path from a clean temporary directory:
 
 ```sh
-gem install three-rb -v 0.1.0
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+gem install three-rb -v "$VERSION"
 ruby -e 'require "three"; puts Three::VERSION'
+ruby -e 'require "three-rb"; puts Three::VERSION'
+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"'
+```
+
+Both Ruby commands must print:
+
+```text
+$VERSION
+```
+
+The `three-rb browser` command must create `examples/browser/quickstart/main.rb`, and the final Ruby command must print:
+
+```text
+generated Ruby entrypoint is Ruby-only
 ```
 
-Then update issue tracker or release notes with the published RubyGems URL.
+Then update issue tracker or release notes with the published RubyGems URL:
+
+```text
+https://rubygems.org/gems/three-rb
+```

data/docs/release-readiness.md

@@ -16,12 +16,13 @@ The `0.1.0` target is complete when all of these are true:
 
 - Scope is frozen to the browser-first alpha surface in this document and `README.md`; no additional material, loader, render-target, postprocessing, WebGPU, XR, native-renderer, or broad compatibility work is required for the release unless an already-advertised example is broken.
 - Public API documentation matches the implemented, tested Ruby API surface loaded by `require "three"`.
+- Ruby-authored browser examples use `Three::Browser` helpers instead of application-level `require "js"` and `JS.global`, and the `three-rb browser` generator can create the same Ruby-only entrypoint shape for standalone apps.
 - Snake-case Ruby methods are the documented API style. Broad camelCase three.js compatibility aliases are deferred until after `0.1.0`.
 - `Three::Exporters::ThreeJSONExporter` and `Three::Loaders::ThreeJSONLoader` continue to round-trip Ruby-authored scenes covered by the saved `test/fixtures/scene_export_v1.json` regression fixture.
 - JavaScript-loaded assets remain opaque `ExternalObject3D` roots for `0.1.0`; transform-level use, renderer traversal helpers, animation mixer usage, and explicit subtree disposal are in scope, while Ruby child mutation inside loaded external roots is out of scope.
 - Every browser example advertised in `README.md` and `examples/browser/README.md` has a matching deterministic Playwright smoke command, and `pnpm test:browser` runs them all.
 - The required gate below passes locally before tagging, and the CI workflow passes on the release commit.
-- Release metadata is final: `lib/three/version.rb` contains `0.1.0`, `CHANGELOG.md` has either the unreleased heading during development or the final release date before publishing, and `docs/publishing.md` has the manual publish steps.
+- Release metadata is final: `lib/three/version.rb` contains the exact target version, `CHANGELOG.md` has either the unreleased heading during development or the final release date before publishing, and `docs/publishing.md` has the manual publish steps.
 
 ## Public Scope
 
@@ -29,6 +30,7 @@ Included in the first public scope:
 
 - Ruby object model for scenes, groups, transforms, cameras, lights, geometries, non-mesh primitives including sprites, common materials including matcap, toon, sprite, and shadow materials, textures, and common math primitives.
 - Browser rendering through `Three::Renderers::ThreeJSRenderer`, ruby.wasm, and `three@0.184.0`.
+- `Three::Browser` helpers and the `three-rb browser` executable for generating standalone Ruby-only browser examples.
 - Dirty-tracked synchronization from Ruby objects into three.js handles.
 - JSON export/load for Ruby-authored scenes.
 - JavaScript-delegated browser integrations for textures, cube maps, RGBE environment maps, glTF, DRACO, animation mixers, OrbitControls, raycasting, instancing, shadows, and initial postprocessing with composer/render/bloom/dot-screen/output passes.
@@ -67,7 +69,7 @@ The release is acceptable when:
 - The required gate passes locally and in CI.
 - `CHANGELOG.md` describes the release as unreleased or tagged with the final date.
 - README documents the browser-first alpha scope and unsupported areas.
-- `bundle exec rake release:gem_smoke` proves the built gem can be installed into a temporary `GEM_HOME` and used without the repository `lib/` path.
+- `bundle exec rake release:gem_smoke` proves the built gem can be installed into a temporary `GEM_HOME`, used without the repository `lib/` path, and run the installed `three-rb browser` generator.
 - `bundle exec rake release:preflight` proves the Ruby tests, install smoke, browser smoke tests, and gem build pass without publishing.
 - Browser smoke tests cover every advertised browser example.
 
@@ -77,7 +79,7 @@ Before expanding feature scope, prefer:
 
 1. Keep release checks fast and deterministic.
 2. Keep fixture-based JSON export/load regression tests current.
-3. Keep `CHANGELOG.md` accurate while it remains under the `0.1.0 - Unreleased` heading.
+3. Keep `CHANGELOG.md` accurate while the next release remains under an unreleased heading.
 4. Improve public docs around browser examples, browser boot, and unsupported APIs; see `docs/next-work.md`.
 5. Add new material classes, postprocessing passes, render targets, or loaders only when a dedicated example and smoke test need them.
 6. Treat KTX2, WebGPU, WebXR, and native rendering as post-0.1 planning items.