three-rb 0.1.0

data/examples/browser/primitives/smoke_test.mjs

@@ -0,0 +1,113 @@
+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/primitives/`, { waitUntil: "load" });
+    await waitForRunning(page, diagnostics);
+    await page.waitForFunction(
+      () => globalThis.__threeRbSpriteMaterial?.map?.source?.data?.complete === true,
+      null,
+      { timeout: 10_000 }
+    );
+    await page.waitForTimeout(1_000);
+
+    assertNonBlankCanvas(await sampleCanvas(page));
+
+    const state = await page.evaluate(() => ({
+      frame: globalThis.__threeRbPrimitivesFrame,
+      line: {
+        type: globalThis.__threeRbLine?.type,
+        materialType: globalThis.__threeRbLine?.material?.type,
+        positionCount: globalThis.__threeRbLine?.geometry?.attributes?.position?.count,
+        color: globalThis.__threeRbLine?.material?.color?.getHex?.()
+      },
+      points: {
+        type: globalThis.__threeRbPoints?.type,
+        materialType: globalThis.__threeRbPoints?.material?.type,
+        positionCount: globalThis.__threeRbPoints?.geometry?.attributes?.position?.count,
+        color: globalThis.__threeRbPoints?.material?.color?.getHex?.(),
+        size: globalThis.__threeRbPoints?.material?.size,
+        sizeAttenuation: globalThis.__threeRbPoints?.material?.sizeAttenuation
+      },
+      sprite: {
+        type: globalThis.__threeRbSprite?.type,
+        materialType: globalThis.__threeRbSprite?.material?.type,
+        center: globalThis.__threeRbSprite?.center?.toArray?.(),
+        scale: globalThis.__threeRbSprite?.scale?.toArray?.(),
+        color: globalThis.__threeRbSpriteMaterial?.color?.getHex?.(),
+        opacity: globalThis.__threeRbSpriteMaterial?.opacity,
+        rotation: globalThis.__threeRbSpriteMaterial?.rotation,
+        sizeAttenuation: globalThis.__threeRbSpriteMaterial?.sizeAttenuation,
+        materialMapType: globalThis.__threeRbSpriteMaterial?.map?.isTexture,
+        mapSame: globalThis.__threeRbSpriteMaterial?.map === globalThis.__threeRbSpriteTexture,
+        textureWidth: globalThis.__threeRbSpriteTexture?.source?.data?.naturalWidth
+      },
+      renderInfo: globalThis.__threeRbRenderer?.info?.render
+    }));
+
+    if (state.line.type !== "Line" || state.line.materialType !== "LineBasicMaterial" || state.line.positionCount !== 5) {
+      throw new Error(`line primitive did not materialize correctly: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.points.type !== "Points" ||
+      state.points.materialType !== "PointsMaterial" ||
+      state.points.positionCount !== 6 ||
+      state.points.size !== 12 ||
+      state.points.sizeAttenuation !== false
+    ) {
+      throw new Error(`points primitive did not materialize correctly: ${JSON.stringify(state)}`);
+    }
+    if (
+      state.sprite.type !== "Sprite" ||
+      state.sprite.materialType !== "SpriteMaterial" ||
+      state.sprite.color !== 0xffffff ||
+      state.sprite.opacity !== 0.82 ||
+      state.sprite.sizeAttenuation !== false ||
+      state.sprite.materialMapType !== true ||
+      state.sprite.mapSame !== true ||
+      state.sprite.textureWidth <= 0
+    ) {
+      throw new Error(`sprite primitive did not materialize correctly: ${JSON.stringify(state)}`);
+    }
+    if (!Array.isArray(state.sprite.center) || state.sprite.center[0] !== 0.5 || state.sprite.center[1] !== 0.5) {
+      throw new Error(`sprite center did not sync correctly: ${JSON.stringify(state)}`);
+    }
+    if (!Array.isArray(state.sprite.scale) || state.sprite.scale[0] !== 0.42 || state.sprite.scale[1] !== 0.42) {
+      throw new Error(`sprite transform did not sync correctly: ${JSON.stringify(state)}`);
+    }
+    if (state.sprite.rotation <= 0.2) {
+      throw new Error(`sprite material rotation did not animate: ${JSON.stringify(state)}`);
+    }
+    if (!state.renderInfo || state.renderInfo.calls < 2 || !state.frame) {
+      throw new Error(`primitives scene did not render or animate: ${JSON.stringify(state)}`);
+    }
+
+    assertNoDiagnostics(diagnostics);
+
+    console.log(`primitives smoke test passed at ${server.url}/examples/browser/primitives/`);
+  } finally {
+    await browser.close();
+    await new Promise((resolve) => server.instance.close(resolve));
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

data/examples/browser/serialization/README.md

@@ -0,0 +1,33 @@
+# Browser Serialization Example
+
+This example exports a Ruby-authored scene with shared geometry, material, and texture resources to the `ThreeJSONExporter` format, parses it back with `ThreeJSONLoader`, and renders the loaded scene through the three.js backend.
+
+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/serialization/
+```
+
+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:serialization
+```

data/examples/browser/serialization/boot.mjs

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

data/examples/browser/serialization/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 serialization</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/serialization/main.rb

@@ -0,0 +1,97 @@
+# 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] = "Exporting Ruby scene"
+
+  source_scene = Three::Scene.new
+  source_scene.name = "serialization-source"
+
+  shared_texture = Three::Loaders::TextureLoader.new.load("/examples/browser/assets/checker.svg")
+  shared_texture.wrap_s = Three::RepeatWrapping
+  shared_texture.wrap_t = Three::RepeatWrapping
+  shared_texture.mag_filter = Three::NearestFilter
+  shared_texture.min_filter = Three::NearestMipmapNearestFilter
+  shared_texture.repeat.set(2, 2)
+
+  geometry = Three::BoxGeometry.new(0.82, 0.82, 0.82)
+  material = Three::MeshBasicMaterial.new(color: 0xffffff, map: shared_texture)
+  first = Three::Mesh.new(geometry, material)
+  first.name = "loaded-left"
+  first.position.x = -0.68
+
+  second = Three::Mesh.new(geometry, material)
+  second.name = "loaded-right"
+  second.position.x = 0.68
+  second.scale.set(0.72, 0.72, 0.72)
+
+  source_scene.add(first, second)
+
+  exported = Three::Exporters::ThreeJSONExporter.new(deterministic_ids: true).export(source_scene)
+  json = JSON.generate(exported)
+  scene = Three::Loaders::ThreeJSONLoader.new.parse(json)
+  scene.name = "serialization-loaded"
+
+  camera = Three::PerspectiveCamera.new(62, aspect: 1.0, near: 0.1, far: 100)
+  camera.position.z = 3.4
+
+  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)
+
+  left = scene.get_object_by_name("loaded-left")
+  right = scene.get_object_by_name("loaded-right")
+
+  JS.global[:__threeRbRenderer] = renderer.handle
+  JS.global[:__threeRbScene] = renderer.backend.materialize(scene)
+  JS.global[:__threeRbCamera] = renderer.backend.materialize(camera)
+  JS.global[:__threeRbSerializedJson] = json
+  JS.global[:__threeRbLoadedLeft] = renderer.backend.materialize(left)
+  JS.global[:__threeRbLoadedRight] = renderer.backend.materialize(right)
+  JS.global[:__threeRbLoadedSharedGeometry] = left.geometry.equal?(right.geometry)
+  JS.global[:__threeRbLoadedSharedMaterial] = left.material.equal?(right.material)
+  JS.global[:__threeRbLoadedSharedTexture] = left.material.map.equal?(right.material.map)
+  JS.global[:__threeRbSerializationFrame] = 0
+
+  renderer.animation_loop do
+    JS.global[:__threeRbSerializationFrame] = JS.global[:__threeRbSerializationFrame].to_i + 1
+    left.rotation.x += 0.012
+    left.rotation.y += 0.018
+    right.rotation.x -= 0.01
+    right.rotation.y += 0.014
+    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/serialization/smoke_test.mjs

