three-rb 0.1.0

data/docs/loaded-assets-design.md

@@ -0,0 +1,400 @@
+# Loaded Asset Traversal and Disposal Design
+
+This document records the recommended design for loaded assets such as glTF scenes. It is intended to be self-contained enough to resume implementation even if the conversation context is lost.
+
+## Status Snapshot
+
+Repository state when this decision was written:
+
+- Branch: `main`
+- Relevant recent commits:
+  - `421a89c Add GLTF loader`
+  - `3bc389d Add CubeTexture loader`
+  - `9b6307c Add renderer disposal helper`
+- Current implementation:
+  - `Three::Loaders::GLTFLoader` delegates to JavaScript `GLTFLoader#loadAsync` and can attach JavaScript `DRACOLoader` when `draco_decoder_path:` is configured.
+  - `Three::Loaders::GLTF#scene` is a `Three::ExternalObject3D`.
+  - `Three::ExternalObject3D` stores a loaded JavaScript `Object3D` handle.
+  - `Three::Backends::ThreeJS#materialize` returns that handle directly for `ExternalObject3D`.
+  - `examples/browser/gltf` verifies that a loaded glTF scene can be added to a Ruby-authored scene and rendered.
+
+Important local files:
+
+- `lib/three/loaders/gltf_loader.rb`
+- `lib/three/objects/external_object3d.rb`
+- `lib/three/backends/threejs.rb`
+- `examples/browser/gltf/main.rb`
+- `examples/browser/gltf/smoke_test.mjs`
+- `test/three/loaders/gltf_loader_test.rb`
+- `test/three/objects/external_object3d_test.rb`
+- `test/three/backends/threejs_test.rb`
+
+## Implementation Status
+
+The recommended design has been implemented for the current loaded-asset MVP:
+
+- `ExternalObject3D#add`, `#remove`, and `#clear` now reject Ruby child mutation.
+- `Three::Backends::ThreeJS#traverse_handles` traverses backend object handles without changing `Object3D#traverse`.
+- `Three::Renderers::ThreeJSRenderer#traverse_handles` exposes the same traversal at renderer scope.
+- `Three::Backends::ThreeJS#dispose_subtree` delegates subtree cleanup to the backend adapter.
+- `Three::Renderers::ThreeJSRenderer#dispose_subtree` provides high-level loaded-asset cleanup and defaults `dispose_textures` to `true`.
+- `RubyWasmAdapter` collects unique geometries, materials, common material texture slots, scene background/environment textures, and skeletons before disposing.
+- `FakeThreeJSAdapter` mirrors this behavior for unit tests.
+- `examples/browser/gltf/smoke_test.mjs` verifies that the Ruby renderer API decodes a Draco-compressed glTF fixture, detaches loaded glTF roots, and dispatches geometry/material/texture dispose events.
+
+Remaining work:
+
+- The Ruby material model exposes common `MeshStandardMaterial` PBR texture slots, `MeshPhysicalMaterial` physical texture slots, and `MeshMatcapMaterial` matcap texture slots. Broaden ownership helpers further if additional material classes introduce new texture slots.
+- If future APIs need to inspect or edit loaded child objects, design explicit wrapper types instead of changing `Object3D#traverse`.
+
+## Decision
+
+Keep loaded three.js assets opaque by default.
+
+Do not fully convert a loaded glTF scene into Ruby `Mesh`, `Material`, `BufferGeometry`, `Texture`, `Camera`, or animation objects at this stage. Instead:
+
+1. Use `ExternalObject3D` as an opaque root wrapper around the loaded JavaScript `Object3D`.
+2. Let Ruby own only the attachment point and transform-level concerns for that external root.
+3. Add explicit backend/renderer helpers for traversing and disposing resources inside the external JavaScript subtree.
+4. Preserve the existing pure Ruby `Object3D#traverse` semantics for Ruby-authored objects.
+
+The first target user-facing API should be:
+
+```ruby
+gltf = Three::Loaders::GLTFLoader.new.load("/models/model.gltf")
+scene.add(gltf.scene)
+
+# Later, when the loaded asset is no longer needed:
+renderer.dispose_subtree(gltf.scene, remove: true, dispose_textures: true)
+```
+
+## Rationale
+
+three.js `GLTFLoader` already constructs a complete JavaScript scene graph. Its documented usage is to load a glTF asset and add `gltf.scene` directly to the scene. The returned object also carries `animations`, `scenes`, `cameras`, `asset`, `parser`, and `userData`.
+
+`GLTFLoader` performs non-trivial work that should not be duplicated in Ruby early:
+
+- It returns `Group` scenes, not `THREE.Scene` instances.
+- It handles shared node references and clones reused nodes when necessary.
+- It reuses non-scene resources such as materials, geometries, and textures by reference.
+- It preserves parser associations and glTF extension data.
+- It can involve skins, skeletons, morph targets, animations, compressed geometry, texture transforms, and custom extensions.
+
+Ruby-side full conversion would either lose these semantics or force a large, fragile mirror of three.js loader internals. That is not justified for the current goal: write Ruby scene code and render through three.js in the browser.
+
+## Source Findings
+
+These findings were verified against the local vendored/reference repositories.
+
+three.js facts:
+
+- `Object3D#add` removes an object from its previous parent and attaches it to the new parent.
+- `Object3D#traverse` walks JavaScript children depth-first and discourages modifying the scene graph inside the callback.
+- `BufferGeometry#dispose`, `Material#dispose`, and `Texture#dispose` dispatch disposal events for GPU-related resources.
+- Removing a mesh from a scene does not dispose its geometry or material.
+- Disposing a material does not dispose textures, because textures can be shared.
+- The three.js manual recommends explicit resource tracking for cleanup.
+- Scene-related resources such as `scene.background`, `scene.environment`, and `material.envMap` may leave renderer-internal resources visible in `renderer.info.memory`, even after reachable app resources are disposed.
+
+Local source locations:
+
+- `node_modules/three/src/core/Object3D.js`
+- `node_modules/three/src/core/BufferGeometry.js`
+- `node_modules/three/src/materials/Material.js`
+- `node_modules/three/src/textures/Texture.js`
+- `node_modules/three/examples/jsm/loaders/GLTFLoader.js`
+- `node_modules/three/examples/jsm/utils/SkeletonUtils.js`
+- `~/ghq/github.com/mrdoob/three.js/manual/en/how-to-dispose-of-objects.html`
+- `~/ghq/github.com/mrdoob/three.js/manual/en/cleanup.html`
+
+ruby.wasm facts:
+
+- `JS::Object#await` works in `evalAsync` / `callAsync` contexts.
+- `JS::Object` supports property access with `object[:name]`, method calls with `call`, and array conversion with `to_a`.
+- Passing blocks/procs to JavaScript callbacks is supported enough for traversal-style APIs.
+
+Local source locations:
+
+- `~/ghq/github.com/ruby/ruby.wasm/packages/gems/js/lib/js.rb`
+- `~/ghq/github.com/ruby/ruby.wasm/packages/npm-packages/ruby-wasm-wasi/test/eval_async.test.js`
+
+## Verified Behavior
+
+The existing glTF browser smoke test verifies:
+
+- `Three::Loaders::GLTFLoader` loads `examples/browser/assets/triangle.gltf`.
+- 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.
+
+Additional manual verification was performed in a real headless browser:
+
+```text
+objects=2
+meshes=1
+geometries=1
+materials=1
+textures=0
+geometryDisposeEvents=1
+materialDisposeEvents=1
+textureDisposeEvents=0
+```
+
+This confirmed that a loaded glTF JavaScript subtree can be traversed through its handle and that geometry/material disposal events fire as expected.
+
+## Recommended API Shape
+
+### External Object Traversal
+
+Keep Ruby-authored traversal and JavaScript-loaded traversal separate.
+
+Recommended:
+
+```ruby
+gltf.scene.traverse_handles do |handle|
+  # handle is a JS object in ruby.wasm, or an adapter-provided object in tests.
+end
+```
+
+or renderer/backend scoped:
+
+```ruby
+renderer.traverse_handles(gltf.scene) do |handle|
+  # inspect loaded JS Object3D handles
+end
+```
+
+Do not make `Object3D#traverse` silently enter the JavaScript subtree. That method currently traverses Ruby-owned `Object3D` instances and should remain predictable on MRI Ruby and ruby.wasm.
+
+### External Object Mutability
+
+Guard `ExternalObject3D#add`, `#remove`, and `#clear` for now.
+
+Reason: the backend currently syncs Ruby child-list changes by clearing and re-adding children on the JavaScript handle. If a user adds Ruby children under an `ExternalObject3D`, a later sync can wipe the loaded glTF children. Until mixed Ruby/loaded children are explicitly designed, this should fail loudly.
+
+Recommended behavior:
+
+```ruby
+class Three::ExternalObject3D
+  def add(*)
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+
+  def remove(*)
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+
+  def clear
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+end
+```
+
+Transform properties should continue to work:
+
+```ruby
+gltf.scene.position.y = 1
+gltf.scene.scale.set(2, 2, 2)
+```
+
+### Resource Disposal
+
+Add `dispose_subtree` to renderer/backend instead of putting disposal directly on `GLTF`.
+
+Recommended renderer API:
+
+```ruby
+renderer.dispose_subtree(
+  gltf.scene,
+  remove: true,
+  dispose_geometries: true,
+  dispose_materials: true,
+  dispose_textures: true,
+  dispose_skeletons: true
+)
+```
+
+Default recommendation:
+
+- `remove: true`
+- `dispose_geometries: true`
+- `dispose_materials: true`
+- `dispose_textures: false` at the lowest backend layer
+- `dispose_textures: true` for high-level loaded-asset cleanup helpers
+- `dispose_skeletons: true`, but de-duplicate skeletons
+
+Texture disposal must be explicit because textures can be shared. High-level asset cleanup may opt into it because it is normally called when unloading the whole asset.
+
+### Resource Collection
+
+Disposal should collect unique resources before disposing:
+
+- Object roots:
+  - optionally remove root from parent
+- Geometries:
+  - `object.geometry`
+- Materials:
+  - `object.material`
+  - arrays of materials
+- Textures:
+  - common material slots:
+    - `map`
+    - `normalMap`
+    - `roughnessMap`
+    - `metalnessMap`
+    - `aoMap`
+    - `emissiveMap`
+    - `alphaMap`
+    - `bumpMap`
+    - `displacementMap`
+    - `envMap`
+    - `lightMap`
+    - `specularMap`
+    - `anisotropyMap`
+    - `clearcoatMap`
+    - `clearcoatNormalMap`
+    - `clearcoatRoughnessMap`
+    - `transmissionMap`
+    - `thicknessMap`
+    - `iridescenceMap`
+    - `iridescenceThicknessMap`
+    - `sheenColorMap`
+    - `sheenRoughnessMap`
+    - `specularColorMap`
+    - `specularIntensityMap`
+- Skeletons:
+  - `object.skeleton`
+- Scene resources when disposing a `Scene` or when explicitly requested:
+  - `scene.background`
+  - `scene.environment`
+
+Do not rely on `renderer.info.memory` reaching zero as a strict assertion. three.js may keep internal resources for backgrounds, environments, and other renderer internals.
+
+## Backend Boundary
+
+Prefer implementing loaded-asset traversal/disposal behind adapter methods:
+
+```ruby
+def dispose_subtree(object, **options)
+  handle = materialize(object)
+  @adapter.dispose_object3d_subtree(handle, **options)
+  @handles.delete(object.uuid) if object.respond_to?(:uuid)
+  handle
+end
+```
+
+Adapter responsibilities:
+
+- RubyWasmAdapter:
+  - use JavaScript `Object3D#traverse`
+  - collect JS `Set`s of resources
+  - call `parent.remove(object)` when `remove: true`
+  - call `dispose()` on collected resources
+- FakeThreeJSAdapter:
+  - provide equivalent behavior for hash handles
+  - record calls for unit tests
+
+This keeps browser-specific JavaScript traversal out of the pure Ruby object model.
+
+## Rejected Alternatives
+
+### Full Ruby Conversion of glTF
+
+Rejected for now.
+
+Why:
+
+- It would require mirroring too many three.js loader semantics.
+- It risks breaking shared references, skins, animations, extension metadata, and parser associations.
+- It increases maintenance burden without improving the current browser-first MVP.
+
+### Make `ExternalObject3D#traverse` Enter the JS Subtree
+
+Rejected for now.
+
+Why:
+
+- It changes the meaning of existing Ruby traversal.
+- It makes behavior runtime-dependent: MRI Ruby cannot traverse JS handles.
+- It hides expensive JS bridge calls behind a familiar pure Ruby method.
+
+### Dispose Everything Automatically on Remove
+
+Rejected.
+
+Why:
+
+- three.js explicitly separates removal from disposal.
+- Geometry, material, texture, and skeleton resources can be shared.
+- Automatic disposal would surprise users and could break reused assets.
+
+## Implementation Plan
+
+1. Guard `ExternalObject3D#add`, `#remove`, and `#clear`.
+2. Add backend adapter support for traversing an external JS `Object3D` handle.
+3. Add resource collection in `RubyWasmAdapter`.
+4. Add `Three::Backends::ThreeJS#dispose_subtree`.
+5. Add `Three::Renderers::ThreeJSRenderer#dispose_subtree`.
+6. Add unit tests with `FakeThreeJSAdapter`.
+7. Add browser smoke coverage to `examples/browser/gltf/smoke_test.mjs`:
+   - attach disposal listeners to loaded geometry/material
+   - call `renderer.dispose_subtree(gltf.scene, remove: true, dispose_textures: true)`
+   - assert geometry/material dispose events fired
+   - assert root was removed from parent
+8. Update `docs/implementation-plan.md` current status and next tasks.
+
+## Suggested First Patch
+
+Implement only the guard first:
+
+```ruby
+class Three::ExternalObject3D < Object3D
+  def add(*)
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+
+  def remove(*)
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+
+  def clear
+    raise NotImplementedError, "ExternalObject3D does not support Ruby child mutation yet"
+  end
+end
+```
+
+Tests:
+
+```sh
+ruby -Itest test/three/objects/external_object3d_test.rb
+bundle exec rake test
+pnpm test:browser:gltf
+```
+
+## Validation Commands
+
+After implementing traversal/disposal helpers, run:
+
+```sh
+bundle exec rake test
+pnpm test:browser
+pnpm audit --audit-level moderate
+pnpm audit signatures
+gem build three-rb.gemspec --output /private/tmp/three-rb-check.gem
+git diff --check
+```
+
+If the browser smoke tests fail with a local server sandbox error, rerun the same pnpm command with the approved escalated prefix.
+
+## Resume Checklist
+
+If work resumes from this document alone:
+
+1. Read the status snapshot and decision sections above before editing code.
+2. Confirm the repository state with `git status --short --branch`.
+3. Start with the implementation plan in order unless the current code already includes some steps.
+4. Keep `Object3D#traverse` Ruby-only.
+5. Keep loaded glTF internals opaque unless a later design explicitly changes that.
+6. Add disposal behavior behind backend/adapter APIs, not directly inside the pure Ruby object graph.
+7. Use pnpm-managed browser commands for browser verification.
+8. Update this document if implementation results force a design change.

