wgsl-play 0.0.2

package/playwright.config.ts

@@ -0,0 +1,33 @@
+import process from "node:process";
+import { defineConfig, devices } from "@playwright/test";
+import { testPort } from "./playwright.port.ts";
+
+const port = process.env.PLAYWRIGHT_PORT || testPort;
+
+export default defineConfig({
+  webServer: {
+    command: `pnpm run dev --port ${port}`,
+    url: `http://localhost:${port}`,
+    reuseExistingServer: !process.env.CI,
+    stdout: "pipe",
+  },
+
+  testDir: "./src/test",
+  testMatch: "**/*.e2e.ts",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: "html",
+  use: {
+    baseURL: `http://localhost:${port}`,
+    trace: "on-first-retry",
+  },
+
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+});

package/playwright.port.ts

@@ -0,0 +1,2 @@
+// port for playwright tests
+export const testPort = 9102;

package/src/BundleHydrator.ts

@@ -0,0 +1,187 @@
+import { init, parse } from "es-module-lexer";
+import type { WeslBundle } from "wesl";
+
+// Initialize es-module-lexer WASM once at module load
+const initPromise = init;
+
+/**
+ * Bundle hydration for WESL packages.
+ *
+ * Takes bundle JS source files (strings) and returns WeslBundle objects with
+ * resolved cross-references. Each bundle file is an ES module that exports a
+ * `weslBundle` object containing shader source and metadata, and declares
+ * dependencies via imports:
+ *
+ *   import dependency from "other-package";
+ *   export const weslBundle = { ..., dependencies: [dependency] };
+ *
+ * We use es-module-lexer to parse imports without executing code, reconstruct
+ * the dependency graph, then hydrate bundles in dependency order using
+ * Function() constructor with dependency injection. Returns WeslBundle objects
+ * where dependency references are resolved to actual bundle objects.
+ */
+
+// This relies the generated weslBundle.js using a conventional format. LATER generalize
+
+/** Bundle file from filesystem, tgz, or network source. (i.e. a weslBundle.js file) */
+export interface WeslBundleFile {
+  /** for debug, normally weslBundle.js */
+  packagePath: string;
+
+  /** JavaScript source code */
+  content: string;
+
+  /** name of the wesl package (the npm package name, sanitized to remove @ and -) */
+  packageName: string;
+}
+
+interface BundleInfo {
+  /** JavaScript source containing the weslBundle object literal */
+  bundleLiteral: string;
+
+  imports: Array<{ varName: string; path: string }>;
+}
+
+/** Registry of parsed bundle info, keyed by import path. */
+export type BundleRegistry = Map<string, BundleInfo>;
+
+/** Fetcher callback for loading missing packages on-demand. */
+type PackageFetcher = (pkgName: string) => Promise<WeslBundleFile[]>;
+
+// Matches: package/dist/foo/bar/weslBundle.js (captures "foo/bar")
+const nestedBundlePattern = /package\/dist\/(.+)\/weslBundle\.js$/;
+
+// Matches: package/dist/weslBundle.js
+const rootBundlePattern = /package\/dist\/weslBundle\.js$/;
+
+/** Load WeslBundle objects from BundleFile sources. */
+export async function loadBundlesFromFiles(
+  bundleFiles: WeslBundleFile[],
+): Promise<WeslBundle[]> {
+  const registry = await bundleRegistry(bundleFiles);
+  return hydrateBundleRegistry(registry);
+}
+
+/** Parse bundle files into a registry without hydrating. */
+export async function bundleRegistry(
+  bundleFiles: WeslBundleFile[],
+  registry: BundleRegistry = new Map(),
+): Promise<BundleRegistry> {
+  await initPromise;
+  for (const file of bundleFiles) {
+    const { content, packagePath, packageName } = file;
+    const bundleInfo = parseBundleImports(content);
+    const modulePath = filePathToModulePath(packagePath, packageName);
+    registry.set(modulePath, bundleInfo);
+  }
+  return registry;
+}
+
+/** Hydrate bundles, optionally fetching missing packages on-demand. */
+export async function hydrateBundleRegistry(
+  registry: BundleRegistry,
+  fetcher?: PackageFetcher,
+): Promise<WeslBundle[]> {
+  const hydrated = new Map<string, WeslBundle>();
+  const bundles: WeslBundle[] = [];
+  for (const path of registry.keys()) {
+    bundles.push(await hydrateBundle(path, registry, hydrated, fetcher));
+  }
+  return bundles;
+}
+
+// Matches: export const weslBundle = { ... };
+const weslBundleExportPattern =
+  /export\s+const\s+weslBundle\s*=\s*({[\s\S]+});?\s*$/m;
+
+// Matches: import foo from "package" (captures "foo")
+const importVarPattern = /import\s+(\w+)\s+from/;
+
+/** Parse ES module imports from bundle code using es-module-lexer.  */
+function parseBundleImports(code: string): BundleInfo {
+  const exportMatch = code.match(weslBundleExportPattern);
+  if (!exportMatch) {
+    throw new Error("Could not find weslBundle export in bundle");
+  }
+
+  const [imports] = parse(code);
+  const parsedImports = imports.map(imp => {
+    const statement = code.slice(imp.ss, imp.se);
+    const match = statement.match(importVarPattern);
+    if (!match) {
+      throw new Error(
+        `Could not parse import variable name from: ${statement}`,
+      );
+    }
+    return { varName: match[1], path: imp.n!.replace(/\//g, "::") };
+  });
+
+  return { bundleLiteral: exportMatch[1], imports: parsedImports };
+}
+
+/**
+ * Recursively hydrate a bundle with dependency injection.
+ *
+ * Uses Function() constructor to evaluate the bundle object literal with
+ * dependencies injected as parameters. Supports circular dependencies via
+ * placeholder objects.
+ *
+ * If fetcher is provided and a dependency is missing, fetches the package
+ * on-demand, adds to registry, and continues. Otherwise throws on missing deps.
+ */
+async function hydrateBundle(
+  path: string,
+  registry: BundleRegistry,
+  hydrated: Map<string, WeslBundle>,
+  fetcher?: PackageFetcher,
+): Promise<WeslBundle> {
+  const cached = hydrated.get(path);
+  if (cached) return cached;
+
+  let info = registry.get(path);
+  if (!info) {
+    if (!fetcher) throw new Error(`Bundle not found in registry: ${path}`);
+
+    const pkgName = path.split("::")[0];
+    const files = await fetcher(pkgName);
+    await bundleRegistry(files, registry);
+    info = registry.get(path);
+    if (!info) throw new Error(`Bundle not found after fetch: ${path}`);
+  }
+
+  // Create placeholder before recursing to handle cycles
+  const placeholder = {} as WeslBundle;
+  hydrated.set(path, placeholder);
+
+  // Recursively hydrate dependencies (will auto-fetch if missing)
+  const paramNames = info.imports.map(imp => imp.varName);
+  const paramValues = await Promise.all(
+    info.imports.map(imp =>
+      hydrateBundle(imp.path, registry, hydrated, fetcher),
+    ),
+  );
+
+  // Hydrate and fill placeholder with actual bundle data
+  const fn = new Function(
+    ...paramNames,
+    `'use strict'; return ${info.bundleLiteral}`,
+  );
+  const bundle = fn(...paramValues) as WeslBundle;
+  Object.assign(placeholder, bundle);
+
+  return placeholder;
+}
+
+/** Convert bundle file path to module path (e.g., "package/dist/math/consts/weslBundle.js" => "pkg::math::consts"). */
+function filePathToModulePath(filePath: string, packageName: string): string {
+  const multiMatch = filePath.match(nestedBundlePattern);
+  if (multiMatch) {
+    const subpath = multiMatch[1].replace(/\//g, "::");
+    return `${packageName}::${subpath}`;
+  }
+
+  const singleMatch = filePath.match(rootBundlePattern);
+  if (singleMatch) return packageName;
+
+  throw new Error(`Invalid bundle file path: ${filePath}`);
+}

package/src/BundleLoader.ts

@@ -0,0 +1,119 @@
+import { gunzipSync } from "fflate";
+import { type ParsedTarFileItem, parseTar } from "nanotar";
+import type { WeslBundle } from "wesl";
+import { loadBundlesFromFiles, type WeslBundleFile } from "./BundleHydrator.ts";
+
+/** Load bundles from URL or npm package name, return bundles, package name, and resolved tgz URL. */
+export async function loadBundlesWithPackageName(
+  input: string,
+): Promise<{ bundles: WeslBundle[]; packageName: string; tgzUrl: string }> {
+  const tgzUrl = await resolvePackageInput(input);
+  const entries = await fetchAndExtractTgz(tgzUrl);
+
+  const bundleFilesWithoutPackage = entries
+    .filter(f => f.name.endsWith("weslBundle.js"))
+    .map(f => ({ packagePath: f.name, content: f.text }));
+
+  if (bundleFilesWithoutPackage.length === 0) {
+    throw new Error("No bundle files found in package");
+  }
+
+  const packageName = extractPackageName(bundleFilesWithoutPackage[0].content);
+  const bundleFiles: WeslBundleFile[] = bundleFilesWithoutPackage.map(f => ({
+    ...f,
+    packageName,
+  }));
+  const bundles = await loadBundlesFromFiles(bundleFiles);
+
+  return { bundles, packageName, tgzUrl };
+}
+
+/** Load WESL bundles from a tgz URL. */
+export async function loadBundlesFromTgz(
+  tgzUrl: string,
+  packageName: string,
+): Promise<WeslBundle[]> {
+  const entries = await fetchAndExtractTgz(tgzUrl);
+  const bundleFiles: WeslBundleFile[] = entries
+    .filter(f => f.name.endsWith("weslBundle.js"))
+    .map(f => ({ packagePath: f.name, content: f.text, packageName }));
+
+  return loadBundlesFromFiles(bundleFiles);
+}
+
+/** Custom tgz URL for lygia (npm package is outdated). */
+export const lygiaTgzUrl =
+  "https://raw.githubusercontent.com/mighdoll/big-files/refs/heads/main/lygia-1.3.5-rc.2.tgz";
+
+/** Resolve input to a tgz URL (converts npm package names to registry URLs). */
+async function resolvePackageInput(input: string): Promise<string> {
+  if (input.startsWith("http://") || input.startsWith("https://")) {
+    return input;
+  }
+  if (input === "lygia") return lygiaTgzUrl;
+  return npmPackageToUrl(input);
+}
+
+/** Extract package name from bundle file content. */
+function extractPackageName(bundleContent: string): string {
+  const nameMatch = bundleContent.match(/name:\s*"([^"]+)"/);
+  if (!nameMatch) {
+    throw new Error("Could not extract package name from bundle");
+  }
+  return nameMatch[1];
+}
+
+/** Fetch and extract tgz file, returning tar entries. */
+async function fetchAndExtractTgz(
+  tgzUrl: string,
+): Promise<ParsedTarFileItem[]> {
+  const response = await fetch(tgzUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch package: HTTP ${response.status}`);
+  }
+  const gzipData = new Uint8Array(await response.arrayBuffer());
+  const tarData = gunzipSync(gzipData);
+  return parseTar(tarData);
+}
+
+/** Fetch bundle files from a tgz URL (without evaluating). */
+export async function fetchBundleFilesFromUrl(
+  tgzUrl: string,
+): Promise<WeslBundleFile[]> {
+  const entries = await fetchAndExtractTgz(tgzUrl);
+  const bundleFilesWithoutPkg = entries
+    .filter(f => f.name.endsWith("weslBundle.js"))
+    .map(f => ({ packagePath: f.name, content: f.text }));
+
+  if (bundleFilesWithoutPkg.length === 0) return [];
+
+  const pkgName = extractPackageName(bundleFilesWithoutPkg[0].content);
+  return bundleFilesWithoutPkg.map(f => ({ ...f, packageName: pkgName }));
+}
+
+/** Fetch bundle files from an npm package (without evaluating). */
+export async function fetchBundleFilesFromNpm(
+  packageName: string,
+): Promise<WeslBundleFile[]> {
+  const tgzUrl = await npmPackageToUrl(packageName);
+  return fetchBundleFilesFromUrl(tgzUrl);
+}
+
+/** Fetch npm package tarball URL from registry metadata. */
+export async function npmPackageToUrl(packageName: string): Promise<string> {
+  const metadataUrl = `https://registry.npmjs.org/${packageName}`;
+  const response = await fetch(metadataUrl);
+  if (!response.ok) {
+    throw new Error(`Package not found in npm registry: ${packageName}`);
+  }
+  const metadata = await response.json();
+  const latestVersion = metadata["dist-tags"]?.latest;
+  if (!latestVersion) {
+    throw new Error(`No latest version found for package: ${packageName}`);
+  }
+  const tarballUrl = metadata.versions?.[latestVersion]?.dist?.tarball;
+  if (!tarballUrl) {
+    throw new Error(`No tarball URL found for ${packageName}@${latestVersion}`);
+  }
+  return tarballUrl;
+}

package/src/ErrorOverlay.ts

@@ -0,0 +1,32 @@
+/** Manages an error overlay element within a shadow DOM. */
+export class ErrorOverlay {
+  private el: HTMLDivElement;
+  private _message: string | null = null;
+
+  constructor(container: ShadowRoot, onDismiss?: () => void) {
+    this.el = document.createElement("div");
+    this.el.className = "error-overlay";
+    if (onDismiss) this.el.addEventListener("click", onDismiss);
+    container.appendChild(this.el);
+  }
+
+  show(message: string): void {
+    this._message = message;
+    this.el.textContent = message;
+    this.el.classList.add("visible");
+    console.error("[wgsl-play]", message);
+  }
+
+  hide(): void {
+    this._message = null;
+    this.el.classList.remove("visible");
+  }
+
+  get visible(): boolean {
+    return this.el.classList.contains("visible");
+  }
+
+  get message(): string | null {
+    return this._message;
+  }
+}

package/src/PackageLoader.ts

@@ -0,0 +1,83 @@
+import type { WeslBundle } from "wesl";
+import { findUnboundIdents, npmNameVariations, RecordResolver } from "wesl";
+import type { WeslBundleFile } from "./BundleHydrator.ts";
+import { bundleRegistry, hydrateBundleRegistry } from "./BundleHydrator.ts";
+import {
+  fetchBundleFilesFromNpm,
+  fetchBundleFilesFromUrl,
+  lygiaTgzUrl,
+} from "./BundleLoader.ts";
+
+/** Shader source with resolved dependency bundles. */
+export interface ShaderWithDeps {
+  source: string;
+  bundles: WeslBundle[];
+}
+
+/** Fetch bundles for external dependencies detected in shader source. */
+export async function fetchDependenciesForSource(
+  source: string,
+): Promise<WeslBundle[]> {
+  const packageNames = detectPackageDeps(source);
+  return fetchPackages(packageNames);
+}
+
+/** Load shader text from a url and recursively fetch imported bundles */
+export async function loadShaderFromUrl(url: string): Promise<ShaderWithDeps> {
+  const source = await fetchShaderSource(url);
+  const packageNames = detectPackageDeps(source);
+  const bundles = await fetchPackages(packageNames);
+  return { source, bundles };
+}
+
+/** Detect external package dependencies from shader source. */
+function detectPackageDeps(source: string): string[] {
+  const resolver = new RecordResolver({ "./main.wesl": source });
+  const unbound = findUnboundIdents(resolver);
+  const pkgRefs = unbound.filter(p => p[0] !== "constants" && p[0] !== "test"); // LATER make dynamic
+  const weslPackages = pkgRefs.map(p => p[0]);
+  return [...new Set(weslPackages)];
+}
+
+/** Fetch WESL bundles for packages, auto-fetching dependencies recursively. */
+async function fetchPackages(pkgIds: string[]): Promise<WeslBundle[]> {
+  const loaded = new Set<string>();
+
+  const promisedBundles = pkgIds.map(id => fetchOnePackage(id, loaded));
+  const initialFiles = await Promise.all(promisedBundles);
+  const registry = await bundleRegistry(initialFiles.flat());
+
+  return hydrateBundleRegistry(registry, id => fetchOnePackage(id, loaded));
+}
+
+/** Fetch bundle files for a single package. */
+async function fetchOnePackage(
+  pkgId: string,
+  loaded: Set<string>,
+): Promise<WeslBundleFile[]> {
+  if (loaded.has(pkgId)) return []; // already loaded
+  loaded.add(pkgId);
+
+  // Special case for lygia - use custom tgz URL (npm package is outdated)
+  if (pkgId === "lygia") {
+    return fetchBundleFilesFromUrl(lygiaTgzUrl);
+  }
+
+  for (const npmName of npmNameVariations(pkgId)) {
+    try {
+      return await fetchBundleFilesFromNpm(npmName);
+    } catch {
+      // Try next variation
+    }
+  }
+  throw new Error(`Package not found: ${pkgId}`);
+}
+
+/** Fetch shader source from URL. */
+async function fetchShaderSource(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return response.text();
+}

package/src/Renderer.ts

@@ -0,0 +1,144 @@
+import type { LinkParams, WeslBundle } from "wesl";
+import { requestWeslDevice } from "wesl";
+import {
+  linkAndCreatePipeline,
+  renderFrame,
+  updateRenderUniforms,
+} from "wesl-gpu";
+
+/** WebGPU state */
+export interface RenderState {
+  device: GPUDevice;
+  canvas: HTMLCanvasElement;
+  context: GPUCanvasContext;
+  presentationFormat: GPUTextureFormat;
+  uniformBuffer: GPUBuffer;
+  pipelineLayout: GPUPipelineLayout;
+  bindGroup: GPUBindGroup;
+  pipeline?: GPURenderPipeline;
+}
+
+/** Animation state */
+export interface PlaybackState {
+  isPlaying: boolean;
+  startTime: number;
+  pausedDuration: number;
+}
+
+/** Initialize WebGPU for a canvas element. */
+export async function initWebGPU(
+  canvas: HTMLCanvasElement,
+): Promise<RenderState> {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error("WebGPU adapter not available");
+
+  const device = await requestWeslDevice(adapter);
+  const context = canvas.getContext("webgpu");
+  if (!context) throw new Error("WebGPU context not available");
+
+  const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+  context.configure({
+    device,
+    format: presentationFormat,
+    alphaMode: "opaque",
+  });
+
+  const uniformBuffer = device.createBuffer({
+    size: 32, // vec2f + f32 + padding + vec2f
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  });
+
+  // Explicit layout for now. LATER will construct layout based on reflection
+  const bindGroupLayout = device.createBindGroupLayout({
+    entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: {} }],
+  });
+  const pipelineLayout = device.createPipelineLayout({
+    bindGroupLayouts: [bindGroupLayout],
+  });
+  const bindGroup = device.createBindGroup({
+    layout: bindGroupLayout,
+    entries: [{ binding: 0, resource: { buffer: uniformBuffer } }],
+  });
+
+  return {
+    device,
+    canvas,
+    context,
+    presentationFormat,
+    uniformBuffer,
+    pipelineLayout,
+    bindGroup,
+  };
+}
+
+export type LinkOptions = Pick<
+  LinkParams,
+  "packageName" | "conditions" | "constants"
+>;
+
+/** Compile WESL fragment shader and create render pipeline. */
+export async function createPipeline(
+  state: RenderState,
+  fragmentSource: string,
+  bundles: WeslBundle[],
+  options?: LinkOptions,
+): Promise<void> {
+  state.pipeline = await linkAndCreatePipeline({
+    device: state.device,
+    fragmentSource,
+    bundles,
+    format: state.presentationFormat,
+    layout: state.pipelineLayout,
+    conditions: options?.conditions,
+    constants: options?.constants,
+    packageName: options?.packageName,
+  });
+}
+
+/** Start the render loop. Returns a stop function. */
+export function startRenderLoop(
+  state: RenderState,
+  playback: PlaybackState,
+): () => void {
+  let animationId: number;
+
+  function render(): void {
+    if (!state.pipeline) {
+      animationId = requestAnimationFrame(render);
+      return;
+    }
+
+    const time = calculateTime(playback);
+    const resolution: [number, number] = [
+      state.canvas.width,
+      state.canvas.height,
+    ];
+    const mouse: [number, number] = [0.0, 0.0];
+
+    updateRenderUniforms(
+      state.uniformBuffer,
+      state.device,
+      resolution,
+      time,
+      mouse,
+    );
+    renderFrame({
+      device: state.device,
+      pipeline: state.pipeline,
+      bindGroup: state.bindGroup,
+      targetView: state.context.getCurrentTexture().createView(),
+    });
+    animationId = requestAnimationFrame(render);
+  }
+
+  animationId = requestAnimationFrame(render);
+
+  return () => cancelAnimationFrame(animationId);
+}
+
+function calculateTime(playback: PlaybackState): number {
+  const currentTime = playback.isPlaying
+    ? performance.now()
+    : playback.startTime + playback.pausedDuration;
+  return (currentTime - playback.startTime) / 1000;
+}

package/src/WgslPlay.css

@@ -0,0 +1,28 @@
+:host {
+  display: block;
+  position: relative;
+}
+
+canvas {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.error-overlay {
+  position: absolute;
+  inset: 0;
+  background: rgba(200, 0, 0, 0.8);
+  color: white;
+  padding: 1rem;
+  font-family: monospace;
+  font-size: 0.875rem;
+  white-space: pre-wrap;
+  overflow: auto;
+  cursor: pointer;
+  display: none;
+}
+
+.error-overlay.visible {
+  display: block;
+}