RubyGems - three-rb - Versions diffs - 0.1.0 - Mend

three-rb 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (145) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +19 -0
data/LICENSE +21 -0
data/README.md +153 -0
data/docs/browser-runtime.md +153 -0
data/docs/implementation-plan.md +874 -0
data/docs/loaded-assets-design.md +400 -0
data/docs/next-work.md +107 -0
data/docs/publishing.md +64 -0
data/docs/release-readiness.md +83 -0
data/examples/browser/README.md +54 -0
data/examples/browser/assets/animated_triangle.gltf +123 -0
data/examples/browser/assets/checker.svg +11 -0
data/examples/browser/assets/compressed_triangle.gltf +74 -0
data/examples/browser/assets/studio.hdr +5 -0
data/examples/browser/assets/triangle.gltf +67 -0
data/examples/browser/composition/README.md +35 -0
data/examples/browser/composition/boot.mjs +6 -0
data/examples/browser/composition/index.html +136 -0
data/examples/browser/composition/main.rb +216 -0
data/examples/browser/composition/smoke_test.mjs +266 -0
data/examples/browser/cube/README.md +41 -0
data/examples/browser/cube/boot.mjs +6 -0
data/examples/browser/cube/index.html +142 -0
data/examples/browser/cube/main.rb +62 -0
data/examples/browser/cube/smoke_test.mjs +99 -0
data/examples/browser/cubemap/README.md +23 -0
data/examples/browser/cubemap/boot.mjs +6 -0
data/examples/browser/cubemap/index.html +142 -0
data/examples/browser/cubemap/main.rb +84 -0
data/examples/browser/cubemap/smoke_test.mjs +91 -0
data/examples/browser/gltf/README.md +23 -0
data/examples/browser/gltf/boot.mjs +6 -0
data/examples/browser/gltf/index.html +142 -0
data/examples/browser/gltf/main.rb +105 -0
data/examples/browser/gltf/smoke_test.mjs +162 -0
data/examples/browser/picking/README.md +33 -0
data/examples/browser/picking/boot.mjs +6 -0
data/examples/browser/picking/index.html +142 -0
data/examples/browser/picking/main.rb +113 -0
data/examples/browser/picking/smoke_test.mjs +78 -0
data/examples/browser/postprocessing/README.md +26 -0
data/examples/browser/postprocessing/boot.mjs +6 -0
data/examples/browser/postprocessing/index.html +142 -0
data/examples/browser/postprocessing/main.rb +117 -0
data/examples/browser/postprocessing/smoke_test.mjs +121 -0
data/examples/browser/primitives/README.md +33 -0
data/examples/browser/primitives/boot.mjs +6 -0
data/examples/browser/primitives/index.html +142 -0
data/examples/browser/primitives/main.rb +116 -0
data/examples/browser/primitives/smoke_test.mjs +113 -0
data/examples/browser/serialization/README.md +33 -0
data/examples/browser/serialization/boot.mjs +6 -0
data/examples/browser/serialization/index.html +142 -0
data/examples/browser/serialization/main.rb +97 -0
data/examples/browser/serialization/smoke_test.mjs +67 -0
data/examples/browser/shared/boot.mjs +79 -0
data/examples/browser/shared/smoke_test_helpers.mjs +151 -0
data/examples/browser/textures/README.md +35 -0
data/examples/browser/textures/boot.mjs +6 -0
data/examples/browser/textures/index.html +142 -0
data/examples/browser/textures/main.rb +142 -0
data/examples/browser/textures/smoke_test.mjs +189 -0
data/lib/three/animation/animation_action.rb +57 -0
data/lib/three/animation/animation_clip.rb +22 -0
data/lib/three/animation/animation_mixer.rb +43 -0
data/lib/three/backends/base.rb +87 -0
data/lib/three/backends/threejs/materialization.rb +143 -0
data/lib/three/backends/threejs/parameters.rb +97 -0
data/lib/three/backends/threejs/resource_management.rb +69 -0
data/lib/three/backends/threejs/ruby_wasm_adapter.rb +873 -0
data/lib/three/backends/threejs/synchronization.rb +224 -0
data/lib/three/backends/threejs.rb +365 -0
data/lib/three/cameras/camera.rb +39 -0
data/lib/three/cameras/orthographic_camera.rb +107 -0
data/lib/three/cameras/perspective_camera.rb +137 -0
data/lib/three/constants.rb +40 -0
data/lib/three/controls/orbit_controls.rb +118 -0
data/lib/three/core/buffer_attribute.rb +151 -0
data/lib/three/core/buffer_geometry.rb +181 -0
data/lib/three/core/clock.rb +58 -0
data/lib/three/core/event_dispatcher.rb +57 -0
data/lib/three/core/layers.rb +75 -0
data/lib/three/core/object3d.rb +331 -0
data/lib/three/core/raycaster.rb +73 -0
data/lib/three/dirty.rb +58 -0
data/lib/three/exporters/three_json_exporter.rb +187 -0
data/lib/three/geometries/box_geometry.rb +97 -0
data/lib/three/geometries/plane_geometry.rb +70 -0
data/lib/three/geometries/sphere_geometry.rb +107 -0
data/lib/three/lights/ambient_light.rb +12 -0
data/lib/three/lights/directional_light.rb +38 -0
data/lib/three/lights/hemisphere_light.rb +34 -0
data/lib/three/lights/light.rb +85 -0
data/lib/three/lights/point_light.rb +33 -0
data/lib/three/loaders/cube_texture_loader.rb +13 -0
data/lib/three/loaders/gltf_loader.rb +48 -0
data/lib/three/loaders/rgbe_loader.rb +15 -0
data/lib/three/loaders/texture_loader.rb +13 -0
data/lib/three/loaders/three_json_loader.rb +409 -0
data/lib/three/materials/line_basic_material.rb +65 -0
data/lib/three/materials/material.rb +158 -0
data/lib/three/materials/mesh_basic_material.rb +64 -0
data/lib/three/materials/mesh_lambert_material.rb +71 -0
data/lib/three/materials/mesh_matcap_material.rb +86 -0
data/lib/three/materials/mesh_normal_material.rb +42 -0
data/lib/three/materials/mesh_phong_material.rb +119 -0
data/lib/three/materials/mesh_physical_material.rb +155 -0
data/lib/three/materials/mesh_standard_material.rb +149 -0
data/lib/three/materials/mesh_toon_material.rb +98 -0
data/lib/three/materials/points_material.rb +74 -0
data/lib/three/materials/shadow_material.rb +45 -0
data/lib/three/materials/sprite_material.rb +75 -0
data/lib/three/math/color.rb +133 -0
data/lib/three/math/euler.rb +197 -0
data/lib/three/math/math_utils.rb +36 -0
data/lib/three/math/matrix3.rb +255 -0
data/lib/three/math/matrix4.rb +448 -0
data/lib/three/math/quaternion.rb +277 -0
data/lib/three/math/vector2.rb +95 -0
data/lib/three/math/vector3.rb +396 -0
data/lib/three/objects/external_object3d.rb +28 -0
data/lib/three/objects/group.rb +12 -0
data/lib/three/objects/instanced_mesh.rb +110 -0
data/lib/three/objects/line.rb +41 -0
data/lib/three/objects/mesh.rb +45 -0
data/lib/three/objects/points.rb +41 -0
data/lib/three/objects/sprite.rb +57 -0
data/lib/three/postprocessing/dot_screen_pass.rb +83 -0
data/lib/three/postprocessing/effect_composer.rb +56 -0
data/lib/three/postprocessing/output_pass.rb +40 -0
data/lib/three/postprocessing/render_pass.rb +42 -0
data/lib/three/postprocessing/unreal_bloom_pass.rb +56 -0
data/lib/three/renderers/renderer.rb +11 -0
data/lib/three/renderers/threejs_renderer.rb +85 -0
data/lib/three/scenes/scene.rb +29 -0
data/lib/three/textures/cube_texture.rb +72 -0
data/lib/three/textures/rgbe_texture.rb +45 -0
data/lib/three/textures/texture.rb +200 -0
data/lib/three/version.rb +5 -0
data/lib/three-rb.rb +3 -0
data/lib/three.rb +77 -0
data/package.json +30 -0
data/pnpm-lock.yaml +86 -0
metadata +216 -0