data/docs/next-work.md

@@ -0,0 +1,107 @@
+# Next Work
+
+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.
+
+## Current Position
+
+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.
+
+Recent completed work:
+
+- `MeshPhysicalMaterial` support.
+- `RGBELoader` / `RGBETexture` support.
+- `DRACOLoader` integration through `GLTFLoader#draco_decoder_path`.
+- Initial postprocessing support with `EffectComposer`, `RenderPass`, and `UnrealBloomPass`.
+- Release readiness checks, gem install smoke, release preflight, and publishing documentation.
+- Saved JSON export/load fixture regression coverage for `Three::Exporters::ThreeJSONExporter` and `Three::Loaders::ThreeJSONLoader`.
+- Browser examples overview and smoke command map for cube, composition, textures, cubemap, glTF, serialization, picking, primitives, and postprocessing.
+- Browser runtime guide documenting the current ruby.wasm, import-map, `globalThis.THREE`, and `Three::Renderers::ThreeJSRenderer` boot contract.
+- `Three::Postprocessing::OutputPass` support in the postprocessing composer example and browser smoke test.
+- `MeshMatcapMaterial` support with matcap texture-slot sync, JSON export/load, resource disposal, and texture browser smoke coverage.
+- `ShadowMaterial` support with backend sync, JSON export/load, and composition browser smoke coverage.
+- `MeshToonMaterial` support with gradient-map texture-slot sync, JSON export/load, resource disposal, and texture browser smoke coverage.
+- `Three::Postprocessing::DotScreenPass` support with composer integration, uniform update coverage, browser runtime boot contract updates, and postprocessing browser smoke coverage.
+- `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.
+- 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.
+
+## Recommended Next Task
+
+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.
+
+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.
+- 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.
+
+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.
+
+After the release is published, pick one feature target and keep the change small enough to verify through one browser example.
+
+Candidate targets, in recommended order when there is no stronger product signal:
+
+1. Another small primitive or material workflow only when it reuses existing object/material parameter, JSON, backend sync, and browser smoke patterns. After `Sprite` / `SpriteMaterial`, prefer this only for a concrete example gap rather than API breadth.
+2. Another small postprocessing pass only when it can extend `examples/browser/postprocessing` without adding render targets. After `DotScreenPass`, prefer this only for a specific visual workflow rather than pass count.
+3. Render target support, but only with a focused example that proves why it is needed.
+4. A new addon loader only when a committed fixture requires it.
+5. KTX2 loader after texture-compression fixture coverage and decoder-path handling are planned.
+
+## 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.
+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`.
+6. After publishing, start the next feature from a user-visible workflow and choose exactly one feature target.
+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.
+8. Add or extend one browser example and keep `examples/browser/README.md` in sync.
+9. Add or update a deterministic Playwright smoke command in `package.json`.
+10. Run Ruby tests, the affected browser smoke test, `bundle exec rake release:gem_smoke`, and `bundle exec rake release:preflight` before release work.
+
+## Acceptance Criteria
+
+- `bundle exec rake test` passes.
+- The chosen feature has one dedicated or clearly extended browser example.
+- `examples/browser/README.md` documents the new coverage.
+- `package.json` has a matching `test:browser:*` command when a new example is added.
+- The affected browser smoke test passes.
+- `bundle exec rake release:gem_smoke` still passes.
+
+Optional after the next feature task:
+
+- Run `bundle exec rake release:preflight` before release work or when browser/runtime code changed.
+- Run `pnpm benchmark:browser` only if synchronization or renderer internals changed.
+
+## What Not To Do Next
+
+Do not prioritize these without a clear product need:
+
+- KTX2 loader.
+- Additional postprocessing passes.
+- Render target API.
+- WebGPU renderer.
+- Native renderer.
+- Broad public API documentation beyond the current README, release readiness, implementation plan, browser examples overview, and browser runtime guide.
+
+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.
+
+## After This Task
+
+After the next feature task, reassess in this order:
+
+1. Keep the release gate passing after each change.
+2. Decide whether the new example reveals a natural follow-up feature.
+3. Delay Phase 9 native renderer work until the browser-first API is stable enough to justify a second renderer target.

