webvas 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5741995c39bcdce271bdf34cf96cc377d48cfb43abc9705d8beb6f2b49345034
-  data.tar.gz: 77fee6bec1cafd49ff8fb62b65ca00afeff04e618986b73977b375b13d652ad7
+  metadata.gz: 8a2023d01aad96f20ed9938d18ddedf254edd56ba69c2dc0383a84d00c2efd03
+  data.tar.gz: 4ad4fbd5919583226a281186a717d59eb038a0d1aac25e79716ccd8cc5775fb9
 SHA512:
-  metadata.gz: 7b98cc6279a621f860e0bde96266c11c54913e5331d0a80f4a880ae17caf3b277bd3699dbf5c34913a4376efc792b05b1793ec152933438d4d2a6819789a21cd
-  data.tar.gz: cf95c627be83f6525fd9a5205ffd253367cb06fc6aed829e9d1f056b1bad192c6a41f983e145f71c18b7d494faf6cc38adf10df0b95752eeb53192e2be6485f5
+  metadata.gz: 034c1b98ebf7a2607d8b985c21e63394ccca5b228bf99fc39dc74bb710ea6ae4e72b2ae13968e7b8108f3f3a71280c0119ab025290274d1b8b877b3bba3aeb78
+  data.tar.gz: affd813bbbbf4ab437bfa794c5d56dd54187c27e4c6315bec9ad76b40bde5f9fae4dfa6941641e668f56f8a32506c40efe9c0e7983a5b5da32206a03209f1439

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.3.1] - 2026-09-25
+
+### Fixed
+
+- Build the current WebAssembly runtime before browser tests and Pages deployment.
+- Include the CLI executable and runtime build inputs in the gem.
+- Require a Gesso release that supports browser sketches.
+
+## [0.3.0] - 2026-09-25
+
+### Added
+
+- Gesso sketches and RLSL WGSL shaders in the browser runtime.
+- An editable playground with example modes, compressed share URLs, and standalone HTML downloads.
+- `webvas new`, `serve`, and `build` commands, including custom WebAssembly runtime builds.
+- Worker reset between runs, Ruby error reporting, and frame performance measurements.
+
 ## [0.1.0] - 2026-09-25
 
 Initial release

data/README.md

@@ -2,80 +2,107 @@
 
 # Webvas
 
-**Run RBGL sketches in a browser with Ruby.**
+**Write Ruby graphics sketches and run them in a browser.**
 