data/examples/browser/postprocessing/index.html ADDED Viewed

@@ -0,0 +1,142 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>three-rb postprocessing</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family:
+          Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+          "Segoe UI", sans-serif;
+        background: #0a0d12;
+        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.035) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(255, 255, 255, 0.035) 1px, transparent 1px),
+          linear-gradient(135deg, #0a0d12 0%, #101820 52%, #0d1118 100%);
+        background-size: 32px 32px, 32px 32px, 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(10, 14, 18, 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: #4ed08f;
+        box-shadow: 0 0 14px rgba(78, 208, 143, 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.setTimeout(() => {
+        if (status && status.textContent === "Loading ruby.wasm") {
+          status.textContent = "Still loading ruby.wasm";
+        }
+      }, 15000);
+      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>

data/examples/browser/postprocessing/main.rb ADDED Viewed

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+require "js"
+begin
+  JS.global[:__threeReady].await
+  require_relative "../../../lib/three"
+  document = JS.global[:document]
+  window = JS.global[:window]
+  viewport = document.call(:querySelector, "#viewport")
+  status = document.call(:querySelector, "#status")
+  status_dot = document.call(:querySelector, "#status-dot")
+  status[:textContent] = "Starting postprocessing scene"
+  scene = Three::Scene.new
+  camera = Three::PerspectiveCamera.new(52, aspect: 1.0, near: 0.1, far: 100)
+  camera.position.set(0, 0.15, 5.2)
+  renderer = Three::Renderers::ThreeJSRenderer.new(
+    canvas: "#scene",
+    antialias: true,
+    alpha: false,
+    preserveDrawingBuffer: true
+  )
+  renderer.set_clear_color(0x0a0d12, 1)
+  composer = Three::Postprocessing::EffectComposer.new(renderer: renderer)
+  render_pass = Three::Postprocessing::RenderPass.new(scene, camera, composer: composer)
+  bloom_pass = Three::Postprocessing::UnrealBloomPass.new(
+    resolution: [1, 1],
+    strength: 1.15,
+    radius: 0.42,
+    threshold: 0.22,
+    composer: composer
+  )
+  dot_screen_pass = Three::Postprocessing::DotScreenPass.new(
+    center: [0.5, 0.5],
+    angle: 0.72,
+    scale: 1.4,
+    composer: composer
+  )
+  output_pass = Three::Postprocessing::OutputPass.new(composer: composer)
+  composer.add_pass(render_pass)
+  composer.add_pass(bloom_pass)
+  composer.add_pass(dot_screen_pass)
+  composer.add_pass(output_pass)
+  core_material = Three::MeshBasicMaterial.new(color: 0xf8fbff)
+  core = Three::Mesh.new(Three::SphereGeometry.new(0.48, width_segments: 32, height_segments: 16), core_material)
+  scene.add(core)
+  ring_material = Three::MeshBasicMaterial.new(color: 0x4ed08f)
+  ring = Three::Mesh.new(Three::BoxGeometry.new(2.15, 0.035, 0.035), ring_material)
+  ring.position.z = -0.05
+  scene.add(ring)
+  accent_material = Three::MeshBasicMaterial.new(color: 0xffcc4d)
+  left_accent = Three::Mesh.new(Three::BoxGeometry.new(0.18, 0.18, 0.18), accent_material)
+  left_accent.position.set(-1.25, -0.52, 0.15)
+  scene.add(left_accent)
+  right_accent = Three::Mesh.new(Three::BoxGeometry.new(0.18, 0.18, 0.18), accent_material)
+  right_accent.position.set(1.25, 0.52, 0.15)
+  scene.add(right_accent)
+  resize = proc do
+    width = [viewport[:clientWidth].to_i, 1].max
+    height = [viewport[:clientHeight].to_i, 1].max
+    camera.aspect = width.to_f / height
+    camera.update_projection_matrix
+    renderer.set_size(width, height)
+    composer.set_size(width, height)
+  end
+  resize.call
+  window.call(:addEventListener, "resize", resize)
+  composer.render(scene, camera)
+  JS.global[:__threeRbRenderer] = renderer.handle
+  JS.global[:__threeRbPostComposer] = composer.handle
+  JS.global[:__threeRbPostRenderPass] = render_pass.handle
+  JS.global[:__threeRbPostBloomPass] = bloom_pass.handle
+  JS.global[:__threeRbPostDotScreenPass] = dot_screen_pass.handle
+  JS.global[:__threeRbPostOutputPass] = output_pass.handle
+  JS.global[:__threeRbScene] = renderer.backend.materialize(scene)
+  JS.global[:__threeRbCamera] = renderer.backend.materialize(camera)
+  JS.global[:__threeRbPostCore] = renderer.backend.materialize(core)
+  JS.global[:__threeRbPostRing] = renderer.backend.materialize(ring)
+  JS.global[:__threeRbPostLeftAccent] = renderer.backend.materialize(left_accent)
+  JS.global[:__threeRbPostRightAccent] = renderer.backend.materialize(right_accent)
+  JS.global[:__threeRbPostFrame] = 0
+  renderer.animation_loop do
+    frame = JS.global[:__threeRbPostFrame].to_i + 1
+    JS.global[:__threeRbPostFrame] = frame
+    core.rotation.y += 0.014
+    ring.rotation.z += 0.01
+    left_accent.rotation.x += 0.018
+    left_accent.rotation.y += 0.013
+    right_accent.rotation.x -= 0.014
+    right_accent.rotation.y += 0.017
+    bloom_pass.strength = 0.95 + (0.22 * ((Math.sin(frame * 0.035) + 1) / 2.0))
+    dot_screen_pass.scale = 1.35 + (0.18 * ((Math.sin(frame * 0.025) + 1) / 2.0))
+    composer.render(scene, camera)
+  end
+  status[:textContent] = "Running"
+  status_dot[:dataset][:state] = "running"
+rescue StandardError => error
+  JS.global.call(:__threeRbBootFailed, error.message) if JS.global[:__threeRbBootFailed]
+  raise
+end

data/examples/browser/postprocessing/smoke_test.mjs ADDED Viewed

@@ -0,0 +1,121 @@
+import {
+  assertNoDiagnostics,
+  assertNonBlankCanvas,
+  createDiagnostics,
+  createSmokePage,
+  loadPlaywright,
+  sampleCanvas,
+  startServer,
+  waitForRunning
+} from "../shared/smoke_test_helpers.mjs";
+async function main() {
+  const { chromium } = await loadPlaywright();
+  const server = await startServer();
+  const browser = await chromium.launch({ headless: process.env.HEADLESS !== "0" });
+  const diagnostics = createDiagnostics();
+  try {
+    const page = await createSmokePage(browser, diagnostics);
+    await page.goto(`${server.url}/examples/browser/postprocessing/`, { waitUntil: "load" });
+    await waitForRunning(page, diagnostics);
+    await page.waitForTimeout(1_000);
+    assertNonBlankCanvas(await sampleCanvas(page));
+    const state = await page.evaluate(() => ({
+      frame: globalThis.__threeRbPostFrame,
+      renderCount: globalThis.__threeRbRenderCount,
+      renderFrameCount: globalThis.__threeRbRenderFrameCount,
+      renderInfo: globalThis.__threeRbRenderer?.info?.render,
+      composerPasses: globalThis.__threeRbPostComposer?.passes?.map((pass) => pass?.constructor?.name),
+      composerWidth: globalThis.__threeRbPostComposer?.renderTarget1?.width,
+      composerHeight: globalThis.__threeRbPostComposer?.renderTarget1?.height,
+      renderPassEnabled: globalThis.__threeRbPostRenderPass?.enabled,
+      renderPassSceneSame: globalThis.__threeRbPostRenderPass?.scene === globalThis.__threeRbScene,
+      renderPassCameraSame: globalThis.__threeRbPostRenderPass?.camera === globalThis.__threeRbCamera,
+      bloomPassEnabled: globalThis.__threeRbPostBloomPass?.enabled,
+      bloomStrength: globalThis.__threeRbPostBloomPass?.strength,
+      bloomRadius: globalThis.__threeRbPostBloomPass?.radius,
+      bloomThreshold: globalThis.__threeRbPostBloomPass?.threshold,
+      dotScreenPassEnabled: globalThis.__threeRbPostDotScreenPass?.enabled,
+      dotScreenPassType: globalThis.__threeRbPostDotScreenPass?.constructor?.name,
+      dotScreenCenter: globalThis.__threeRbPostDotScreenPass?.uniforms?.center?.value?.toArray?.(),
+      dotScreenAngle: globalThis.__threeRbPostDotScreenPass?.uniforms?.angle?.value,
+      dotScreenScale: globalThis.__threeRbPostDotScreenPass?.uniforms?.scale?.value,
+      outputPassEnabled: globalThis.__threeRbPostOutputPass?.enabled,
+      outputPassType: globalThis.__threeRbPostOutputPass?.constructor?.name,
+      outputPassFlag: globalThis.__threeRbPostOutputPass?.isOutputPass,
+      coreType: globalThis.__threeRbPostCore?.type,
+      coreGeometryType: globalThis.__threeRbPostCore?.geometry?.type,
+      ringType: globalThis.__threeRbPostRing?.type,
+      leftAccentType: globalThis.__threeRbPostLeftAccent?.type,
+      rightAccentType: globalThis.__threeRbPostRightAccent?.type
+    }));
+    if (!Array.isArray(state.composerPasses) || state.composerPasses.length !== 4) {
+      throw new Error(`expected four postprocessing passes: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.composerPasses[0] !== "RenderPass" ||
+      state.composerPasses[1] !== "UnrealBloomPass" ||
+      state.composerPasses[2] !== "DotScreenPass" ||
+      state.composerPasses[3] !== "OutputPass"
+    ) {
+      throw new Error(`expected RenderPass, UnrealBloomPass, DotScreenPass, then OutputPass: ${JSON.stringify(state)}`);
+    }
+    if (state.composerWidth <= 0 || state.composerHeight <= 0) {
+      throw new Error(`expected composer render targets to be sized: ${JSON.stringify(state)}`);
+    }
+    if (state.renderPassEnabled !== true || state.renderPassSceneSame !== true || state.renderPassCameraSame !== true) {
+      throw new Error(`expected render pass to target the Ruby-authored scene and camera: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.bloomPassEnabled !== true ||
+      state.bloomStrength < 0.9 ||
+      Math.abs(state.bloomRadius - 0.42) > 1e-12 ||
+      Math.abs(state.bloomThreshold - 0.22) > 1e-12
+    ) {
+      throw new Error(`expected configured bloom pass values: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.dotScreenPassEnabled !== true ||
+      state.dotScreenPassType !== "DotScreenPass" ||
+      !Array.isArray(state.dotScreenCenter) ||
+      state.dotScreenCenter[0] !== 0.5 ||
+      state.dotScreenCenter[1] !== 0.5 ||
+      Math.abs(state.dotScreenAngle - 0.72) > 1e-12 ||
+      state.dotScreenScale < 1.3
+    ) {
+      throw new Error(`expected configured dot screen pass values: ${JSON.stringify(state)}`);
+    }
+    if (state.outputPassEnabled !== true || state.outputPassType !== "OutputPass" || state.outputPassFlag !== true) {
+      throw new Error(`expected configured output pass values: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.coreType !== "Mesh" ||
+      state.coreGeometryType !== "SphereGeometry" ||
+      state.ringType !== "Mesh" ||
+      state.leftAccentType !== "Mesh" ||
+      state.rightAccentType !== "Mesh"
+    ) {
+      throw new Error(`postprocessing scene objects did not materialize: ${JSON.stringify(state)}`);
+    }
+    if (!state.renderInfo || state.renderInfo.calls < 1 || !state.frame || state.renderCount < 2 || state.renderFrameCount < 2) {
+      throw new Error(`postprocessing scene did not render or animate through composer: ${JSON.stringify(state)}`);
+    }
+    assertNoDiagnostics(diagnostics);
+    console.log(`postprocessing smoke test passed at ${server.url}/examples/browser/postprocessing/`);
+  } finally {
+    await browser.close();
+    await new Promise((resolve) => server.instance.close(resolve));
+  }
+}
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

data/examples/browser/primitives/README.md ADDED Viewed

@@ -0,0 +1,33 @@
+# Browser Primitives Example
+This example renders Ruby-authored `Three::Line`, `Three::Points`, and `Three::Sprite` objects through the Three.js browser backend. It covers generic `BufferGeometry` attributes, line/points materials, and a textured billboard sprite marker.
+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/primitives/
+```
+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:primitives
+```

data/examples/browser/primitives/boot.mjs ADDED Viewed

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

data/examples/browser/primitives/index.html ADDED Viewed

@@ -0,0 +1,142 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>three-rb primitives</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family:
+          Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+          "Segoe UI", sans-serif;
+        background: #101418;
+        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.035) 1px, transparent 1px),
+          linear-gradient(90deg, rgba(255, 255, 255, 0.035) 1px, transparent 1px),
+          linear-gradient(135deg, #101418 0%, #172026 52%, #0f1215 100%);
+        background-size: 32px 32px, 32px 32px, 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(10, 14, 18, 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: #4ed08f;
+        box-shadow: 0 0 14px rgba(78, 208, 143, 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.setTimeout(() => {
+        if (status && status.textContent === "Loading ruby.wasm") {
+          status.textContent = "Still loading ruby.wasm";
+        }
+      }, 15000);
+      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>

data/examples/browser/primitives/main.rb ADDED Viewed

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+require "js"
+begin
+  JS.global[:__threeReady].await
+  require_relative "../../../lib/three"
+  document = JS.global[:document]
+  window = JS.global[:window]
+  viewport = document.call(:querySelector, "#viewport")
+  status = document.call(:querySelector, "#status")
+  status_dot = document.call(:querySelector, "#status-dot")
+  status[:textContent] = "Starting primitives scene"
+  scene = Three::Scene.new
+  camera = Three::PerspectiveCamera.new(55, aspect: 1.0, near: 0.1, far: 100)
+  camera.position.z = 4
+  line_geometry = Three::BufferGeometry.new
+  line_geometry.set_attribute(
+    :position,
+    Three::Float32BufferAttribute.new(
+      [
+        -1.8, -0.8, 0,
+        -0.9, 0.75, 0,
+        0.0, -0.15, 0,
+        0.9, 0.75, 0,
+        1.8, -0.8, 0
+      ],
+      3
+    )
+  )
+  line = Three::Line.new(line_geometry, Three::LineBasicMaterial.new(color: 0x66ddff, linewidth: 2))
+  points_geometry = Three::BufferGeometry.new
+  points_geometry.set_attribute(
+    :position,
+    Three::Float32BufferAttribute.new(
+      [
+        -1.3, 0.25, 0.15,
+        -0.65, -0.35, 0.25,
+        0.0, 0.45, -0.2,
+        0.65, -0.35, 0.25,
+        1.3, 0.25, 0.15,
+        0.0, -0.9, 0
+      ],
+      3
+    )
+  )
+  points = Three::Points.new(
+    points_geometry,
+    Three::PointsMaterial.new(color: 0xffcc4d, size: 12, size_attenuation: false)
+  )
+  sprite_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  sprite_material = Three::SpriteMaterial.new(
+    color: 0xffffff,
+    map: sprite_texture,
+    rotation: 0.2,
+    size_attenuation: false,
+    opacity: 0.82
+  )
+  sprite = Three::Sprite.new(sprite_material)
+  sprite.center = [0.5, 0.5]
+  sprite.position.set(1.45, -0.95, 0.2)
+  sprite.scale.set(0.42, 0.42, 1)
+  scene.add(line, points, sprite)
+  renderer = Three::Renderers::ThreeJSRenderer.new(
+    canvas: "#scene",
+    antialias: true,
+    alpha: false,
+    preserveDrawingBuffer: true
+  )
+  renderer.set_clear_color(0x101418, 1)
+  resize = proc do
+    width = [viewport[:clientWidth].to_i, 1].max
+    height = [viewport[:clientHeight].to_i, 1].max
+    camera.aspect = width.to_f / height
+    camera.update_projection_matrix
+    renderer.set_size(width, height)
+  end
+  resize.call
+  window.call(:addEventListener, "resize", resize)
+  renderer.render(scene, camera)
+  JS.global[:__threeRbRenderer] = renderer.handle
+  JS.global[:__threeRbScene] = renderer.backend.materialize(scene)
+  JS.global[:__threeRbCamera] = renderer.backend.materialize(camera)
+  JS.global[:__threeRbLine] = renderer.backend.materialize(line)
+  JS.global[:__threeRbPoints] = renderer.backend.materialize(points)
+  JS.global[:__threeRbSprite] = renderer.backend.materialize(sprite)
+  JS.global[:__threeRbSpriteMaterial] = renderer.backend.materialize(sprite_material)
+  JS.global[:__threeRbSpriteTexture] = renderer.backend.materialize(sprite_texture)
+  JS.global[:__threeRbPrimitivesFrame] = 0
+  renderer.animation_loop do
+    JS.global[:__threeRbPrimitivesFrame] = JS.global[:__threeRbPrimitivesFrame].to_i + 1
+    line.rotation.z += 0.004
+    points.rotation.y += 0.012
+    sprite_material.rotation += 0.01
+    renderer.render(scene, camera)
+  end
+  status[:textContent] = "Running"
+  status_dot[:dataset][:state] = "running"
+rescue StandardError => error
+  JS.global.call(:__threeRbBootFailed, error.message) if JS.global[:__threeRbBootFailed]
+  raise
+end