data/docs/publishing.md

@@ -0,0 +1,64 @@
+# 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.
+
+## Preflight
+
+Start from a clean `main` branch:
+
+```sh
+git status --short
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm audit --audit-level moderate
+pnpm audit signatures
+pnpm exec playwright install chromium
+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
+
+For version `0.1.0`:
+
+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:
+
+```sh
+git add CHANGELOG.md lib/three/version.rb
+git commit -m "Prepare 0.1.0 release"
+```
+
+Skip `lib/three/version.rb` in the commit if the version was already correct.
+
+## Publish
+
+Publishing requires RubyGems credentials with MFA enabled.
+
+```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:
+
+```sh
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin main
+git push origin v0.1.0
+```
+
+If `gem push` fails, do not create the tag until the published artifact is confirmed.
+
+## Post-publish
+
+Verify the public install path from a clean temporary directory:
+
+```sh
+gem install three-rb -v 0.1.0
+ruby -e 'require "three"; puts Three::VERSION'
+```
+
+Then update issue tracker or release notes with the published RubyGems URL.

data/docs/release-readiness.md

@@ -0,0 +1,83 @@
+# Release Readiness
+
+This document defines the quality gate for publishing the first public `three-rb` release.
+
+## Current Position
+
+The project is past the original MVP. It is now in Phase 8, renderer maturity: core Ruby scene authoring, browser rendering, JSON export/load, interaction, asset loading, instancing, picking, shadows, and initial postprocessing are implemented and covered by unit or browser smoke tests.
+
+The first public release should be positioned as browser-first alpha. The stable promise is narrow: users can build Ruby-authored scenes and render them in a browser through ruby.wasm and the delegated three.js backend. Native rendering and full three.js API compatibility are not part of the first release.
+
+## 0.1.0 Target and Completion Definition
+
+The current release plan targets `0.1.0` as the first public browser-first alpha. This is not a `1.0` stable API commitment. A future `1.0` should get a separate stability plan covering compatibility guarantees, deprecation policy, support windows, and any non-browser renderer commitment.
+
+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"`.
+- 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.
+
+## Public Scope
+
+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`.
+- 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.
+- Browser examples and smoke tests that verify visible rendering paths.
+
+Explicitly out of scope for the first public scope:
+
+- A native Ruby renderer.
+- Full three.js API coverage.
+- Compatibility aliases for every camelCase three.js API.
+- Broad addon coverage beyond examples that are already tested.
+- WebGPU, WebXR, node materials, editor integration, physics, and production asset pipeline guarantees.
+
+## Required Gate
+
+Run these before publishing or tagging:
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm audit --audit-level moderate
+pnpm audit signatures
+pnpm exec playwright install chromium
+bundle exec rake release:preflight
+```
+
+Optional but recommended when renderer internals change:
+
+```sh
+pnpm benchmark:browser
+```
+
+## Release Criteria
+
+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:preflight` proves the Ruby tests, install smoke, browser smoke tests, and gem build pass without publishing.
+- Browser smoke tests cover every advertised browser example.
+
+## Recommended Next Work
+
+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.
+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.