wgsl-play 0.0.2

package/src/WgslPlay.ts

@@ -0,0 +1,308 @@
+import type { LinkParams, WeslBundle } from "wesl";
+import { ErrorOverlay } from "./ErrorOverlay.ts";
+import {
+  fetchDependenciesForSource,
+  loadShaderFromUrl,
+} from "./PackageLoader.ts";
+import {
+  createPipeline,
+  initWebGPU,
+  type LinkOptions,
+  type PlaybackState,
+  type RenderState,
+  startRenderLoop,
+} from "./Renderer.ts";
+import cssText from "./WgslPlay.css?inline";
+
+/** Project configuration for multi-file shaders (subset of wesl link() API). */
+export type WeslProject = Pick<
+  LinkParams,
+  | "weslSrc"
+  | "rootModuleName"
+  | "conditions"
+  | "constants"
+  | "libs"
+  | "packageName"
+>;
+
+/** Compile error detail for events. */
+export interface CompileErrorDetail {
+  message: string;
+}
+
+// Lazy-init for SSR/Node.js compatibility (avoid browser APIs at module load)
+let styles: CSSStyleSheet | null = null;
+let template: HTMLTemplateElement | null = null;
+
+/**
+ * <wgsl-play> - Web component for rendering WESL/WGSL fragment shaders.
+ *
+ * @example
+ * <!-- From URL -->
+ * <wgsl-play src="./shader.wesl"></wgsl-play>
+ *
+ * <!-- Inline source -->
+ * <wgsl-play>
+ *   @fragment fn fs_main() -> @location(0) vec4f {
+ *     return vec4f(1.0, 0.0, 0.0, 1.0);
+ *   }
+ * </wgsl-play>
+ */
+export class WgslPlay extends HTMLElement {
+  static observedAttributes = ["src"];
+
+  private canvas: HTMLCanvasElement;
+  private errorOverlay: ErrorOverlay;
+  private resizeObserver: ResizeObserver;
+  private stopRenderLoop?: () => void;
+
+  private renderState?: RenderState;
+  private playback: PlaybackState = {
+    isPlaying: true,
+    startTime: performance.now(),
+    pausedDuration: 0,
+  };
+
+  private _source = "";
+  private _linkOptions: LinkOptions = {};
+  private _initialized = false;
+
+  constructor() {
+    super();
+    const shadow = this.attachShadow({ mode: "open" });
+    shadow.adoptedStyleSheets = [getStyles()];
+    shadow.appendChild(getTemplate().content.cloneNode(true));
+
+    this.canvas = shadow.querySelector("canvas")!;
+    this.errorOverlay = new ErrorOverlay(shadow, () => this.pause());
+
+    this.resizeObserver = new ResizeObserver(entries => {
+      for (const entry of entries) {
+        const { width, height } = entry.contentRect;
+        if (width > 0 && height > 0) {
+          this.canvas.width = Math.floor(width * devicePixelRatio);
+          this.canvas.height = Math.floor(height * devicePixelRatio);
+        }
+      }
+    });
+  }
+
+  connectedCallback(): void {
+    this.resizeObserver.observe(this);
+    this.initialize();
+  }
+
+  disconnectedCallback(): void {
+    this.resizeObserver.disconnect();
+    this.stopRenderLoop?.();
+  }
+
+  attributeChangedCallback(
+    name: string,
+    oldValue: string | null,
+    newValue: string | null,
+  ): void {
+    if (oldValue === newValue) return;
+
+    // Initial src is handled by initialize(); this handles later changes
+    if (name === "src" && newValue && this._initialized) {
+      this.loadFromUrl(newValue);
+    }
+  }
+
+  /** Current shader source code. */
+  get source(): string {
+    return this._source;
+  }
+
+  /** Set shader source directly. */
+  set source(value: string) {
+    this._source = value;
+    this.compileSource(value);
+  }
+
+  /** Set project configuration (mirrors wesl link() API). */
+  set project(value: WeslProject) {
+    const { weslSrc, rootModuleName, libs } = value;
+    const { packageName, conditions, constants } = value;
+    if (!weslSrc || !rootModuleName) return;
+    const mainSource = weslSrc[rootModuleName];
+    if (!mainSource) return;
+
+    this._source = mainSource;
+    this._linkOptions = { packageName, conditions, constants };
+
+    if (libs?.length) {
+      this.compileWithLibs(mainSource, libs);
+    } else {
+      this.compileSource(mainSource);
+    }
+  }
+
+  /** Whether the shader is currently playing. */
+  get isPlaying(): boolean {
+    return this.playback.isPlaying;
+  }
+
+  /** Current animation time in seconds. */
+  get time(): number {
+    const currentTime = this.playback.isPlaying
+      ? performance.now()
+      : this.playback.startTime + this.playback.pausedDuration;
+    return (currentTime - this.playback.startTime) / 1000;
+  }
+
+  /** Whether there's a compilation error. */
+  get hasError(): boolean {
+    return this.errorOverlay.visible;
+  }
+
+  /** Current error message, or null if no error. */
+  get errorMessage(): string | null {
+    return this.errorOverlay.message;
+  }
+
+  /** Start playback. */
+  play(): void {
+    if (this.playback.isPlaying) return;
+    const pauseTime = this.playback.startTime + this.playback.pausedDuration;
+    this.playback.startTime =
+      performance.now() - (pauseTime - this.playback.startTime);
+    this.setPlaying(true);
+  }
+
+  /** Pause playback. */
+  pause(): void {
+    if (!this.playback.isPlaying) return;
+    this.playback.pausedDuration = performance.now() - this.playback.startTime;
+    this.setPlaying(false);
+  }
+
+  private setPlaying(playing: boolean): void {
+    this.playback.isPlaying = playing;
+    this.dispatchEvent(
+      new CustomEvent("playback-change", { detail: { isPlaying: playing } }),
+    );
+  }
+
+  /** Reset animation to time 0 and pause. */
+  rewind(): void {
+    this.playback.startTime = performance.now();
+    this.playback.pausedDuration = 0;
+    this.setPlaying(false);
+  }
+
+  /** Display error message in overlay. Pass empty string to clear. */
+  showError(message: string): void {
+    if (message) {
+      this.errorOverlay.show(message);
+      this.pause();
+    } else {
+      this.errorOverlay.hide();
+    }
+  }
+
+  /** Set up WebGPU and load initial shader from src attribute or inline content. */
+  private async initialize(): Promise<void> {
+    if (this._initialized) return;
+    this._initialized = true;
+
+    try {
+      this.renderState = await initWebGPU(this.canvas);
+      await this.loadInitialContent();
+      this.stopRenderLoop = startRenderLoop(this.renderState, this.playback);
+    } catch (error) {
+      const message = `WebGPU initialization failed: ${error}`;
+      this.errorOverlay.show(message);
+      this.pause();
+      this.dispatchEvent(
+        new CustomEvent("init-error", { detail: { message } }),
+      );
+    }
+  }
+
+  /** Load from src attribute or inline textContent. */
+  private async loadInitialContent(): Promise<void> {
+    const src = this.getAttribute("src");
+    if (src) {
+      await this.loadFromUrl(src);
+    } else {
+      const inlineSource = this.textContent?.trim();
+      if (inlineSource) await this.compileSource(inlineSource);
+    }
+  }
+
+  /** Fetch shader from URL, auto-fetching any imported dependencies. */
+  private async loadFromUrl(url: string): Promise<void> {
+    if (!this.renderState) return;
+
+    try {
+      this.errorOverlay.hide();
+      const { source, bundles } = await loadShaderFromUrl(url);
+      this._source = source;
+      await createPipeline(this.renderState, source, bundles);
+    } catch (error) {
+      this.handleCompileError(error);
+    }
+  }
+
+  /** Compile source string, auto-fetching any imported dependencies. */
+  private async compileSource(source: string): Promise<void> {
+    if (!this.renderState) return;
+
+    try {
+      this.errorOverlay.hide();
+      const bundles = await fetchDependenciesForSource(source);
+      await createPipeline(
+        this.renderState,
+        source,
+        bundles,
+        this._linkOptions,
+      );
+    } catch (error) {
+      this.handleCompileError(error);
+    }
+  }
+
+  /** Compile with pre-loaded library bundles (no network fetch for libs). */
+  private async compileWithLibs(
+    source: string,
+    libs: WeslBundle[],
+  ): Promise<void> {
+    if (!this.renderState) {
+      await this.initialize();
+    }
+    if (!this.renderState) return;
+
+    try {
+      this.errorOverlay.hide();
+      await createPipeline(this.renderState, source, libs, this._linkOptions);
+    } catch (error) {
+      this.handleCompileError(error);
+    }
+  }
+
+  private handleCompileError(error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error);
+    this.errorOverlay.show(message);
+    this.pause();
+    const detail: CompileErrorDetail = { message };
+    this.dispatchEvent(new CustomEvent("compile-error", { detail }));
+  }
+}
+
+function getTemplate(): HTMLTemplateElement {
+  if (!template) {
+    template = document.createElement("template");
+    template.innerHTML = `<canvas part="canvas"></canvas>`;
+  }
+  return template;
+}
+
+function getStyles(): CSSStyleSheet {
+  if (!styles) {
+    styles = new CSSStyleSheet();
+    styles.replaceSync(cssText);
+  }
+  return styles;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./BundleHydrator.ts";
+export * from "./BundleLoader.ts";
+export * from "./PackageLoader.ts";
+export * from "./WgslPlay.ts";
+
+import { WgslPlay } from "./WgslPlay.ts";
+
+// Auto-register the custom element
+if (typeof customElements !== "undefined" && !customElements.get("wgsl-play")) {
+  customElements.define("wgsl-play", WgslPlay);
+}

package/src/test/BundleHydrator.test.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "fflate";
+import { parseTar } from "nanotar";
+import { expect, test } from "vitest";
+import type { WeslBundleFile } from "../BundleHydrator.ts";
+import { loadBundlesFromFiles } from "../BundleHydrator.ts";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const testPkgDir = join(__dirname, "../../../../test_pkg");
+
+function loadBundlesFromTgz(tgzPath: string, packageName: string) {
+  const gzipData = readFileSync(tgzPath);
+  const tarData = gunzipSync(new Uint8Array(gzipData));
+  const entries = parseTar(tarData);
+  const bundleFiles: WeslBundleFile[] = entries
+    .filter(f => f.name.endsWith("weslBundle.js"))
+    .map(f => ({ packagePath: f.name, content: f.text, packageName }));
+  return loadBundlesFromFiles(bundleFiles);
+}
+
+test("load single bundle from tgz", async () => {
+  const tgzPath = join(testPkgDir, "dependent_package-0.0.1.tgz");
+  const bundles = await loadBundlesFromTgz(tgzPath, "dependent_package");
+
+  expect(bundles.length).toBe(1);
+  const bundle = bundles[0];
+  expect(bundle.name).toBe("dependent_package");
+  expect(bundle.edition).toBe("unstable_2025_1");
+  expect(Object.keys(bundle.modules)).toEqual(["lib.wesl"]);
+  expect(bundle.modules["lib.wesl"]).toContain("fn dep()");
+});
+
+test("load bundles with dependencies from tgz", async () => {
+  // Multi_pkg has a transitive bundle that imports from dependent_package
+  // Load both to verify dependency resolution across packages
+  const multiTgz = join(testPkgDir, "multi_pkg-0.0.1.tgz");
+  const depTgz = join(testPkgDir, "dependent_package-0.0.1.tgz");
+
+  const multiFiles = extractBundleFiles(multiTgz, "multi_pkg");
+  const depFiles = extractBundleFiles(depTgz, "dependent_package");
+
+  // Load all bundles together - each file knows its package name
+  const allFiles = [...depFiles, ...multiFiles];
+  const allBundles = await loadBundlesFromFiles(allFiles);
+
+  // Should get 4 bundles: 1 from dependent_package, 3 from multi_pkg
+  // All bundles can now resolve because each is registered under correct package
+  expect(allBundles.length).toBe(4);
+
+  // Verify the transitive bundle successfully resolved its dependency
+  const transitive = allBundles.find(b => b.modules["transitive.wesl"]);
+  if (!transitive) throw new Error("transitive bundle not found");
+  if (!transitive.dependencies)
+    throw new Error("transitive has no dependencies");
+  expect(transitive.dependencies.length).toBe(1);
+  expect(transitive.dependencies[0].name).toBe("dependent_package");
+});
+
+test("circular dependencies", async () => {
+  // Create two bundles that import each other
+  const bundleA: WeslBundleFile = {
+    packagePath: "package/dist/weslBundle.js",
+    packageName: "circular_test",
+    content: `
+      import bundleB from "circular_test/b";
+      export const weslBundle = {
+        name: "circular_test",
+        edition: "unstable_2025_1",
+        modules: { "a.wesl": "fn a() {}" },
+        dependencies: [bundleB]
+      };
+    `,
+  };
+
+  const bundleB: WeslBundleFile = {
+    packagePath: "package/dist/b/weslBundle.js",
+    packageName: "circular_test",
+    content: `
+      import bundleA from "circular_test";
+      export const weslBundle = {
+        name: "circular_test",
+        edition: "unstable_2025_1",
+        modules: { "b.wesl": "fn b() {}" },
+        dependencies: [bundleA]
+      };
+    `,
+  };
+
+  const bundles = await loadBundlesFromFiles([bundleA, bundleB]);
+
+  // Both bundles should evaluate successfully
+  expect(bundles.length).toBe(2);
+
+  const a = bundles.find(b => b.modules["a.wesl"]);
+  const b = bundles.find(b => b.modules["b.wesl"]);
+
+  if (!a) throw new Error("bundle a not found");
+  if (!b) throw new Error("bundle b not found");
+
+  // Verify circular references
+  expect(a.dependencies?.length).toBe(1);
+  expect(b.dependencies?.length).toBe(1);
+
+  // Each bundle should reference the other
+  expect(a.dependencies?.[0]).toBe(b);
+  expect(b.dependencies?.[0]).toBe(a);
+});
+
+function extractBundleFiles(
+  tgzPath: string,
+  packageName: string,
+): WeslBundleFile[] {
+  const gzipData = readFileSync(tgzPath);
+  const tarData = gunzipSync(new Uint8Array(gzipData));
+  const entries = parseTar(tarData);
+  return entries
+    .filter(f => f.name.endsWith("weslBundle.js"))
+    .map(f => ({ packagePath: f.name, content: f.text, packageName }));
+}

package/src/test/WgslPlay.e2e.ts

@@ -0,0 +1,38 @@
+/** E2E tests for wgsl-play component using Playwright. */
+import { expect, test } from "@playwright/test";
+
+test("canvas renders correctly (visual regression)", async ({ page }) => {
+  await page.goto("/");
+
+  // Wait for WebGPU to initialize and render
+  await page.waitForTimeout(1000);
+
+  // Rewind to t=0 for consistent snapshot
+  await page.getByRole("button", { name: "Rewind" }).click();
+  await page.waitForTimeout(100);
+
+  const player = page.locator("wgsl-play");
+  await expect(player).toHaveScreenshot("gradient-t0.png", {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+
+test("no critical console errors", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("console", msg => {
+    if (msg.type() === "error") {
+      const text = msg.text();
+      if (!text.includes("favicon")) {
+        errors.push(text);
+      }
+    }
+  });
+
+  await page.goto("/");
+  await page.waitForTimeout(2000);
+
+  const criticalErrors = errors.filter(
+    e => !e.includes("favicon") && !e.includes("404"),
+  );
+  expect(criticalErrors).toEqual([]);
+});

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/test-page/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>wgsl-play test</title>
+    <style>
+      body { margin: 20px; background: #1a1a1a; color: #e0e0e0; font-family: sans-serif; }
+      wgsl-play { width: 512px; height: 512px; display: block; }
+      .controls { margin-bottom: 10px; }
+      button { padding: 6px 12px; margin-right: 8px; }
+    </style>
+  </head>
+  <body>
+    <div class="controls">
+      <button id="play">Play</button>
+      <button id="pause">Pause</button>
+      <button id="rewind">Rewind</button>
+    </div>
+    <wgsl-play id="player">
+      @fragment fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+        let uv = pos.xy / 512.0;
+        return vec4f(uv, 0.5, 1.0);
+      }
+    </wgsl-play>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/test-page/main.ts

@@ -0,0 +1,12 @@
+import "../src/index.ts";
+import type { WgslPlay } from "../src/WgslPlay.ts";
+
+const player = document.querySelector<WgslPlay>("#player")!;
+
+document.querySelector("#play")!.addEventListener("click", () => player.play());
+document
+  .querySelector("#pause")!
+  .addEventListener("click", () => player.pause());
+document
+  .querySelector("#rewind")!
+  .addEventListener("click", () => player.rewind());

package/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../../tsconfig.browser.json",
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+/// <reference types="vitest/config" />
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});