-Webvas connects RBGL's software renderer to an `OffscreenCanvas` and drives one frame at a time with `requestAnimationFrame`.
-
-[Live example](https://rbgfx.github.io/webvas/) · [Ruby API](#ruby-api) · [Browser requirements](#browser-requirements)
+[Playground](https://rbgfx.github.io/webvas/) · [Ruby API](#ruby-api) · [CLI](#cli) · [Security](#security)
 
 </div>
 
+Webvas connects RBGL's software renderer to an `OffscreenCanvas` and advances one frame at a time with `requestAnimationFrame`. The playground includes RBGL, Gesso, and RLSL examples, shareable source links, and single-file HTML downloads.
+
 ## Features
 
-- RBGL browser backend for RGBA frames and pointer, keyboard, and wheel events
-- Frame scheduling through `RBGL::GUI::Window#step`
-- Standalone loader for `<script type="text/ruby" data-webvas>`
-- Runtime published with the example site; no local WebAssembly build is needed to use it
+- RBGL canvas backend with pointer, keyboard, and wheel input
+- Gesso sketch runner and RLSL WGSL compute shaders
+- Fresh Ruby worker for each playground run, with visible errors and frame measurements
+- Deflate-compressed source in URL fragments; source is not sent to a Webvas service
+- `webvas new`, `serve`, and `build` for standalone sketch projects
+- Browser runtime built with Webvas, RBGL, Tessel, Gesso, Glyphic, and RLSL
 
-## Install
+## Quick start
 
-Add Webvas to the Ruby bundle used to prepare your WebAssembly runtime:
+Add the loader and a Ruby source file to an HTML page:
+
+~~~html
+<canvas id="screen" width="320" height="240"></canvas>
+<script type="text/ruby" data-webvas data-canvas="#screen" src="app.rb"></script>
+<script src="https://rbgfx.github.io/webvas/loader.js"
+        data-runtime="https://rbgfx.github.io/webvas/assets/webvas.wasm"></script>
+~~~
+
+In `app.rb`:
 
 ~~~ruby
-gem "webvas"
+require "gesso"
+
+Gesso.run(width: 320, height: 240, runner: :web) do
+  draw do
+    background "#101827"
+    no_stroke
+    fill "#f07850"
+    circle width / 2, height / 2, 36
+  end
+end
 ~~~
 
-The browser runtime must also include `rbgl` and its dependencies. When using the runtime distributed with the Webvas example, no local build is required.
+The official runtime is built with these gems already included. A runtime URL can be set with `data-runtime`; use the same URL for sketches that bundle their own dependencies.
 
-## Quick start
+## Ruby API
 
-Add a canvas, a Ruby script, and the loader to an HTML page:
+Create an `RBGL::GUI::Window` with `Webvas::Backend.new`, then call `Webvas.run(window)` with a frame block. The block receives the RBGL context and delta time. `Webvas.run` reuses one animation callback, closes the window on stop or error, and reports exceptions through the bridge.
 
-~~~html
-<canvas id="screen" width="320" height="240"></canvas>
-<script type="text/ruby" data-webvas>
-  require "rbgl"
-  require "webvas"
-
-  window = RBGL::GUI::Window.new(
-    width: 320,
-    height: 240,
-    backend: Webvas::Backend.new(width: 320, height: 240)
-  )
-
-  Webvas.run(window) do |context, _delta_time|
-    context.clear
-    # Bind an RBGL pipeline and draw here.
+`Webvas::Backend` accepts `width`, `height`, `canvas`, `title`, and `pixelated`. Canvas drawing dimensions set render resolution; CSS scales its display. Pointer coordinates are mapped from CSS pixels to render pixels. Focus the canvas to send keyboard input.
+
+RLSL can generate the WGSL source for WebGPU:
+
+~~~ruby
+require "rlsl"
+require "webvas"
+
+wgsl = RLSL.to_wgsl(:plasma) do
+  uniforms { float :time }
+  fragment do |frag_coord, resolution, uniforms|
+    uv = frag_coord / resolution.y
+    vec3(sin(uv.x + uniforms.time), uv.y, 0.6)
   end
-</script>
-<script src="https://rbgfx.github.io/webvas/loader.js"></script>
+end
+Webvas.run_shader(Webvas::Shader.new(wgsl))
 ~~~
 
-The loader reads `assets/webvas.wasm` beside itself by default. Set `data-runtime` on the loader script to use another HTTPS or same-origin runtime URL. Set `data-canvas` on the Ruby script and use the same selector in `Webvas::Backend` when the canvas is not `#screen`.
+WebGPU requires a supported browser, secure context, and GPU adapter. The shader runner updates the `resolution` and `time` uniforms automatically.
 
-## Ruby API
-
-Create an `RBGL::GUI::Window` with a `Webvas::Backend`, then pass it to `Webvas.run`. The callback receives the RBGL context and elapsed seconds. `Webvas.run` reuses one callback for each animation frame and closes the window when it stops or raises an exception.
+## CLI
 
-`Webvas::Backend` accepts `width`, `height`, `canvas`, `title`, and `pixelated`. The canvas size sets the rendering resolution; CSS can scale its display size. With `pixelated: true`, scaled output uses nearest-neighbor display.
+~~~sh
+gem install webvas
+webvas new my-sketch
+cd my-sketch
+webvas serve
+webvas build -o dist
+~~~
 
-Pointer coordinates are mapped from the canvas display bounds to rendering pixels. Pointer buttons, keyboard keys, modifier keys, and wheel deltas are converted to RBGL events. Focus the canvas to send keyboard events.
+`serve` binds to `127.0.0.1:8000`, serves `.wasm` as `application/wasm`, and reloads when project files change. Use `--host`, `--port`, or `--root` to change its defaults. `build` writes a static site that loads the official runtime. To bundle a custom runtime, add `ruby_wasm` and `js` to the project's `Gemfile`, install it, then run `webvas build --runtime custom`; the project's bundle is passed to `rbwasm build`.
 
-## Browser requirements
+## Playground
 
-- WebAssembly, module workers, and `OffscreenCanvas`
-- A secure context when loading the page over the network
-- A Ruby runtime built with Webvas, RBGL, and RBGL's dependencies
+Open the [Webvas playground](https://rbgfx.github.io/webvas/). Choose a mode and example, edit the Ruby, then press **Run** or **Ctrl/Cmd + Enter**. Each run starts a fresh worker and canvas. **Share** compresses the source with `CompressionStream` into the URL fragment; **Download HTML** embeds the source as escaped JSON and keeps the runtime on its CDN URL.
 
-Ruby runs in a worker without access to the page DOM. The `js` gem exposes APIs available to that worker, so this worker should not be treated as a security sandbox for hostile code. The page's Content Security Policy must allow the worker, runtime URL, and WebAssembly compilation.
+## Security and limitations
 
-Blocking frame loops and `sleep` cannot drive animation in the browser. Use `Webvas.run` to advance the window one frame at a time. WebAssembly threads and compiling native extensions in the browser are not supported.
+- Ruby runs in a worker, but the worker is not a security sandbox. Sketches can call browser APIs and make network requests allowed by the page's Content Security Policy. Inspect shared code before running it.
+- Webvas does not set cookies, store source, or send code to a Webvas service. The GitHub Pages project URL shares the `rbgfx.github.io` origin; a dedicated hostname requires a separate hosting or domain decision.
+- Runtime downloads omit browser credentials. Pages need to allow the chosen loader, worker, and runtime in their Content Security Policy.
+- The `js` gem evaluates Ruby-to-JavaScript bridge code, so the playground policy requires `unsafe-eval` and `wasm-unsafe-eval`. This weakens script restrictions; use a dedicated origin for untrusted sketches.
+- The 0.3.0 candidate was verified locally in Chromium 153 on macOS arm64. Firefox, Safari, and mobile browsers are not verified; the software renderer needs `OffscreenCanvas` and module workers, and RLSL also needs WebGPU.
+- Blocking loops and `sleep` stop browser frame progress. WebAssembly threads and compiling native extensions in the browser are unsupported.
+- Ruby source is limited to 32 KiB. RGBA frames use base64 transfer; a 320×240 frame is 307,200 bytes before encoding.
+- RLSL mode requires WebGPU; RBGL and Gesso modes use the software renderer.
 
-Ruby source is limited to 32 KiB. Frame pixels use base64 between Ruby and JavaScript; a 320×240 RGBA frame is 307,200 bytes before encoding and 409,600 bytes after encoding.
+See [browser security notes](docs/security.md) and [runtime/performance records](docs/performance.md).
 
 ## Development
 
-The repository expects adjacent checkouts of `larb`, `rbgl`, and `tessel`.
+The repository expects adjacent checkouts of Larb, RBGL, Tessel, Gesso, Glyphic, and RLSL. Ruby unit tests run under CRuby; the browser integration tests use Chromium and the locally built runtime.
 
 ~~~sh
 bundle install
@@ -90,8 +117,6 @@ npx playwright install chromium
 npm run test:browser
 ~~~
 
-The Pages workflow builds the WebAssembly runtime, checks the browser loader in Chromium, and deploys the static example.
-
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/webvas

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "webvas"
+require_relative "../lib/webvas/cli"
+
+exit Webvas::CLI.run

data/js/bridge.js

@@ -4,6 +4,107 @@
   const pendingEvents = [];
   const eventLimit = 2048;
 
+  function uniformLayout(wgsl) {
+    const source = wgsl.match(/struct\s+Uniforms\s*\{([\s\S]*?)\}/)?.[1];
+    if (!source) throw new Error("WGSL must define a Uniforms struct");
+    const fields = [...source.matchAll(/\b(\w+)\s*:\s*(f32|i32|u32|vec[234]<f32>)\s*,/g)];
+    let offset = 0;
+    const layout = fields.map(([, name, type]) => {
+      const components = Number(type.match(/^vec(\d)/)?.[1] || 1);
+      const align = components === 1 ? 4 : components === 2 ? 8 : 16;
+      const size = components === 3 ? 12 : components * 4;
+      offset = Math.ceil(offset / align) * align;
+      const field = { name, type, offset, components };
+      offset += size;
+      return field;
+    });
+    if (!layout.length) throw new Error("WGSL Uniforms must contain supported numeric fields");
+    return { fields: layout, size: Math.ceil(offset / 16) * 16 };
+  }
+
+  function startShader(selector, wgsl, initialUniforms) {
+    const canvas = globalThis.WebvasCanvases?.[selector];
+    if (!(canvas instanceof OffscreenCanvas)) throw new Error("Canvas not found: " + selector);
+    if (!navigator.gpu) throw new Error("WebGPU is unavailable. Try a browser with WebGPU enabled.");
+    if (!canvas.width || !canvas.height) throw new Error("Shader canvas size must be positive");
+
+    const startTime = performance.now();
+    let metricFrames = 0;
+    let metricStart = startTime;
+    let metricDispatchMs = 0;
+    const uniforms = JSON.parse(initialUniforms);
+    const layout = uniformLayout(wgsl);
+    const frame = async () => {
+      try {
+        const adapter = await navigator.gpu.requestAdapter();
+        if (!adapter) throw new Error("WebGPU could not find an adapter.");
+        const device = await adapter.requestDevice();
+        const context = canvas.getContext("webgpu");
+        if (!context) throw new Error("WebGPU canvas is unavailable.");
+        context.configure({ device, format: "rgba8unorm", usage: GPUTextureUsage.STORAGE_BINDING, alphaMode: "opaque" });
+        const module = device.createShaderModule({ code: wgsl });
+        const info = await module.getCompilationInfo();
+        const errors = info.messages.filter(message => message.type === "error");
+        if (errors.length) throw new Error(errors.map(error => error.message).join("\n"));
+        const pipeline = await device.createComputePipelineAsync({
+          layout: "auto", compute: { module, entryPoint: "main" }
+        });
+        const buffer = device.createBuffer({ size: layout.size, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        const draw = () => {
+          try {
+            const started = performance.now();
+            const data = new DataView(new ArrayBuffer(layout.size));
+            for (const field of layout.fields) {
+              let value = uniforms[field.name];
+              if (field.name === "resolution") value = [canvas.width, canvas.height];
+              if (field.name === "time" && value === undefined) value = (performance.now() - startTime) / 1000;
+              const values = field.components === 1 ? [value ?? 0] : Array.isArray(value) ? value : [];
+              for (let index = 0; index < field.components; index += 1) {
+                const at = field.offset + index * 4;
+                if (field.type === "i32") data.setInt32(at, Number(values[index] || 0), true);
+                else if (field.type === "u32") data.setUint32(at, Number(values[index] || 0), true);
+                else data.setFloat32(at, Number(values[index] || 0), true);
+              }
+            }
+            device.queue.writeBuffer(buffer, 0, data);
+            const bindGroup = device.createBindGroup({
+              layout: pipeline.getBindGroupLayout(0),
+              entries: [
+                { binding: 0, resource: { buffer } },
+                { binding: 1, resource: context.getCurrentTexture().createView() }
+              ]
+            });
+            const encoder = device.createCommandEncoder();
+            const pass = encoder.beginComputePass();
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bindGroup);
+            pass.dispatchWorkgroups(Math.ceil(canvas.width / 8), Math.ceil(canvas.height / 8));
+            pass.end();
+            device.queue.submit([encoder.finish()]);
+            metricDispatchMs += performance.now() - started;
+            metricFrames += 1;
+            if (metricFrames === 60) {
+              const elapsed = performance.now() - metricStart;
+              globalThis.postMessage({ type: "webvas:metrics", frames: metricFrames, elapsedMs: elapsed,
+                fps: metricFrames * 1000 / elapsed, averagePresentMs: metricDispatchMs / metricFrames });
+              metricFrames = 0;
+              metricStart = performance.now();
+              metricDispatchMs = 0;
+            }
+            globalThis.window.requestAnimationFrame(draw);
+          } catch (error) {
+            globalThis.WebvasBridge.showError(error.message || String(error), "");
+          }
+        };
+        globalThis.window.requestAnimationFrame(draw);
+      } catch (error) {
+        globalThis.WebvasBridge.showError(error.message || String(error), "");
+      }
+    };
+    frame();
+    return true;
+  }
+
   function queue(handle, event) {
     if (handle.events.length === eventLimit) handle.events.shift();
     handle.events.push(event);
@@ -17,7 +118,7 @@
       canvas.height = height;
       const context = canvas.getContext("2d", { alpha: false });
       if (!context) throw new Error("Canvas 2D is unavailable");
-      const handle = { id: nextId++, canvas, context, events: pendingEvents.splice(0) };
+      const handle = { id: nextId++, canvas, context, events: pendingEvents.splice(0), metricStart: performance.now(), metricFrames: 0, metricPresentMs: 0 };
       globalThis.postMessage({ type: "webvas:pixelated", selector, enabled: pixelated });
       canvases.set(handle.id, handle);
       return handle.id;
@@ -26,6 +127,7 @@
     present(id, encoded, width, height) {
       const handle = canvases.get(id);
       if (!handle) throw new Error("Canvas backend is closed");
+      const started = performance.now();
       const { canvas, context } = handle;
       if (canvas.width !== width || canvas.height !== height) {
         canvas.width = width;
@@ -36,9 +138,23 @@
       const pixels = new Uint8ClampedArray(binary.length);
       for (let index = 0; index < binary.length; index += 1) pixels[index] = binary.charCodeAt(index);
       context.putImageData(new ImageData(pixels, width, height), 0, 0);
+      handle.metricFrames += 1;
+      handle.metricPresentMs += performance.now() - started;
+      if (handle.metricFrames === 60) {
+        const elapsed = performance.now() - handle.metricStart;
+        globalThis.postMessage({ type: "webvas:metrics", frames: handle.metricFrames, elapsedMs: elapsed,
+          fps: handle.metricFrames * 1000 / elapsed, averagePresentMs: handle.metricPresentMs / handle.metricFrames });
+        handle.metricStart = performance.now();
+        handle.metricFrames = 0;
+        handle.metricPresentMs = 0;
+      }
       return true;
     },
 
+    runShader(selector, wgsl, uniforms) {
+      return startShader(selector, wgsl, uniforms);
+    },
+
     events(id) {
       const handle = canvases.get(id);
       return JSON.stringify(handle ? handle.events.splice(0) : []);

data/js/loader.js

@@ -3,44 +3,92 @@
   if (!loader) return;
 
   const base = new URL(".", loader.src);
-  const runtimeUrl = loader.dataset.runtime || new URL("./assets/webvas.wasm", base).href;
-  const workerUrl = new URL("./worker.js", base).href;
-  const bridgeUrl = new URL("./bridge.js", base).href;
+  const defaultRuntime = loader.dataset.runtime || new URL("./assets/webvas.wasm", base).href;
+  const sessions = new Map();
+  const sourceLimit = 32768;
+
+  function textSource(element) {
+    if (element.matches('script[type="application/json"][data-webvas-source]')) {
+      const payload = JSON.parse(element.textContent);
+      if (typeof payload.source !== "string") throw new Error("Embedded Ruby source is missing.");
+      return payload.source;
+    }
+    return element.textContent;
+  }
+
+  async function readSource(element) {
+    if (!element.src) return textSource(element);
+    const response = await fetch(element.src, { credentials: "omit" });
+    if (!response.ok) throw new Error(`Ruby source download failed: ${response.status}`);
+    return response.text();
+  }
+
+  function dispose(selector, replaceCanvas) {
+    const old = sessions.get(selector);
+    if (!old) return;
+    old.worker.terminate();
+    URL.revokeObjectURL(old.workerBlobUrl);
+    old.listeners.forEach(([target, type, listener, options]) => target.removeEventListener(type, listener, options));
+    if (replaceCanvas && old.canvas.isConnected) {
+      const canvas = old.canvas.cloneNode(false);
+      canvas.style.imageRendering = "";
+      old.canvas.replaceWith(canvas);
+    }
+    sessions.delete(selector);
+  }
+
+  async function start(source, { canvas: selector = "#screen", runtime, statusElement, onStatus } = {}) {
+    if (typeof source !== "string") throw new TypeError("Ruby source must be a string.");
+    if (new TextEncoder().encode(source).length > sourceLimit) throw new Error("Ruby source exceeds 32 KB.");
+    dispose(selector, true);
 
-  async function run(sourceElement) {
-    const selector = sourceElement.dataset.canvas || "#screen";
     const canvas = document.querySelector(selector);
     if (!(canvas instanceof HTMLCanvasElement)) throw new Error(`Canvas not found: ${selector}`);
-    if (new TextEncoder().encode(sourceElement.textContent).length > 32768) throw new Error("Ruby source exceeds 32 KB.");
-
-    const status = document.createElement("output");
-    status.setAttribute("role", "status");
-    status.setAttribute("aria-live", "polite");
-    canvas.insertAdjacentElement("afterend", status);
-    const report = message => { status.textContent = message; };
-    report("Loading Ruby runtime…");
+    const status = statusElement || document.createElement("output");
+    if (!statusElement) {
+      status.setAttribute("role", "status");
+      status.setAttribute("aria-live", "polite");
+      canvas.insertAdjacentElement("afterend", status);
+    }
+    const report = detail => {
+      if (onStatus) onStatus(detail);
+      else status.textContent = detail.message || "";
+    };
+    report({ state: "loading", message: "Loading Ruby runtime…" });
     if (canvas.tabIndex < 0) canvas.tabIndex = 0;
 
-    const response = await fetch(workerUrl, { credentials: "omit" });
+    const response = await fetch(new URL("./worker.js", base), { credentials: "omit" });
     if (!response.ok) throw new Error(`Worker download failed: ${response.status}`);
     const workerBlobUrl = URL.createObjectURL(new Blob([await response.text()], { type: "text/javascript" }));
     const worker = new Worker(workerBlobUrl, { type: "module", name: "webvas" });
-    worker.addEventListener("message", event => {
+    const listeners = [];
+    const session = { canvas, worker, workerBlobUrl, listeners };
+    sessions.set(selector, session);
+
+    const listen = (target, type, callback, options) => {
+      target.addEventListener(type, callback, options);
+      listeners.push([target, type, callback, options]);
+    };
+    listen(worker, "message", event => {
       const message = event.data || {};
-      if (message.type === "webvas:loading") report(message.message || "Loading Ruby runtime…");
+      if (message.type === "webvas:loading") report({ state: "loading", message: message.message || "Loading Ruby runtime…" });
       else if (message.type === "webvas:ready") {
         URL.revokeObjectURL(workerBlobUrl);
-        worker.postMessage({ type: "webvas:run", source: sourceElement.textContent });
-      } else if (message.type === "webvas:started") report("Ruby sketch is running");
-      else if (message.type === "webvas:error") report([message.message, message.backtrace].filter(Boolean).join("\n"));
+        worker.postMessage({ type: "webvas:run", source });
+      } else if (message.type === "webvas:started") report({ state: "running", message: "Ruby sketch is running" });
+      else if (message.type === "webvas:error") report({ state: "error", message: message.message || "Ruby sketch failed", backtrace: message.backtrace || "" });
+      else if (message.type === "webvas:metrics") report({ state: "metrics", ...message });
       else if (message.type === "webvas:pixelated" && message.selector === selector) {
-        canvas.style.imageRendering = message.enabled ? "pixelated" : "auto";
+        const enabled = message.enabled === true || message.enabled === "true";
+        canvas.dataset.pixelated = String(enabled);
+        canvas.style.imageRendering = enabled ? "pixelated" : "auto";
       }
     });
-    worker.addEventListener("error", event => {
+    listen(worker, "error", event => {
       URL.revokeObjectURL(workerBlobUrl);
-      report(event.message || "Webvas worker failed");
+      report({ state: "error", message: event.message || "Webvas worker failed" });
     });
+    listen(worker, "messageerror", () => report({ state: "error", message: "Webvas worker sent an unreadable message." }));
 
     const forward = event => {
       if (event.type === "wheel") event.preventDefault();
@@ -54,7 +102,7 @@
         type: "webvas:input",
         event: {
           type: event.type === "pointercancel" ? "pointerup" : event.type,
-          clientX: event.clientX || 0, clientY: event.clientY || 0,
+          clientX: event.clientX ?? 0, clientY: event.clientY ?? 0,
           left: rect.left, top: rect.top, rectWidth: rect.width, rectHeight: rect.height,
           button: event.button, deltaX: event.deltaX, deltaY: event.deltaY,
           code: event.code, key: event.key, shiftKey: event.shiftKey,
@@ -63,24 +111,52 @@
       });
     };
     for (const type of ["pointerdown", "pointerup", "pointermove", "pointercancel", "keydown", "keyup", "wheel"]) {
-      canvas.addEventListener(type, forward, type === "wheel" ? { passive: false } : undefined);
+      listen(canvas, type, forward, type === "wheel" ? { passive: false } : undefined);
     }
 
+    if (typeof canvas.transferControlToOffscreen !== "function") throw new Error("OffscreenCanvas is unavailable in this browser.");
     const offscreen = canvas.transferControlToOffscreen();
     worker.postMessage({
       type: "webvas:init", canvas: offscreen, selector,
-      bridgeUrl, wasmUrl: new URL(runtimeUrl, document.baseURI).href
+      bridgeUrl: new URL("./bridge.js", base).href,
+      wasmUrl: new URL(runtime || defaultRuntime, document.baseURI).href
     }, [offscreen]);
+    return session;
+  }
+
+  async function run(source, options = {}) {
+    try {
+      return await start(source, options);
+    } catch (error) {
+      const detail = { state: "error", message: error.message || String(error) };
+      dispose(options.canvas || "#screen", true);
+      if (options.onStatus) options.onStatus(detail);
+      else if (options.statusElement) options.statusElement.textContent = detail.message;
+      else throw error;
+    }
   }
 
-  const start = () => document.querySelectorAll('script[type="text/ruby"][data-webvas]').forEach(element => {
-    run(element).catch(error => {
+  globalThis.WebvasPlayground = {
+    run,
+    stop(canvas = "#screen") { dispose(canvas, true); }
+  };
+
+  const startEmbedded = () => {
+    for (const element of document.querySelectorAll('script[type="text/ruby"][data-webvas],script[type="application/json"][data-webvas-source]')) {
       const status = document.createElement("output");
-      status.setAttribute("role", "alert");
-      status.textContent = error.message || String(error);
+      status.setAttribute("role", "status");
+      status.setAttribute("aria-live", "polite");
       element.insertAdjacentElement("afterend", status);
-    });
-  });
-  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start, { once: true });
-  else start();
+      readSource(element).then(source => run(source, {
+        canvas: element.dataset.canvas || "#screen",
+        runtime: element.dataset.runtime,
+        statusElement: status
+      })).catch(error => {
+        status.setAttribute("role", "alert");
+        status.textContent = error.message || String(error);
+      });
+    }
+  };
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", startEmbedded, { once: true });
+  else startEmbedded();
 })();

data/lib/webvas/backend.rb

@@ -19,7 +19,14 @@ module Webvas
     def set_pixels(buffer, width, height)
       width = Integer(width)
       height = Integer(height)
-      bytes = validate_rgba_buffer(buffer, width, height)
+      bytes = String.try_convert(buffer)
+      raise ArgumentError, "Pixel buffer must be a String" unless bytes
+
+      expected_size = width * height * 4
+      unless width.positive? && height.positive? && bytes.bytesize == expected_size
+        raise ArgumentError, "Pixel buffer size mismatch: expected #{expected_size}, got #{bytes.bytesize}"
+      end
+
       resize(width, height) if [width, height] != [@width, @height]
       @pending_pixels = [bytes, width, height]
       true

data/lib/webvas/bridge.rb

@@ -18,6 +18,10 @@ module Webvas
       @api.present(handle, Base64.strict_encode64(bytes), width, height)
     end
 
+    def run_shader(selector, wgsl, uniforms)
+      @api.runShader(selector, wgsl, JSON.generate(uniforms))
+    end
+
     def events(handle)
       JSON.parse(@api.events(handle).to_s)
     end

data/lib/webvas/cli.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require "socket"
+require "uri"
+
+module Webvas
+  class CLI
+    ROOT = File.expand_path("../..", __dir__)
+    CDN = "https://rbgfx.github.io/webvas"
+    LIVE_SCRIPT = '(()=>{const s=new EventSource("/__webvas/events");s.onmessage=()=>location.reload()})();'
+    CONTENT_TYPES = {
+      ".css" => "text/css; charset=utf-8", ".html" => "text/html; charset=utf-8",
+      ".js" => "text/javascript; charset=utf-8", ".json" => "application/json",
+      ".png" => "image/png", ".svg" => "image/svg+xml", ".wasm" => "application/wasm",
+      ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".gif" => "image/gif",
+      ".rb" => "text/plain; charset=utf-8", ".txt" => "text/plain; charset=utf-8"
+    }.freeze
+
+    def self.run(arguments = ARGV, out: $stdout, err: $stderr)
+      command = arguments.shift
+      case command
+      when "new" then new_project(arguments, out:)
+      when "serve" then serve(arguments, out:)
+      when "build" then build(arguments, out:)
+      when "--help", "-h", nil then out.puts help; 0
+      else raise Error, "unknown command: #{command}\n#{help}"
+      end
+    rescue Error, OptionParser::ParseError, SystemCallError, Interrupt => error
+      err.puts(error.message) unless error.is_a?(Interrupt)
+      error.is_a?(Interrupt) ? 0 : 1
+    end
+
+    def self.help
+      <<~HELP
+        Usage: webvas <command>
+
+        Commands:
+          new NAME             Create a browser sketch project
+          serve [--root DIR]   Serve the current project and reload on changes
+          build [-o DIR]       Build a static site using the official runtime
+               [--runtime custom]  Build a runtime from the project's Gemfile
+      HELP
+    end
+
+    def self.new_project(arguments, out:)
+      name = arguments.shift
+      raise Error, "Usage: webvas new NAME" unless name && arguments.empty?
+      raise Error, "Project name must be one path component." unless name.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/) && !%w[. ..].include?(name)
+
+      destination = File.expand_path(name)
+      raise Error, "Directory already exists and is not empty: #{destination}" if File.directory?(destination) && !Dir.empty?(destination)
+      raise Error, "Path already exists: #{destination}" if File.exist?(destination) && !File.directory?(destination)
+
+      FileUtils.mkdir_p(destination)
+      html = project_html.gsub("__WEBVAS_LOADER__", "#{CDN}/loader.js")
+        .gsub("__WEBVAS_RUNTIME__", "#{CDN}/assets/webvas.wasm")
+      files = {
+        "index.html" => html,
+        "app.rb" => project_source,
+        "Gemfile" => project_gemfile
+      }
+      existing = files.keys.select { |file| File.exist?(File.join(destination, file)) }
+      raise Error, "Refusing to overwrite: #{existing.join(', ')}" unless existing.empty?
+      files.each { |file, content| File.write(File.join(destination, file), content) }
+      out.puts "Created #{destination}"
+      0
+    end
+
+    def self.serve(arguments, out:)
+      options = { host: "127.0.0.1", port: 8000, root: Dir.pwd }
+      OptionParser.new do |parser|
+        parser.on("--host HOST") { |value| options[:host] = value }
+        parser.on("-p", "--port PORT", Integer) { |value| options[:port] = value }
+        parser.on("--root DIR") { |value| options[:root] = value }
+      end.parse!(arguments)
+      raise Error, "Unexpected arguments: #{arguments.join(' ')}" unless arguments.empty?
+      root = File.realpath(options[:root])
+      raise Error, "Project root must be a directory: #{root}" unless File.directory?(root)
+      raise Error, "Port must be between 0 and 65535." unless (0..65_535).cover?(options[:port])
+
+      server = Server.new(root, host: options[:host], port: options[:port])
+      out.puts "Serving #{root} at http://#{options[:host]}:#{server.port}"
+      server.start
+      0
+    ensure
+      server&.close
+    end
+
+    def self.build(arguments, out:)
+      options = { output: "dist", runtime: "official", root: Dir.pwd }
+      OptionParser.new do |parser|
+        parser.on("-o", "--output DIR") { |value| options[:output] = value }
+        parser.on("--runtime RUNTIME") { |value| options[:runtime] = value }
+        parser.on("--root DIR") { |value| options[:root] = value }
+      end.parse!(arguments)
+      raise Error, "Unexpected arguments: #{arguments.join(' ')}" unless arguments.empty?
+      raise Error, "Runtime must be official or custom." unless %w[official custom].include?(options[:runtime])
+
+      source = File.realpath(options[:root])
+      destination = File.expand_path(options[:output], source)
+      raise Error, "Build output cannot overwrite the project." if destination == source
+      if destination == File.join(source, "assets") || destination.start_with?(File.join(source, "assets") + File::SEPARATOR)
+        raise Error, "Build output cannot be inside the project's assets directory."
+      end
+      raise Error, "Build output cannot contain the project." if source.start_with?(destination + File::SEPARATOR)
+      raise Error, "Project is missing index.html or app.rb." unless %w[index.html app.rb].all? { |file| File.file?(File.join(source, file)) }
+
+      FileUtils.mkdir_p(destination)
+      %w[index.html app.rb].each { |file| FileUtils.cp(File.join(source, file), destination) }
+      assets = File.join(source, "assets")
+      copy_assets(assets, File.join(destination, "assets")) if File.directory?(assets)
+      index = File.read(File.join(destination, "index.html"))
+      if options[:runtime] == "custom"
+        build_custom_runtime(source, File.join(destination, "assets"))
+        webvas_assets = File.join(destination, "assets", "webvas")
+        FileUtils.mkdir_p(webvas_assets)
+        %w[bridge.js loader.js worker.js].each do |file|
+          FileUtils.cp(File.join(ROOT, "js", file), webvas_assets)
+        end
+        index = index.gsub("__WEBVAS_LOADER__", "./assets/webvas/loader.js")
+          .gsub("__WEBVAS_RUNTIME__", "./assets/webvas.wasm")
+      else
+        index = index.gsub("__WEBVAS_LOADER__", "#{CDN}/loader.js")
+          .gsub("__WEBVAS_RUNTIME__", "#{CDN}/assets/webvas.wasm")
+      end
+      index = index.gsub("<!-- webvas:dev -->", "")
+      File.write(File.join(destination, "index.html"), index)
+      out.puts "Built #{destination} (#{options[:runtime]} runtime)"
+      0
+    end
+
+    def self.copy_assets(source, destination)
+      FileUtils.mkdir_p(destination)
+      Dir.children(source).each do |name|
+        path = File.join(source, name)
+        next if File.symlink?(path)
+
+        FileUtils.cp_r(path, destination)
+      end
+    end
+    private_class_method :copy_assets
+
+    def self.build_custom_runtime(source, assets)
+      gemfile = File.join(source, "Gemfile")
+      raise Error, "Custom runtime requires a project Gemfile." unless File.file?(gemfile)
+      FileUtils.mkdir_p(assets)
+      command = ["bundle", "exec", "rbwasm", "build", "--ruby-version", "4.0",
+        "--target", "wasm32-unknown-wasip1", "--build-profile", "full"]
+      patch = File.join(ROOT, "patches", "psych-wasi.patch")
+      command.concat(["--patch", patch]) if File.file?(patch)
+      command.concat(["-o", File.join(assets, "webvas.wasm")])
+      success = Dir.chdir(source) { system({ "BUNDLE_GEMFILE" => gemfile }, *command) }
+      raise Error, "Custom runtime build failed. Install the project's bundle and check rbwasm." unless success
+    end
+    private_class_method :build_custom_runtime
+
+    def self.project_html
+      <<~HTML
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://rbgfx.github.io https://cdn.jsdelivr.net 'unsafe-eval' 'wasm-unsafe-eval'; worker-src 'self' blob:; connect-src 'self' https://rbgfx.github.io https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'">
+          <title>My Webvas sketch</title>
+          <style>body{margin:2rem auto;max-width:760px;padding:0 1rem;background:#101312;color:#e7e9e2;font:16px/1.5 system-ui}canvas{display:block;width:min(100%,640px);height:auto;aspect-ratio:4/3;background:#101827;image-rendering:pixelated}output{display:block;white-space:pre-wrap;overflow-wrap:anywhere}</style>
+        </head>
+        <body>
+          <h1>My Webvas sketch</h1>
+          <canvas id="screen" width="320" height="240" aria-label="Ruby sketch"></canvas>
+          <script type="text/ruby" data-webvas data-canvas="#screen" src="./app.rb"></script>
+          <!-- webvas:dev -->
+          <script data-webvas-loader src="__WEBVAS_LOADER__" data-runtime="__WEBVAS_RUNTIME__"></script>
+        </body>
+        </html>
+      HTML
+    end
+    private_class_method :project_html
+
+    def self.project_source
+      <<~RUBY
+        require "gesso"
+
+        Gesso.run(width: 320, height: 240, runner: :web, pixelated: true) do
+          draw do
+            background "#101827"
+            no_stroke
+            fill "#f07850"
+            circle width / 2 + Math.sin(frame_count * 0.05) * 60, height / 2, 28
+          end
+        end
+      RUBY
+    end
+    private_class_method :project_source
+
+    def self.project_gemfile
+      <<~RUBY
+        source "https://rubygems.org"
+
+        gem "ruby_wasm", "~> 2.10.1"
+        gem "js", "~> 2.10.1"
+        gem "webvas", "~> #{Webvas::VERSION}"
+        gem "rbgl"
+        gem "gesso"
+        gem "rlsl"
+        gem "glyphic"
+      RUBY
+    end
+    private_class_method :project_gemfile
+
+    class Server
+      attr_reader :port
+
+      def initialize(root, host:, port:)
+        @root = File.realpath(root)
+        @listener = TCPServer.new(host, port)
+        @port = @listener.addr[1]
+        @threads = []
+      end
+
+      def start
+        loop do
+          socket = @listener.accept
+          @threads << Thread.new(socket) { |client| handle(client) }
+        end
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      def close
+        @listener.close unless @listener.closed?
+        @threads.each { |thread| thread.kill if thread.alive? }
+      end
+
+      private
+
+      def handle(socket)
+        request = socket.gets("\r\n", 8192)
+        return unless request
+        method, target = request.split(" ", 3)
+        header_bytes = 0
+        while (line = socket.gets("\r\n")) && line != "\r\n"
+          header_bytes += line.bytesize
+          return response(socket, 400, "text/plain; charset=utf-8", "Headers too large") if header_bytes > 16_384
+        end
+        return response(socket, 405, "text/plain", "GET only") unless method == "GET"
+        return response(socket, 400, "text/plain; charset=utf-8", "Bad request") unless target
+
+        uri = URI.parse(target)
+        return events(socket) if uri.path == "/__webvas/events"
+        return response(socket, 200, "text/javascript; charset=utf-8", LIVE_SCRIPT) if uri.path == "/__webvas/live.js"
+
+        file = safe_file(uri.path)
+        return response(socket, 404, "text/plain; charset=utf-8", "Not found") unless file
+        body = File.binread(file)
+        if File.basename(file) == "index.html" && body.include?("<!-- webvas:dev -->")
+          body = body.sub("<!-- webvas:dev -->", '<script src="/__webvas/live.js"></script>')
+        end
+        response(socket, 200, CONTENT_TYPES.fetch(File.extname(file), "application/octet-stream"), body)
+      rescue URI::InvalidURIError, ArgumentError
+        response(socket, 400, "text/plain; charset=utf-8", "Bad request")
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        socket.close unless socket.closed?
+      end
+
+      def safe_file(path)
+        decoded = URI::RFC2396_PARSER.unescape(path)
+        return if decoded.include?("\0")
+        parts = decoded.split("/")
+        return if parts.any? { |part| part.start_with?(".") }
+        return if %w[.bundle build dist node_modules tmp vendor].include?(parts.first)
+        candidate = File.expand_path(decoded.delete_prefix("/"), @root)
+        return unless candidate.start_with?("#{@root}#{File::SEPARATOR}") || candidate == @root
+
+        candidate = File.join(candidate, "index.html") if File.directory?(candidate)
+        real = File.realpath(candidate)
+        return if real != @root && !real.start_with?("#{@root}#{File::SEPARATOR}")
+        return unless File.file?(real)
+
+        real
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+
+      def signature
+        hidden = %w[.bundle build dist node_modules tmp vendor]
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: @root).filter_map do |name|
+          next if name == "." || name == ".." || name.split("/").any? { |part| hidden.include?(part) || part.start_with?(".") }
+          path = File.join(@root, name)
+          stat = File.stat(path) rescue next
+          [name, stat.mtime.to_f, stat.size] if stat.file?
+        end.sort
+      end
+
+      def events(socket)
+        previous = signature
+        socket.write("HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nCache-Control: no-cache\r\nConnection: keep-alive\r\nX-Content-Type-Options: nosniff\r\n\r\n: connected\n\n")
+        loop do
+          sleep 0.5
+          current = signature
+          if current != previous
+            socket.write("data: reload\n\n")
+            previous = current
+          end
+        end
+      end
+
+      def response(socket, status, type, body)
+        label = { 200 => "OK", 400 => "Bad Request", 404 => "Not Found", 405 => "Method Not Allowed" }.fetch(status)
+        socket.write("HTTP/1.1 #{status} #{label}\r\nContent-Type: #{type}\r\nContent-Length: #{body.bytesize}\r\nCache-Control: no-store\r\nX-Content-Type-Options: nosniff\r\nConnection: close\r\n\r\n")
+        socket.write(body)
+      end
+    end
+  end
+end

data/lib/webvas/shader.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Webvas
+  class Shader
+    attr_reader :wgsl, :canvas
+
+    def initialize(wgsl, canvas: "#screen")
+      @wgsl = String(wgsl)
+      @canvas = String(canvas)
+      raise ArgumentError, "WGSL source cannot be empty" if @wgsl.empty?
+    end
+  end
+end

data/lib/webvas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Webvas
-  VERSION = "0.1.0"
+  VERSION = "0.3.1"
 end

data/lib/webvas.rb

@@ -7,6 +7,7 @@ require_relative "webvas/backend"
 require_relative "webvas/input"
 require_relative "webvas/key_map"
 require_relative "webvas/runner"
+require_relative "webvas/shader"
 
 module Webvas
   class Error < StandardError; end
@@ -36,4 +37,10 @@ module Webvas
     Bridge.new.show_error(error.message, error.backtrace || [])
   end
 
+  def self.run_shader(shader, uniforms: {})
+    raise TypeError, "expected a Webvas::Shader" unless shader.is_a?(Shader)
+
+    Bridge.new.run_shader(shader.canvas, shader.wgsl, uniforms)
+  end
+
 end

data/patches/psych-wasi.patch

@@ -0,0 +1,9 @@
+--- a/ext/psych/extconf.rb
++++ b/ext/psych/extconf.rb
+@@ -40,3 +40,3 @@
+   # default to pre-installed libyaml
+-elsif pkg_config('yaml-0.1')
++elsif !CROSS_COMPILING && pkg_config('yaml-0.1')
+   # found with pkg-config
+ else
+   dir_config('libyaml')

data/sig/webvas.rbs

@@ -4,10 +4,17 @@ module Webvas
   class Error < StandardError
   end
 
+  class Shader
+    attr_reader wgsl: String
+    attr_reader canvas: String
+    def initialize: (String wgsl, ?canvas: String) -> void
+  end
+
   class Bridge
     def initialize: (?api: untyped) -> void
     def attach: (String selector, Integer width, Integer height, pixelated: bool) -> untyped
     def present: (untyped handle, String bytes, Integer width, Integer height) -> untyped
+    def run_shader: (String selector, String wgsl, Hash[String, untyped] uniforms) -> untyped
     def events: (untyped handle) -> Array[Hash[String, untyped]]
     def resize: (untyped handle, Integer width, Integer height) -> untyped
     def close: (untyped handle) -> untyped
@@ -45,4 +52,5 @@ module Webvas
 
   def self.run: (RBGL::GUI::Window window, ?scheduler: Scheduler, ?on_error: Proc) { (RBGL::Engine::Context, Float) -> void } -> Proc
   def self.report_error: (StandardError error) -> untyped
+  def self.run_shader: (Shader shader, ?uniforms: Hash[Symbol | String, untyped]) -> untyped
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: webvas
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Yudai Takada
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -116,23 +116,28 @@ dependencies:
 description: An RBGL canvas backend and browser loader powered by ruby.wasm.
 email:
 - t.yudai92@gmail.com
-executables: []
+executables:
+- webvas
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- exe/webvas
 - js/bridge.js
 - js/loader.js
 - js/worker.js
 - lib/webvas.rb
 - lib/webvas/backend.rb
 - lib/webvas/bridge.rb
+- lib/webvas/cli.rb
 - lib/webvas/input.rb
 - lib/webvas/key_map.rb
 - lib/webvas/runner.rb
+- lib/webvas/shader.rb
 - lib/webvas/version.rb
+- patches/psych-wasi.patch
 - sig/rbgl.rbs
 - sig/webvas.rbs
 homepage: https://github.com/rbgfx/webvas
@@ -156,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Run Ruby graphics in the browser
 test_files: []