three-rb 0.1.0

data/examples/browser/README.md

@@ -0,0 +1,54 @@
+# Browser Examples
+
+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`.
+
+## Run Examples
+
+Install browser dependencies and serve the repository root:
+
+```sh
+pnpm install
+ruby -run -e httpd . -p 8000
+```
+
+Open an example URL:
+
+```text
+http://localhost:8000/examples/browser/cube/
+http://localhost:8000/examples/browser/composition/
+http://localhost:8000/examples/browser/textures/
+http://localhost:8000/examples/browser/cubemap/
+http://localhost:8000/examples/browser/gltf/
+http://localhost:8000/examples/browser/serialization/
+http://localhost:8000/examples/browser/picking/
+http://localhost:8000/examples/browser/primitives/
+http://localhost:8000/examples/browser/postprocessing/
+```
+
+## Smoke Tests
+
+Run all browser smoke tests:
+
+```sh
+pnpm install
+pnpm exec playwright install chromium
+pnpm test:browser
+```
+
+Run one smoke test by using the command listed in the table below.
+
+| Example | Primary APIs covered | Smoke command | Why it exists |
+| --- | --- | --- | --- |
+| `examples/browser/cube/` | `Scene`, `PerspectiveCamera`, `BoxGeometry`, `Mesh`, `MeshBasicMaterial`, `ThreeJSRenderer`, animation loop | `pnpm test:browser:cube` | Verifies the smallest Ruby-authored scene can boot through ruby.wasm and draw nonblank WebGL pixels through the three.js renderer path. |
+| `examples/browser/composition/` | `OrthographicCamera`, ambient/directional/point/hemisphere lights, shadows, `ShadowMaterial`, `Group`, `InstancedMesh`, `TextureLoader`, `OrbitControls`, material/texture disposal | `pnpm test:browser:composition` | Exercises the broad scene-composition path used by richer browser scenes, including dynamic material updates and camera controls. |
+| `examples/browser/textures/` | `TextureLoader`, `RGBELoader`, repeat/wrap/filter/UV-transform settings, `MeshPhysicalMaterial`, `MeshMatcapMaterial`, `MeshToonMaterial`, physical, matcap, and toon texture slots, scene environment | `pnpm test:browser:textures` | Verifies browser texture loading, HDR environment synchronization, and the current material texture bridge. |
+| `examples/browser/cubemap/` | `CubeTextureLoader`, `CubeTexture`, scene `background`, scene `environment`, reflective `MeshStandardMaterial` | `pnpm test:browser:cubemap` | Keeps cubemap background/environment behavior covered separately from ordinary 2D texture loading. |
+| `examples/browser/gltf/` | `GLTFLoader`, `DRACOLoader` decoder path, loaded external scenes, `AnimationMixer`, `Clock`, loaded subtree disposal | `pnpm test:browser:gltf` | Verifies that external assets can be loaded, animated, attached to Ruby scenes, and disposed through the renderer API. |
+| `examples/browser/serialization/` | `ThreeJSONExporter`, `ThreeJSONLoader`, deterministic ids, shared geometry/material/texture resources, loaded scene rendering | `pnpm test:browser:serialization` | Confirms exported Ruby scenes round-trip through JSON and render after loading. |
+| `examples/browser/picking/` | `Raycaster`, pointer-to-camera coordinates, intersection mapping back to Ruby `Object3D`, selected material updates | `pnpm test:browser:picking` | Verifies browser event coordinates can drive Ruby-side picking and mutate rendered objects. |
+| `examples/browser/primitives/` | `BufferGeometry`, `Float32BufferAttribute`, `Line`, `Points`, `Sprite`, `LineBasicMaterial`, `PointsMaterial`, `SpriteMaterial` | `pnpm test:browser:primitives` | Covers non-`Mesh` primitive rendering, generic buffer attribute synchronization, and textured billboard markers. |
+| `examples/browser/postprocessing/` | `EffectComposer`, `RenderPass`, `UnrealBloomPass`, `DotScreenPass`, `OutputPass`, composer sizing, pass property/uniform updates, `composer.render` | `pnpm test:browser:postprocessing` | Verifies the explicit postprocessing render path stays separate from direct renderer rendering and remains smoke-tested. |
+
+## Adding Browser Coverage
+
+New browser-facing features should add or extend one of these examples and include deterministic smoke coverage. Prefer extending an existing example when the feature strengthens the same workflow; add a new example when it introduces a distinct API surface such as a new loader family, render target workflow, or postprocessing pipeline.

data/examples/browser/assets/animated_triangle.gltf

@@ -0,0 +1,123 @@
+{
+  "asset": {
+    "version": "2.0",
+    "generator": "three-rb animated smoke asset"
+  },
+  "scene": 0,
+  "scenes": [
+    {
+      "nodes": [0]
+    }
+  ],
+  "nodes": [
+    {
+      "name": "AnimatedRubyTriangle",
+      "mesh": 0,
+      "rotation": [0, 0, 0, 1]
+    }
+  ],
+  "meshes": [
+    {
+      "name": "AnimatedRubyTriangleMesh",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 0
+          },
+          "material": 0
+        }
+      ]
+    }
+  ],
+  "materials": [
+    {
+      "name": "AnimatedRubyTriangleMaterial",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [0.35, 0.78, 1.0, 1.0],
+        "metallicFactor": 0.0,
+        "roughnessFactor": 0.45
+      },
+      "doubleSided": true
+    }
+  ],
+  "animations": [
+    {
+      "name": "TriangleSpin",
+      "channels": [
+        {
+          "sampler": 0,
+          "target": {
+            "node": 0,
+            "path": "rotation"
+          }
+        }
+      ],
+      "samplers": [
+        {
+          "input": 1,
+          "output": 2,
+          "interpolation": "LINEAR"
+        }
+      ]
+    }
+  ],
+  "buffers": [
+    {
+      "uri": "data:application/octet-stream;base64,AAAAAAAAgD8AAAAAAACAvwAAgL8AAAAAAACAPwAAgL8AAAAA",
+      "byteLength": 36
+    },
+    {
+      "uri": "data:application/octet-stream;base64,AAAAAAAAAEA=",
+      "byteLength": 8
+    },
+    {
+      "uri": "data:application/octet-stream;base64,AAAAAAAAAAAAAAAAAACAPwAAAAAAAIA/AAAAAAAAAAA=",
+      "byteLength": 32
+    }
+  ],
+  "bufferViews": [
+    {
+      "buffer": 0,
+      "byteOffset": 0,
+      "byteLength": 36,
+      "target": 34962
+    },
+    {
+      "buffer": 1,
+      "byteOffset": 0,
+      "byteLength": 8
+    },
+    {
+      "buffer": 2,
+      "byteOffset": 0,
+      "byteLength": 32
+    }
+  ],
+  "accessors": [
+    {
+      "bufferView": 0,
+      "byteOffset": 0,
+      "componentType": 5126,
+      "count": 3,
+      "type": "VEC3",
+      "min": [-1.0, -1.0, 0.0],
+      "max": [1.0, 1.0, 0.0]
+    },
+    {
+      "bufferView": 1,
+      "byteOffset": 0,
+      "componentType": 5126,
+      "count": 2,
+      "type": "SCALAR",
+      "min": [0.0],
+      "max": [2.0]
+    },
+    {
+      "bufferView": 2,
+      "byteOffset": 0,
+      "componentType": 5126,
+      "count": 2,
+      "type": "VEC4"
+    }
+  ]
+}

data/examples/browser/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/assets/compressed_triangle.gltf

@@ -0,0 +1,74 @@
+{
+  "asset": {
+    "version": "2.0",
+    "generator": "three-rb draco smoke asset"
+  },
+  "extensionsUsed": ["KHR_draco_mesh_compression"],
+  "extensionsRequired": ["KHR_draco_mesh_compression"],
+  "scene": 0,
+  "scenes": [
+    {
+      "nodes": [0]
+    }
+  ],
+  "nodes": [
+    {
+      "name": "CompressedRubyTriangle",
+      "mesh": 0
+    }
+  ],
+  "meshes": [
+    {
+      "name": "CompressedRubyTriangleMesh",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 0
+          },
+          "extensions": {
+            "KHR_draco_mesh_compression": {
+              "bufferView": 0,
+              "attributes": {
+                "POSITION": 0
+              }
+            }
+          },
+          "material": 0
+        }
+      ]
+    }
+  ],
+  "materials": [
+    {
+      "name": "CompressedRubyTriangleMaterial",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [1.0, 0.62, 0.28, 1.0],
+        "metallicFactor": 0.0,
+        "roughnessFactor": 0.35
+      },
+      "doubleSided": true
+    }
+  ],
+  "buffers": [
+    {
+      "uri": "data:application/octet-stream;base64,RFJBQ08CAgEBAAAAAwEAAQAAAQf/AREB/wAAAQAJAwAAAgEBAQAPA60qL1UVA6B6gUj/HwAAAAAAAAD/PwAAAACAvwAAgL8AAAAAAAAAQA4=",
+      "byteLength": 80
+    }
+  ],
+  "bufferViews": [
+    {
+      "buffer": 0,
+      "byteOffset": 0,
+      "byteLength": 80
+    }
+  ],
+  "accessors": [
+    {
+      "componentType": 5126,
+      "count": 3,
+      "type": "VEC3",
+      "min": [-1.0, -1.0, 0.0],
+      "max": [1.0, 1.0, 0.0]
+    }
+  ]
+}

data/examples/browser/assets/studio.hdr

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

data/examples/browser/assets/triangle.gltf

@@ -0,0 +1,67 @@
+{
+  "asset": {
+    "version": "2.0",
+    "generator": "three-rb smoke asset"
+  },
+  "scene": 0,
+  "scenes": [
+    {
+      "nodes": [0]
+    }
+  ],
+  "nodes": [
+    {
+      "name": "RubyTriangle",
+      "mesh": 0
+    }
+  ],
+  "meshes": [
+    {
+      "name": "RubyTriangleMesh",
+      "primitives": [
+        {
+          "attributes": {
+            "POSITION": 0
+          },
+          "material": 0
+        }
+      ]
+    }
+  ],
+  "materials": [
+    {
+      "name": "RubyTriangleMaterial",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [0.35, 0.78, 1.0, 1.0],
+        "metallicFactor": 0.0,
+        "roughnessFactor": 0.45
+      },
+      "doubleSided": true
+    }
+  ],
+  "buffers": [
+    {
+      "uri": "data:application/octet-stream;base64,AAAAAAAAgD8AAAAAAACAvwAAgL8AAAAAAACAPwAAgL8AAAAA",
+      "byteLength": 36
+    }
+  ],
+  "bufferViews": [
+    {
+      "buffer": 0,
+      "byteOffset": 0,
+      "byteLength": 36,
+      "target": 34962
+    }
+  ],
+  "accessors": [
+    {
+      "bufferView": 0,
+      "byteOffset": 0,
+      "componentType": 5126,
+      "count": 3,
+      "type": "VEC3",
+      "min": [-1.0, -1.0, 0.0],
+      "max": [1.0, 1.0, 0.0]
+    }
+  ]
+}

data/examples/browser/composition/README.md

@@ -0,0 +1,35 @@
+# Browser Composition Example
+
+This example renders a Ruby-authored scene through ruby.wasm and the JavaScript three.js renderer. It uses ambient, directional, point, and hemisphere lights, directional shadow mapping, a `PlaneGeometry` backdrop and shadow catcher, `SphereGeometry`, grouped child meshes, `TextureLoader` repeat/wrap/filter settings, `MeshLambertMaterial`, `MeshPhongMaterial`, `MeshStandardMaterial`, `MeshNormalMaterial`, `ShadowMaterial`, `OrbitControls`, backend material/texture disposal, and a material color update in the animation loop.
+
+Install browser dependencies and serve the repository root over HTTP:
+
+```sh
+pnpm install
+ruby -run -e httpd . -p 8000
+```
+
+Then open:
+
+```text
+http://localhost:8000/examples/browser/composition/
+```
+
+The repository root must be served, not only this directory, because `boot.mjs` loads browser packages from `node_modules/` and `main.rb` loads the library source from `lib/`.
+
+## Browser Smoke Test
+
+Install the optional Node dependency and browser binary:
+
+```sh
+pnpm install
+pnpm exec playwright install chromium
+```
+
+Run the browser smoke test:
+
+```sh
+pnpm test:browser:composition
+```
+
+The smoke test serves the repository root, waits for the Ruby scene to reach `Running`, samples the WebGL canvas for nonblank pixels, verifies ambient/directional/point/hemisphere lights, directional shadow mapping, grouped meshes, `PlaneGeometry`, `SphereGeometry`, `TextureLoader` repeat/wrap/filter settings, `MeshLambertMaterial`, `MeshPhongMaterial`, `MeshStandardMaterial`, `MeshNormalMaterial`, `ShadowMaterial`, backend material/texture disposal, and `OrbitControls`, then confirms that material changes and camera drag controls reach the renderer.

data/examples/browser/composition/boot.mjs

@@ -0,0 +1,6 @@
+import { bootRubyExample } from "../shared/boot.mjs";
+
+await bootRubyExample({
+  main: "examples/browser/composition/main",
+  clearColor: 0x0f1419
+});

data/examples/browser/composition/index.html

@@ -0,0 +1,136 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>three-rb composition</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family:
+          Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+          "Segoe UI", sans-serif;
+        background: #0f1419;
+        color: #eef3f7;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+      }
+
+      body {
+        display: grid;
+        place-items: stretch;
+        overflow: hidden;
+      }
+
+      .viewport {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        min-width: 320px;
+        min-height: 320px;
+        background:
+          linear-gradient(rgba(255, 255, 255, 0.04) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(255, 255, 255, 0.035) 1px, transparent 1px),
+          linear-gradient(135deg, #0f1419 0%, #17221e 48%, #151820 100%);
+        background-size: 36px 36px, 36px 36px, auto;
+      }
+
+      canvas {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+
+      .hud {
+        position: absolute;
+        top: 16px;
+        left: 16px;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        max-width: calc(100% - 32px);
+        padding: 8px 10px;
+        border: 1px solid rgba(255, 255, 255, 0.14);
+        border-radius: 6px;
+        background: rgba(9, 13, 17, 0.72);
+        box-shadow: 0 12px 30px rgba(0, 0, 0, 0.24);
+        color: #dce7ef;
+        font-size: 13px;
+        line-height: 1.3;
+        backdrop-filter: blur(10px);
+      }
+
+      .status-dot {
+        width: 8px;
+        height: 8px;
+        flex: 0 0 auto;
+        border-radius: 999px;
+        background: #f2b84b;
+        box-shadow: 0 0 14px rgba(242, 184, 75, 0.72);
+      }
+
+      .status-dot[data-state="running"] {
+        background: #60d394;
+        box-shadow: 0 0 14px rgba(96, 211, 148, 0.72);
+      }
+
+      .status-dot[data-state="error"] {
+        background: #f15b5b;
+        box-shadow: 0 0 14px rgba(241, 91, 91, 0.72);
+      }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "@bjorn3/browser_wasi_shim": "/node_modules/@bjorn3/browser_wasi_shim/dist/index.js",
+          "@ruby/wasm-wasi/browser": "/node_modules/@ruby/wasm-wasi/dist/esm/browser.js",
+          "three": "/node_modules/three/build/three.module.js",
+          "three/addons/": "/node_modules/three/examples/jsm/"
+        }
+      }
+    </script>
+    <script type="module">
+      const status = document.querySelector("#status");
+      const statusDot = document.querySelector("#status-dot");
+
+      globalThis.__threeRbSetStatus = (message, state) => {
+        if (status) status.textContent = message;
+        if (statusDot) statusDot.dataset.state = state;
+      };
+
+      globalThis.__threeRbBootFailed = (message) => {
+        globalThis.__threeRbSetStatus(message, "error");
+      };
+
+      globalThis.addEventListener("error", (event) => {
+        globalThis.__threeRbBootFailed(event.message || "Browser error");
+      });
+
+      globalThis.addEventListener("unhandledrejection", (event) => {
+        const reason = event.reason;
+        globalThis.__threeRbBootFailed(reason && reason.message ? reason.message : "Ruby boot failed");
+      });
+
+      globalThis.__threeRbSetStatus("Loading ruby.wasm", "loading");
+    </script>
+    <script type="module" src="./boot.mjs"></script>
+  </head>
+  <body>
+    <main class="viewport" id="viewport">
+      <canvas id="scene" data-testid="scene-canvas"></canvas>
+      <div class="hud" aria-live="polite">
+        <span class="status-dot" id="status-dot"></span>
+        <span id="status" data-testid="status">Loading ruby.wasm</span>
+      </div>
+    </main>
+  </body>
+</html>