three-rb 0.1.0

data/examples/browser/composition/main.rb

@@ -0,0 +1,216 @@
+# 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 Ruby scene"
+
+  scene = Three::Scene.new
+  camera = Three::OrthographicCamera.new(-3, 3, 1.8, -1.8, near: 0.1, far: 100)
+  camera.position.z = 5
+
+  ambient_light = Three::AmbientLight.new(0xffffff, 0.45)
+  scene.add(ambient_light)
+
+  key_light = Three::DirectionalLight.new(0xffffff, 1.35)
+  key_light.position.set(2.5, 3.0, 4.5)
+  key_light.cast_shadow = true
+  key_light.shadow_map_size = [1024, 1024]
+  key_light.shadow_bias = -0.0001
+  key_light.set_shadow_camera(left: -3.2, right: 3.2, top: 2.4, bottom: -2.4, near: 0.2, far: 12)
+  scene.add(key_light)
+
+  point_light = Three::PointLight.new(0x77a8ff, 0.8, 7, 2)
+  point_light.position.set(-1.6, 1.7, 2.4)
+  scene.add(point_light)
+
+  hemisphere_light = Three::HemisphereLight.new(0xdceeff, 0x1d2a20, 0.28)
+  scene.add(hemisphere_light)
+
+  backdrop_material = Three::MeshLambertMaterial.new(color: 0x243141)
+  backdrop = Three::Mesh.new(Three::PlaneGeometry.new(5.8, 3.4, width_segments: 2, height_segments: 2), backdrop_material)
+  backdrop.position.z = -1.25
+  backdrop.receive_shadow = true
+  scene.add(backdrop)
+
+  shadow_material = Three::ShadowMaterial.new(color: 0x000000, opacity: 0.32)
+  shadow_catcher = Three::Mesh.new(Three::PlaneGeometry.new(5.4, 3.0, width_segments: 1, height_segments: 1), shadow_material)
+  shadow_catcher.position.z = -1.18
+  shadow_catcher.receive_shadow = true
+  scene.add(shadow_catcher)
+
+  rig = Three::Group.new
+  rig.name = "composition-rig"
+  scene.add(rig)
+
+  primary_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  primary_texture.wrap_s = Three::RepeatWrapping
+  primary_texture.wrap_t = Three::RepeatWrapping
+  primary_texture.mag_filter = Three::NearestFilter
+  primary_texture.min_filter = Three::NearestMipmapNearestFilter
+  primary_texture.repeat.set(2, 2)
+  primary_material = Three::MeshLambertMaterial.new(color: 0xffffff, map: primary_texture)
+  primary = Three::Mesh.new(Three::BoxGeometry.new(0.85, 0.85, 0.85), primary_material)
+  primary.position.x = -0.55
+  primary.position.z = 0.15
+  primary.cast_shadow = true
+  rig.add(primary)
+
+  satellite_material = Three::MeshNormalMaterial.new(flat_shading: true)
+  satellite = Three::Mesh.new(Three::BoxGeometry.new(0.42, 0.42, 0.42), satellite_material)
+  satellite.position.x = 1.35
+  satellite.position.y = -0.7
+  satellite.position.z = 0.45
+  satellite.cast_shadow = true
+  rig.add(satellite)
+
+  orb_material = Three::MeshStandardMaterial.new(color: 0x77a8ff, roughness: 0.38, metalness: 0.45)
+  orb = Three::Mesh.new(Three::SphereGeometry.new(0.24, width_segments: 16, height_segments: 8), orb_material)
+  orb.position.x = 0.25
+  orb.position.y = 0.9
+  orb.position.z = 0.35
+  orb.cast_shadow = true
+  rig.add(orb)
+
+  highlight_material = Three::MeshPhongMaterial.new(
+    color: 0xdce7ff,
+    specular: 0xffffff,
+    shininess: 72,
+    specular_map: primary_texture
+  )
+  highlight = Three::Mesh.new(Three::SphereGeometry.new(0.18, width_segments: 12, height_segments: 8), highlight_material)
+  highlight.position.x = -1.25
+  highlight.position.y = 0.55
+  highlight.position.z = 0.55
+  highlight.cast_shadow = true
+  rig.add(highlight)
+
+  instance_count = 1000
+  instance_columns = 50
+  instanced_material = Three::MeshLambertMaterial.new(color: 0xffffff, opacity: 0.42, transparent: true)
+  instanced_field = Three::InstancedMesh.new(Three::BoxGeometry.new(0.032, 0.032, 0.032), instanced_material, instance_count)
+  instance_matrix = Three::Matrix4.new
+  instance_count.times do |index|
+    column = index % instance_columns
+    row = index / instance_columns
+    column_t = column.to_f / (instance_columns - 1)
+    row_t = row.to_f / ((instance_count / instance_columns) - 1)
+    x = (column - ((instance_columns - 1) / 2.0)) * 0.11
+    y = (row - ((instance_count / instance_columns - 1) / 2.0)) * 0.12
+    z = -0.85 - ((index % 7) * 0.012)
+    instanced_field.set_matrix_at(index, instance_matrix.make_translation(x, y, z))
+    instanced_field.set_color_at(index, [0.35 + (0.45 * column_t), 0.55 + (0.25 * row_t), 0.9 - (0.35 * column_t)])
+  end
+  scene.add(instanced_field)
+
+  renderer = Three::Renderers::ThreeJSRenderer.new(
+    canvas: "#scene",
+    antialias: true,
+    alpha: false,
+    preserveDrawingBuffer: true,
+    shadow_map_enabled: true,
+    shadow_map_type: Three::PCFShadowMap
+  )
+  renderer.set_clear_color(0x0f1419, 1)
+
+  controls = Three::Controls::OrbitControls.new(
+    camera,
+    renderer: renderer,
+    enable_damping: true,
+    damping_factor: 0.08,
+    enable_pan: false
+  )
+  controls.target.set(0, 0, 0)
+
+  resize = proc do
+    width = [viewport[:clientWidth].to_i, 1].max
+    height = [viewport[:clientHeight].to_i, 1].max
+    view_height = 3.8
+    view_width = view_height * width.to_f / height
+
+    camera.left = -view_width / 2
+    camera.right = view_width / 2
+    camera.top = view_height / 2
+    camera.bottom = -view_height / 2
+    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[:__threeRbControls] = controls.handle
+  JS.global[:__threeRbScene] = renderer.backend.materialize(scene)
+  JS.global[:__threeRbCamera] = renderer.backend.materialize(camera)
+  JS.global[:__threeRbAmbientLight] = renderer.backend.materialize(ambient_light)
+  JS.global[:__threeRbDirectionalLight] = renderer.backend.materialize(key_light)
+  JS.global[:__threeRbPointLight] = renderer.backend.materialize(point_light)
+  JS.global[:__threeRbHemisphereLight] = renderer.backend.materialize(hemisphere_light)
+  JS.global[:__threeRbPlane] = renderer.backend.materialize(backdrop)
+  JS.global[:__threeRbShadowCatcher] = renderer.backend.materialize(shadow_catcher)
+  JS.global[:__threeRbShadowMaterial] = renderer.backend.materialize(shadow_material)
+  JS.global[:__threeRbRig] = renderer.backend.materialize(rig)
+  JS.global[:__threeRbPrimaryMesh] = renderer.backend.materialize(primary)
+  JS.global[:__threeRbSatelliteMesh] = renderer.backend.materialize(satellite)
+  JS.global[:__threeRbSphereMesh] = renderer.backend.materialize(orb)
+  JS.global[:__threeRbPhongMesh] = renderer.backend.materialize(highlight)
+  JS.global[:__threeRbInstancedMesh] = renderer.backend.materialize(instanced_field)
+  JS.global[:__threeRbInstancedMaterial] = renderer.backend.materialize(instanced_material)
+  JS.global[:__threeRbTexture] = renderer.backend.materialize(primary_texture)
+  JS.global[:__threeRbChangingMaterial] = renderer.backend.materialize(primary_material)
+  JS.global[:__threeRbLambertMaterial] = renderer.backend.materialize(primary_material)
+  JS.global[:__threeRbNormalMaterial] = renderer.backend.materialize(satellite_material)
+  JS.global[:__threeRbStandardMaterial] = renderer.backend.materialize(orb_material)
+  JS.global[:__threeRbPhongMaterial] = renderer.backend.materialize(highlight_material)
+  JS.global[:__threeRbMaterialDisposeEvent] = false
+  JS.global[:__threeRbTextureDisposeEvent] = false
+
+  disposable_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  disposable_material = Three::MeshBasicMaterial.new(map: disposable_texture)
+  disposable_texture_handle = renderer.backend.materialize(disposable_texture)
+  disposable_material_handle = renderer.backend.materialize(disposable_material)
+  disposable_texture_handle.call(:addEventListener, "dispose", proc { JS.global[:__threeRbTextureDisposeEvent] = true })
+  disposable_material_handle.call(:addEventListener, "dispose", proc { JS.global[:__threeRbMaterialDisposeEvent] = true })
+  renderer.dispose(disposable_material, dispose_textures: true)
+  JS.global[:__threeRbMaterialHandleCachedAfterDispose] = renderer.backend.handles.key?(disposable_material.uuid)
+  JS.global[:__threeRbTextureHandleCachedAfterDispose] = renderer.backend.handles.key?(disposable_texture.uuid)
+  JS.global[:__threeRbInitialMaterialColor] = primary_material.color.hex
+  JS.global[:__threeRbCompositionFrame] = 0
+
+  frame = 0
+  renderer.animation_loop do
+    frame += 1
+    rig.rotation.z += 0.008
+    primary.rotation.x += 0.017
+    primary.rotation.y += 0.009
+    satellite.rotation.y -= 0.025
+    orb.rotation.x += 0.018
+    orb.rotation.y -= 0.013
+    highlight.rotation.y += 0.021
+    instanced_field.rotation.z -= 0.0015
+
+    pulse = (Math.sin(frame * 0.045) + 1) / 2.0
+    primary_material.color.set_rgb(0.25 + (0.35 * pulse), 0.55 + (0.25 * pulse), 0.42)
+
+    JS.global[:__threeRbCompositionFrame] = frame
+    controls.update
+    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