@@ -0,0 +1,67 @@
+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/serialization/`, { waitUntil: "load" });
+    await waitForRunning(page, diagnostics);
+    await page.waitForTimeout(1_000);
+
+    assertNonBlankCanvas(await sampleCanvas(page));
+
+    const state = await page.evaluate(() => ({
+      frame: globalThis.__threeRbSerializationFrame,
+      sceneChildren: globalThis.__threeRbScene?.children?.length,
+      leftType: globalThis.__threeRbLoadedLeft?.type,
+      rightType: globalThis.__threeRbLoadedRight?.type,
+      sharedGeometry: globalThis.__threeRbLoadedSharedGeometry,
+      sharedMaterial: globalThis.__threeRbLoadedSharedMaterial,
+      sharedTexture: globalThis.__threeRbLoadedSharedTexture,
+      serialized: JSON.parse(globalThis.__threeRbSerializedJson),
+      renderInfo: globalThis.__threeRbRenderer?.info?.render
+    }));
+
+    if (state.sceneChildren !== 2 || state.leftType !== "Mesh" || state.rightType !== "Mesh") {
+      throw new Error(`loaded scene graph is unexpected: ${JSON.stringify(state)}`);
+    }
+    if (!state.sharedGeometry || !state.sharedMaterial || !state.sharedTexture) {
+      throw new Error(`loaded resources were not shared: ${JSON.stringify(state)}`);
+    }
+    if (state.serialized.geometries?.length !== 1 || state.serialized.materials?.length !== 1 || state.serialized.textures?.length !== 1) {
+      throw new Error(`export did not deduplicate resources: ${JSON.stringify(state.serialized)}`);
+    }
+    if (!state.renderInfo || state.renderInfo.triangles < 24) {
+      throw new Error(`renderer did not draw the loaded meshes: ${JSON.stringify(state)}`);
+    }
+    if (!state.frame) {
+      throw new Error(`serialization example animation did not advance: ${JSON.stringify(state)}`);
+    }
+
+    assertNoDiagnostics(diagnostics);
+
+    console.log(`serialization smoke test passed at ${server.url}/examples/browser/serialization/`);
+  } finally {
+    await browser.close();
+    await new Promise((resolve) => server.instance.close(resolve));
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

data/examples/browser/shared/boot.mjs

@@ -0,0 +1,79 @@
+import { DefaultRubyVM } from "@ruby/wasm-wasi/browser";
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+import { HDRLoader } from "three/addons/loaders/HDRLoader.js";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+import { DotScreenPass } from "three/addons/postprocessing/DotScreenPass.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+
+export async function bootRubyExample({ main, clearColor }) {
+  const setStatus = globalThis.__threeRbSetStatus || (() => {});
+  const bootFailed = globalThis.__threeRbBootFailed || ((message) => console.error(message));
+
+  try {
+    setStatus("Loading ruby.wasm", "loading");
+    globalThis.THREE = THREE;
+    globalThis.THREE_GLTF_LOADER = GLTFLoader;
+    globalThis.THREE_DRACO_LOADER = DRACOLoader;
+    globalThis.THREE_RGBE_LOADER = HDRLoader;
+    globalThis.THREE_ORBIT_CONTROLS = OrbitControls;
+    globalThis.THREE_EFFECT_COMPOSER = EffectComposer;
+    globalThis.THREE_RENDER_PASS = RenderPass;
+    globalThis.THREE_UNREAL_BLOOM_PASS = UnrealBloomPass;
+    globalThis.THREE_DOT_SCREEN_PASS = DotScreenPass;
+    globalThis.THREE_OUTPUT_PASS = OutputPass;
+    globalThis.__threeReady = Promise.resolve(THREE);
+    globalThis.__threeRbRenderCount = 0;
+    globalThis.__threeRbRenderFrameCount = 0;
+    globalThis.__threeRbRender = () => {
+      globalThis.__threeRbRenderCount += 1;
+      const renderer = globalThis.__threeRbCurrentRenderer;
+      const scene = globalThis.__threeRbCurrentScene;
+      const camera = globalThis.__threeRbCurrentCamera;
+      globalThis.__threeRbRenderFrameCount += 1;
+      renderer.setClearColor(clearColor, 1);
+      renderer.render(scene, camera);
+    };
+    globalThis.__threeRbRenderComposer = () => {
+      globalThis.__threeRbRenderCount += 1;
+      const composer = globalThis.__threeRbCurrentComposer;
+      globalThis.__threeRbRenderFrameCount += 1;
+      composer.render();
+    };
+
+    const rubyModule = await compileWasm("/node_modules/@ruby/3.4-wasm-wasi/dist/ruby+stdlib.wasm");
+    const { vm } = await DefaultRubyVM(rubyModule);
+    globalThis.rubyVM = vm;
+
+    setStatus("Starting Ruby VM", "loading");
+    await vm.evalAsync(`
+      require "js/require_remote/relative_shim"
+      JS::RequireRemote.instance.base_url = "/"
+      JS::RequireRemote.instance.load(${JSON.stringify(main)})
+    `);
+  } catch (error) {
+    bootFailed(error && error.message ? error.message : "Ruby boot failed");
+    throw error;
+  }
+}
+
+async function compileWasm(url) {
+  const response = fetch(url);
+  if (WebAssembly.compileStreaming) {
+    try {
+      return await WebAssembly.compileStreaming(response);
+    } catch (_error) {
+      // Fall back when a static server does not provide application/wasm.
+    }
+  }
+
+  const fallbackResponse = await fetch(url);
+  if (!fallbackResponse.ok) {
+    throw new Error(`Failed to load ruby.wasm: ${fallbackResponse.status} ${fallbackResponse.statusText}`);
+  }
+  return WebAssembly.compile(await fallbackResponse.arrayBuffer());
+}

data/examples/browser/shared/smoke_test_helpers.mjs

@@ -0,0 +1,151 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("../../..", import.meta.url));
+const mimeTypes = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".mjs", "text/javascript; charset=utf-8"],
+  [".rb", "text/plain; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".gltf", "model/gltf+json"],
+  [".hdr", "image/vnd.radiance"],
+  [".wasm", "application/wasm"]
+]);
+
+export function createDiagnostics() {
+  return { errors: [], requests: [] };
+}
+
+export async function loadPlaywright() {
+  try {
+    return await import("playwright");
+  } catch (error) {
+    throw new Error(
+      "Playwright is required for the browser smoke test. Run `pnpm install` and `pnpm exec playwright install chromium` first.",
+      { cause: error }
+    );
+  }
+}
+
+export async function createSmokePage(browser, diagnostics, options = {}) {
+  const page = await browser.newPage({ viewport: options.viewport || { width: 960, height: 540 } });
+  page.on("console", (message) => {
+    if (message.type() === "error") diagnostics.errors.push(message.text());
+  });
+  page.on("pageerror", (error) => diagnostics.errors.push(error.message));
+  page.on("requestfailed", (request) => {
+    const failure = request.failure();
+    diagnostics.requests.push(`request failed: ${request.url()} ${failure ? failure.errorText : ""}`.trim());
+  });
+  page.on("response", (response) => {
+    if (response.status() >= 400) diagnostics.requests.push(`response ${response.status()}: ${response.url()}`);
+  });
+  return page;
+}
+
+export async function waitForRunning(page, diagnostics, timeout = 120_000) {
+  await page.getByTestId("status").waitFor({ state: "visible", timeout: 5_000 });
+  try {
+    await page.waitForFunction(
+      () => document.querySelector("[data-testid='status']")?.textContent === "Running",
+      null,
+      { timeout }
+    );
+  } catch (error) {
+    const status = await page.getByTestId("status").textContent();
+    throw new Error(diagnosticMessage(`timed out waiting for Running; current status: ${status}`, diagnostics), {
+      cause: error
+    });
+  }
+}
+
+export async function sampleCanvas(page) {
+  return page.evaluate(() => {
+    const element = document.querySelector("[data-testid='scene-canvas']");
+    if (!element) return { width: 0, height: 0, nonBlankPixels: 0, nonTransparentPixels: 0, maxRgb: 0 };
+
+    const gl = element.getContext("webgl2") || element.getContext("webgl");
+    if (!gl) throw new Error("canvas WebGL context is not available");
+
+    const width = element.width;
+    const height = element.height;
+    const pixels = new Uint8Array(width * height * 4);
+
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+
+    let nonBlankPixels = 0;
+    let nonTransparentPixels = 0;
+    let maxRgb = 0;
+    for (let index = 0; index < pixels.length; index += 4) {
+      const rgb = pixels[index] + pixels[index + 1] + pixels[index + 2];
+      if (rgb > 12) nonBlankPixels += 1;
+      if (pixels[index + 3] > 0) nonTransparentPixels += 1;
+      if (rgb > maxRgb) maxRgb = rgb;
+    }
+
+    return { width, height, nonBlankPixels, nonTransparentPixels, maxRgb };
+  });
+}
+
+export function assertCanvasHasDimensions(canvas) {
+  if (canvas.width <= 0 || canvas.height <= 0) {
+    throw new Error(`canvas has invalid dimensions: ${canvas.width}x${canvas.height}`);
+  }
+}
+
+export function assertNonBlankCanvas(canvas) {
+  assertCanvasHasDimensions(canvas);
+  if (canvas.nonBlankPixels === 0) {
+    throw new Error(`canvas sample is blank: ${JSON.stringify(canvas)}`);
+  }
+}
+
+export function assertNoDiagnostics(diagnostics) {
+  if (diagnostics.errors.length > 0 || diagnostics.requests.length > 0) {
+    throw new Error(diagnosticMessage("browser diagnostics", diagnostics));
+  }
+}
+
+export function diagnosticMessage(message, diagnostics) {
+  const sections = [message];
+  if (diagnostics.errors.length > 0) sections.push(`console/page errors:\n${diagnostics.errors.join("\n")}`);
+  if (diagnostics.requests.length > 0) sections.push(`network diagnostics:\n${diagnostics.requests.join("\n")}`);
+  return sections.join("\n\n");
+}
+
+export function startServer() {
+  const server = createServer(async (request, response) => {
+    try {
+      const pathname = decodeURIComponent(new URL(request.url, "http://127.0.0.1").pathname);
+      const filePath = await resolveFile(pathname);
+      response.setHeader("Content-Type", mimeTypes.get(extname(filePath)) || "application/octet-stream");
+      response.end(await readFile(filePath));
+    } catch (error) {
+      response.statusCode = error.code === "ENOENT" ? 404 : 500;
+      response.end(error.message);
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({ instance: server, url: `http://127.0.0.1:${port}` });
+    });
+  });
+}
+
+async function resolveFile(pathname) {
+  const requested = pathname.endsWith("/") ? `${pathname}index.html` : pathname;
+  const filePath = normalize(join(root, requested));
+  const rel = relative(root, filePath);
+  if (rel.startsWith("..")) throw new Error("request escaped repository root");
+
+  const info = await stat(filePath);
+  if (info.isDirectory()) return join(filePath, "index.html");
+  return filePath;
+}