data/examples/browser/composition/smoke_test.mjs

@@ -0,0 +1,266 @@
+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/composition/`, { waitUntil: "load" });
+    await waitForRunning(page, diagnostics);
+    await page.waitForFunction(
+      () => globalThis.__threeRbLambertMaterial?.map?.source?.data?.complete === true,
+      null,
+      { timeout: 10_000 }
+    );
+    await page.waitForTimeout(1_000);
+
+    assertNonBlankCanvas(await sampleCanvas(page));
+
+    const scene = await page.evaluate(() => ({
+      frame: globalThis.__threeRbCompositionFrame,
+      renderInfo: globalThis.__threeRbRenderer?.info?.render,
+      cameraType: globalThis.__threeRbCamera?.type,
+      controlsType: globalThis.__threeRbControls?.constructor?.name,
+      controlsEnableDamping: globalThis.__threeRbControls?.enableDamping,
+      controlsEnablePan: globalThis.__threeRbControls?.enablePan,
+      controlsTarget: globalThis.__threeRbControls?.target?.toArray?.(),
+      shadowMapEnabled: globalThis.__threeRbRenderer?.shadowMap?.enabled,
+      shadowMapType: globalThis.__threeRbRenderer?.shadowMap?.type,
+      textureType: globalThis.__threeRbTexture?.isTexture,
+      materialTextureType: globalThis.__threeRbLambertMaterial?.map?.isTexture,
+      materialTextureWidth: globalThis.__threeRbLambertMaterial?.map?.source?.data?.naturalWidth,
+      materialTextureWrapS: globalThis.__threeRbLambertMaterial?.map?.wrapS,
+      materialTextureWrapT: globalThis.__threeRbLambertMaterial?.map?.wrapT,
+      materialTextureMagFilter: globalThis.__threeRbLambertMaterial?.map?.magFilter,
+      materialTextureMinFilter: globalThis.__threeRbLambertMaterial?.map?.minFilter,
+      materialTextureRepeat: globalThis.__threeRbLambertMaterial?.map?.repeat?.toArray?.(),
+      sceneChildren: globalThis.__threeRbScene?.children?.length,
+      ambientLightType: globalThis.__threeRbAmbientLight?.type,
+      directionalLightType: globalThis.__threeRbDirectionalLight?.type,
+      directionalLightCastShadow: globalThis.__threeRbDirectionalLight?.castShadow,
+      directionalShadowMapWidth: globalThis.__threeRbDirectionalLight?.shadow?.mapSize?.width,
+      directionalShadowMapHeight: globalThis.__threeRbDirectionalLight?.shadow?.mapSize?.height,
+      directionalShadowBias: globalThis.__threeRbDirectionalLight?.shadow?.bias,
+      directionalShadowCameraLeft: globalThis.__threeRbDirectionalLight?.shadow?.camera?.left,
+      directionalShadowCameraFar: globalThis.__threeRbDirectionalLight?.shadow?.camera?.far,
+      directionalShadowMapReady: Boolean(globalThis.__threeRbDirectionalLight?.shadow?.map),
+      pointLightType: globalThis.__threeRbPointLight?.type,
+      pointLightDistance: globalThis.__threeRbPointLight?.distance,
+      pointLightDecay: globalThis.__threeRbPointLight?.decay,
+      hemisphereLightType: globalThis.__threeRbHemisphereLight?.type,
+      hemisphereLightGroundColor: globalThis.__threeRbHemisphereLight?.groundColor?.getHex?.(),
+      hemisphereLightIntensity: globalThis.__threeRbHemisphereLight?.intensity,
+      planeGeometryType: globalThis.__threeRbPlane?.geometry?.type,
+      planeReceiveShadow: globalThis.__threeRbPlane?.receiveShadow,
+      shadowCatcherType: globalThis.__threeRbShadowCatcher?.type,
+      shadowCatcherGeometryType: globalThis.__threeRbShadowCatcher?.geometry?.type,
+      shadowCatcherReceiveShadow: globalThis.__threeRbShadowCatcher?.receiveShadow,
+      shadowMaterialType: globalThis.__threeRbShadowMaterial?.type,
+      shadowMaterialColor: globalThis.__threeRbShadowMaterial?.color?.getHex?.(),
+      shadowMaterialOpacity: globalThis.__threeRbShadowMaterial?.opacity,
+      shadowMaterialTransparent: globalThis.__threeRbShadowMaterial?.transparent,
+      shadowMaterialFog: globalThis.__threeRbShadowMaterial?.fog,
+      rigType: globalThis.__threeRbRig?.type,
+      primaryParentType: globalThis.__threeRbPrimaryMesh?.parent?.type,
+      primaryCastShadow: globalThis.__threeRbPrimaryMesh?.castShadow,
+      primaryMaterialType: globalThis.__threeRbPrimaryMesh?.material?.type,
+      satelliteParentType: globalThis.__threeRbSatelliteMesh?.parent?.type,
+      sphereParentType: globalThis.__threeRbSphereMesh?.parent?.type,
+      sphereGeometryType: globalThis.__threeRbSphereMesh?.geometry?.type,
+      sphereMaterialType: globalThis.__threeRbSphereMesh?.material?.type,
+      phongParentType: globalThis.__threeRbPhongMesh?.parent?.type,
+      phongGeometryType: globalThis.__threeRbPhongMesh?.geometry?.type,
+      phongMaterialType: globalThis.__threeRbPhongMesh?.material?.type,
+      phongSpecular: globalThis.__threeRbPhongMaterial?.specular?.getHex?.(),
+      phongShininess: globalThis.__threeRbPhongMaterial?.shininess,
+      phongSpecularMapType: globalThis.__threeRbPhongMaterial?.specularMap?.isTexture,
+      instancedType: globalThis.__threeRbInstancedMesh?.type,
+      instancedIsInstancedMesh: globalThis.__threeRbInstancedMesh?.isInstancedMesh,
+      instancedCount: globalThis.__threeRbInstancedMesh?.count,
+      instancedMaterialType: globalThis.__threeRbInstancedMaterial?.type,
+      instancedMaterialTransparent: globalThis.__threeRbInstancedMaterial?.transparent,
+      instancedMatrixNeedsUpdate: globalThis.__threeRbInstancedMesh?.instanceMatrix?.needsUpdate,
+      instancedHasInstanceColor: Boolean(globalThis.__threeRbInstancedMesh?.instanceColor),
+      instancedColorItemSize: globalThis.__threeRbInstancedMesh?.instanceColor?.itemSize,
+      instancedColorCount: globalThis.__threeRbInstancedMesh?.instanceColor?.count,
+      instancedFirstColor: (() => {
+        if (!globalThis.__threeRbInstancedMesh || !globalThis.THREE?.Color) return undefined;
+        const color = new globalThis.THREE.Color();
+        globalThis.__threeRbInstancedMesh.getColorAt(0, color);
+        return color.toArray();
+      })(),
+      instancedLastColor: (() => {
+        if (!globalThis.__threeRbInstancedMesh || !globalThis.THREE?.Color) return undefined;
+        const color = new globalThis.THREE.Color();
+        globalThis.__threeRbInstancedMesh.getColorAt(999, color);
+        return color.toArray();
+      })(),
+      instancedLastMatrix: (() => {
+        if (!globalThis.__threeRbInstancedMesh || !globalThis.THREE?.Matrix4) return undefined;
+        const matrix = new globalThis.THREE.Matrix4();
+        globalThis.__threeRbInstancedMesh.getMatrixAt(999, matrix);
+        return matrix.toArray();
+      })(),
+      satelliteMaterialType: globalThis.__threeRbSatelliteMesh?.material?.type,
+      normalMaterialFlatShading: globalThis.__threeRbNormalMaterial?.flatShading,
+      standardMaterialRoughness: globalThis.__threeRbStandardMaterial?.roughness,
+      standardMaterialMetalness: globalThis.__threeRbStandardMaterial?.metalness,
+      materialDisposeEvent: globalThis.__threeRbMaterialDisposeEvent,
+      textureDisposeEvent: globalThis.__threeRbTextureDisposeEvent,
+      materialHandleCachedAfterDispose: globalThis.__threeRbMaterialHandleCachedAfterDispose,
+      textureHandleCachedAfterDispose: globalThis.__threeRbTextureHandleCachedAfterDispose,
+      currentMaterialColor: globalThis.__threeRbChangingMaterial?.color?.getHex?.(),
+      initialMaterialColor: globalThis.__threeRbInitialMaterialColor
+    }));
+
+    if (scene.planeGeometryType !== "PlaneGeometry") {
+      throw new Error(`expected a PlaneGeometry backdrop: ${JSON.stringify(scene)}`);
+    }
+    if (
+      scene.shadowCatcherType !== "Mesh" ||
+      scene.shadowCatcherGeometryType !== "PlaneGeometry" ||
+      scene.shadowCatcherReceiveShadow !== true ||
+      scene.shadowMaterialType !== "ShadowMaterial" ||
+      scene.shadowMaterialColor !== 0x000000 ||
+      scene.shadowMaterialOpacity !== 0.32 ||
+      scene.shadowMaterialTransparent !== true ||
+      scene.shadowMaterialFog !== true
+    ) {
+      throw new Error(`expected a configured ShadowMaterial catcher: ${JSON.stringify(scene)}`);
+    }
+    if (scene.cameraType !== "OrthographicCamera") {
+      throw new Error(`expected an OrthographicCamera composition view: ${JSON.stringify(scene)}`);
+    }
+    if (scene.controlsType !== "OrbitControls" || scene.controlsEnableDamping !== true || scene.controlsEnablePan !== false) {
+      throw new Error(`expected configured OrbitControls: ${JSON.stringify(scene)}`);
+    }
+    if (scene.shadowMapEnabled !== true || scene.shadowMapType !== 1) {
+      throw new Error(`expected enabled PCF shadow mapping: ${JSON.stringify(scene)}`);
+    }
+    if (scene.textureType !== true || scene.materialTextureType !== true || scene.materialTextureWidth <= 0) {
+      throw new Error(`expected a loaded material texture: ${JSON.stringify(scene)}`);
+    }
+    if (scene.materialTextureWrapS !== 1000 || scene.materialTextureWrapT !== 1000 || scene.materialTextureMagFilter !== 1003 || scene.materialTextureMinFilter !== 1004) {
+      throw new Error(`expected configured texture wrapping and filters: ${JSON.stringify(scene)}`);
+    }
+    if (!Array.isArray(scene.materialTextureRepeat) || scene.materialTextureRepeat[0] !== 2 || scene.materialTextureRepeat[1] !== 2) {
+      throw new Error(`expected configured texture repeat: ${JSON.stringify(scene)}`);
+    }
+    if (scene.ambientLightType !== "AmbientLight" || scene.directionalLightType !== "DirectionalLight" || scene.pointLightType !== "PointLight" || scene.hemisphereLightType !== "HemisphereLight") {
+      throw new Error(`expected ambient, directional, point, and hemisphere lights: ${JSON.stringify(scene)}`);
+    }
+    if (scene.directionalLightCastShadow !== true || scene.directionalShadowMapWidth !== 1024 || scene.directionalShadowMapHeight !== 1024) {
+      throw new Error(`expected configured DirectionalLight shadow map: ${JSON.stringify(scene)}`);
+    }
+    if (scene.directionalShadowBias !== -0.0001 || scene.directionalShadowCameraLeft !== -3.2 || scene.directionalShadowCameraFar !== 12) {
+      throw new Error(`expected configured DirectionalLight shadow camera: ${JSON.stringify(scene)}`);
+    }
+    if (scene.directionalShadowMapReady !== true) {
+      throw new Error(`expected rendered DirectionalLight shadow map: ${JSON.stringify(scene)}`);
+    }
+    if (scene.pointLightDistance !== 7 || scene.pointLightDecay !== 2) {
+      throw new Error(`expected configured PointLight falloff: ${JSON.stringify(scene)}`);
+    }
+    if (scene.hemisphereLightGroundColor !== 0x1d2a20 || scene.hemisphereLightIntensity !== 0.28) {
+      throw new Error(`expected configured HemisphereLight: ${JSON.stringify(scene)}`);
+    }
+    if (scene.rigType !== "Group" || scene.primaryParentType !== "Group" || scene.satelliteParentType !== "Group" || scene.sphereParentType !== "Group" || scene.phongParentType !== "Group") {
+      throw new Error(`expected grouped child meshes: ${JSON.stringify(scene)}`);
+    }
+    if (scene.planeReceiveShadow !== true || scene.primaryCastShadow !== true) {
+      throw new Error(`expected mesh shadow flags: ${JSON.stringify(scene)}`);
+    }
+    if (scene.primaryMaterialType !== "MeshLambertMaterial") {
+      throw new Error(`expected a light-reactive MeshLambertMaterial primary mesh: ${JSON.stringify(scene)}`);
+    }
+    if (scene.sphereGeometryType !== "SphereGeometry") {
+      throw new Error(`expected a SphereGeometry child mesh: ${JSON.stringify(scene)}`);
+    }
+    if (scene.sphereMaterialType !== "MeshStandardMaterial" || scene.standardMaterialRoughness !== 0.38 || scene.standardMaterialMetalness !== 0.45) {
+      throw new Error(`expected a configured MeshStandardMaterial sphere: ${JSON.stringify(scene)}`);
+    }
+    if (scene.phongGeometryType !== "SphereGeometry" || scene.phongMaterialType !== "MeshPhongMaterial") {
+      throw new Error(`expected a MeshPhongMaterial highlight sphere: ${JSON.stringify(scene)}`);
+    }
+    if (scene.phongSpecular !== 0xffffff || scene.phongShininess !== 72 || scene.phongSpecularMapType !== true) {
+      throw new Error(`expected configured MeshPhongMaterial specular settings: ${JSON.stringify(scene)}`);
+    }
+    if (scene.instancedIsInstancedMesh !== true || scene.instancedCount !== 1000) {
+      throw new Error(`expected a 1000-count InstancedMesh: ${JSON.stringify(scene)}`);
+    }
+    if (scene.instancedMaterialType !== "MeshLambertMaterial" || scene.instancedMaterialTransparent !== true) {
+      throw new Error(`expected a transparent MeshLambertMaterial on InstancedMesh: ${JSON.stringify(scene)}`);
+    }
+    if (!Array.isArray(scene.instancedLastMatrix) || Math.abs(scene.instancedLastMatrix[12] - 2.695) > 0.001 || Math.abs(scene.instancedLastMatrix[13] - 1.14) > 0.001) {
+      throw new Error(`expected InstancedMesh matrix data to sync: ${JSON.stringify(scene)}`);
+    }
+    if (scene.instancedHasInstanceColor !== true || scene.instancedColorItemSize !== 3 || scene.instancedColorCount !== 1000) {
+      throw new Error(`expected InstancedMesh color attribute data: ${JSON.stringify(scene)}`);
+    }
+    if (!colorClose(scene.instancedFirstColor, [0.35, 0.55, 0.9]) || !colorClose(scene.instancedLastColor, [0.8, 0.8, 0.55])) {
+      throw new Error(`expected InstancedMesh color data to sync: ${JSON.stringify(scene)}`);
+    }
+    if (scene.satelliteMaterialType !== "MeshNormalMaterial" || scene.normalMaterialFlatShading !== true) {
+      throw new Error(`expected a flat-shaded MeshNormalMaterial satellite: ${JSON.stringify(scene)}`);
+    }
+    if (scene.materialDisposeEvent !== true || scene.textureDisposeEvent !== true) {
+      throw new Error(`expected material and texture dispose events: ${JSON.stringify(scene)}`);
+    }
+    if (scene.materialHandleCachedAfterDispose !== false || scene.textureHandleCachedAfterDispose !== false) {
+      throw new Error(`expected disposed material and texture handles to leave the backend cache: ${JSON.stringify(scene)}`);
+    }
+    if (!scene.renderInfo || scene.renderInfo.triangles < 10000) {
+      throw new Error(`renderer did not draw the composition triangles: ${JSON.stringify(scene)}`);
+    }
+    if (!scene.frame || scene.currentMaterialColor === scene.initialMaterialColor) {
+      throw new Error(`material color did not change after animation frames: ${JSON.stringify(scene)}`);
+    }
+
+    const beforeDrag = await page.evaluate(() => globalThis.__threeRbCamera?.position?.toArray?.());
+    await page.mouse.move(480, 270);
+    await page.mouse.down();
+    await page.mouse.move(620, 300, { steps: 12 });
+    await page.mouse.up();
+    await page.waitForTimeout(500);
+    const afterDrag = await page.evaluate(() => globalThis.__threeRbCamera?.position?.toArray?.());
+    if (!cameraPositionChanged(beforeDrag, afterDrag)) {
+      throw new Error(`OrbitControls drag did not move the camera: ${JSON.stringify({ beforeDrag, afterDrag })}`);
+    }
+    assertNoDiagnostics(diagnostics);
+
+    console.log(`composition smoke test passed at ${server.url}/examples/browser/composition/`);
+  } finally {
+    await browser.close();
+    await new Promise((resolve) => server.instance.close(resolve));
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+
+function cameraPositionChanged(before, after) {
+  if (!Array.isArray(before) || !Array.isArray(after)) return false;
+
+  return before.some((value, index) => Math.abs(value - after[index]) > 0.001);
+}
+
+function colorClose(actual, expected) {
+  if (!Array.isArray(actual)) return false;
+
+  return expected.every((value, index) => Math.abs(actual[index] - value) < 0.001);
+}

data/examples/browser/cube/README.md

@@ -0,0 +1,41 @@
+# Browser Cube Example
+
+This example renders a Ruby-authored cube through ruby.wasm and the JavaScript three.js renderer.
+
+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/cube/
+```
+
+The page uses these pnpm-managed browser dependencies:
+
+- `@ruby/3.4-wasm-wasi@2.9.4-2026-05-11-a`
+- `@ruby/wasm-wasi@2.9.4-2026-05-11-a`
+- `three@0.184.0`
+
+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:cube
+```
+
+The smoke test serves the repository root, waits for the Ruby scene to reach `Running`, samples the WebGL canvas for nonblank pixels, and verifies that the renderer drew the cube triangles.

data/examples/browser/cube/boot.mjs

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

data/examples/browser/cube/index.html

@@ -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 cube</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>