wgsl-play 0.0.39 → 0.0.40

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "wgsl-play",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "type": "module",
   "files": [
     "dist",
     "src"
   ],
-  "repository": "github:wgsl-tooling-wg/wesl-js",
+  "repository": "github:webgpu-tools/wesl-js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -19,18 +19,22 @@
     "./bundle": {
       "types": "./dist/WgslPlay.d.ts",
       "import": "./dist/wgsl-play.js"
+    },
+    "./jsx-preact": {
+      "types": "./dist/jsx-preact.d.ts",
+      "import": "./dist/jsx-preact.js"
     }
   },
   "dependencies": {
-    "wesl": "0.7.26",
-    "wesl-fetch": "0.0.14",
-    "wesl-reflect": "0.0.5",
-    "wesl-gpu": "0.1.28"
+    "wesl": "0.7.27",
+    "wesl-gpu": "0.1.29",
+    "wesl-reflect": "0.0.6",
+    "wesl-fetch": "0.0.15"
   },
   "devDependencies": {
     "@playwright/test": "^1.53.2",
-    "fflate": "^0.8.2",
     "nanotar": "^0.2.0",
+    "preact": "^10.27.2",
     "wesl-plugin": "x"
   },
   "scripts": {
@@ -38,7 +42,7 @@
     "dev": "vite test-page --config vite.config.ts",
     "test": "vitest",
     "test:e2e": "playwright test",
-    "typecheck": "tsgo"
+    "typecheck": "tsgo && tsgo -p tsconfig.e2e.json"
   },
   "main": "./dist/index.js"
 }

package/src/CanvasSize.ts

@@ -0,0 +1,27 @@
+/** Device-pixel size of an observed element.
+ *  Prefers `devicePixelContentBoxSize` (Chromium/Firefox) — integer, pixel-exact.
+ *  Falls back to `contentBoxSize × ratio` on Safari and when a `pixel-ratio`
+ *  override is set (the override is CSS-pixel-based by intent). */
+export function entrySize(
+  entry: ResizeObserverEntry,
+  pixelRatioOverride: string | null,
+): [width: number, height: number] {
+  if (pixelRatioOverride === null) {
+    const dp = entry.devicePixelContentBoxSize?.[0];
+    if (dp) return [dp.inlineSize, dp.blockSize];
+  }
+  const ratio =
+    pixelRatioOverride !== null ? Number(pixelRatioOverride) : devicePixelRatio;
+  const css = entry.contentBoxSize?.[0];
+  if (css) return [css.inlineSize * ratio, css.blockSize * ratio];
+  const { width, height } = entry.contentRect;
+  return [width * ratio, height * ratio];
+}
+
+/** Floor and clamp to `[1, max]` so the canvas never exceeds the GPU's 2D limit.
+ *  Pass `max = undefined` to skip the upper clamp (e.g. before the GPU device
+ *  is available; device init will surface limit errors itself). */
+export function clampCanvas(size: number, max: number | undefined): number {
+  const floored = Math.max(1, Math.floor(size));
+  return max !== undefined ? Math.min(floored, max) : floored;
+}

package/src/ComputeBuild.ts

@@ -0,0 +1,151 @@
+import type { WeslAST } from "wesl";
+import {
+  type AutoValues,
+  clearBuffers,
+  linkComputeShader,
+  type PlayResources,
+  runCompute,
+  withErrorScopes,
+  writeUniforms,
+} from "wesl-gpu";
+import {
+  type DiscoveredResource,
+  type VarReflection,
+  varReflection,
+} from "wesl-reflect";
+import type { BuildResult, LinkOptions, RenderState } from "./Renderer.ts";
+import {
+  type BuildBranchParams,
+  destroyPlayResources,
+  disposeResources,
+  mergeResourcePlugins,
+} from "./RenderResources.ts";
+import type { BufferEntry } from "./ResultsPanel.ts";
+
+export interface BuildComputeParams extends BuildBranchParams {
+  ast: WeslAST;
+  entryPoint: string;
+}
+
+interface LinkComputeForParams {
+  device: GPUDevice;
+  shaderSource: string;
+  resources: DiscoveredResource[];
+  options?: LinkOptions;
+}
+
+/** Build the compute pipeline, dispatch once, and return initial readback. */
+export async function buildCompute(
+  p: BuildComputeParams,
+): Promise<BuildResult> {
+  const { state, resources, playResources, ast, shaderSource } = p;
+  const { device } = state;
+  const compute = await linkComputeFor({
+    device,
+    shaderSource,
+    resources,
+    options: p.options,
+  }).catch(err => {
+    destroyPlayResources(playResources);
+    throw err;
+  });
+
+  const readBuffers = mapBuffersByName(resources, playResources);
+  const reflections = mapBufferReflections(ast, resources);
+
+  disposeResources(state);
+  state.pipeline = undefined;
+  state.bindGroup = p.bindGroup;
+  state.resourceTextures = playResources.textures;
+  state.resourceBuffers = playResources.buffers;
+  state.compute = {
+    pipelineLayout: p.pipelineLayout,
+    bindGroup: p.bindGroup,
+    module: compute.module,
+    entryPoint: p.entryPoint,
+    readBuffers,
+    reflections,
+  };
+
+  const computeReadback = await dispatchComputeAndReadback(state);
+  return { layout: p.layout, mode: "compute", computeReadback };
+}
+
+/** Re-dispatch the compute pipeline against the current uniform state and
+ *  return fresh BufferEntry[] for the panel. */
+export async function rerunCompute(state: RenderState): Promise<BufferEntry[]> {
+  return dispatchComputeAndReadback(state);
+}
+
+/** Re-zero each readback buffer, dispatch, and read back. Used for both initial
+ *  build and slider/refresh-driven re-runs in compute mode. */
+async function dispatchComputeAndReadback(
+  state: RenderState,
+): Promise<BufferEntry[]> {
+  const compute = state.compute;
+  if (!compute) return [];
+  // Auto fields (time/frame/delta_time) stay zero in compute mode by design.
+  writeUniforms(state.device, state.uniformState, computeAutoValues(state));
+  clearBuffers(state.device, compute.readBuffers.values());
+  const { readbacks } = await runCompute({
+    device: state.device,
+    module: compute.module,
+    entryPoint: compute.entryPoint,
+    bindGroup: compute.bindGroup,
+    pipelineLayout: compute.pipelineLayout,
+    readBuffers: compute.readBuffers,
+  });
+  return [...readbacks].map(([varName, data]) => ({
+    reflection: compute.reflections.get(varName)!,
+    data,
+  }));
+}
+
+async function linkComputeFor(
+  p: LinkComputeForParams,
+): Promise<{ module: GPUShaderModule }> {
+  const config = mergeResourcePlugins(p.options?.config, p.resources);
+  return withErrorScopes(p.device, () =>
+    linkComputeShader({
+      device: p.device,
+      computeSource: p.shaderSource,
+      ...p.options,
+      config,
+    }),
+  );
+}
+
+/** Map @buffer var name to its allocated GPU buffer (positional alignment). */
+function mapBuffersByName(
+  resources: DiscoveredResource[],
+  playResources: PlayResources,
+): Map<string, GPUBuffer> {
+  const bufferVars = resources.filter(r => r.kind === "buffer");
+  return new Map(
+    bufferVars.map((r, i) => [r.varName, playResources.buffers[i]]),
+  );
+}
+
+/** Map @buffer var name to its VarReflection (type tree, address space, etc.). */
+function mapBufferReflections(
+  ast: WeslAST,
+  resources: DiscoveredResource[],
+): Map<string, VarReflection> {
+  return new Map(
+    resources
+      .filter(r => r.kind === "buffer")
+      .map(r => [r.varName, varReflection(ast, r.varName)]),
+  );
+}
+
+function computeAutoValues(state: RenderState): AutoValues {
+  return {
+    resolution: [state.canvas.width, state.canvas.height],
+    time: 0,
+    delta_time: 0,
+    frame: 0,
+    mouse_pos: [0, 0],
+    mouse_delta: [0, 0],
+    mouse_button: 0,
+  };
+}

package/src/FragmentRender.ts

@@ -0,0 +1,147 @@
+import {
+  type AutoValues,
+  linkAndCreatePipeline,
+  renderFrame,
+  withErrorScopes,
+  writeUniforms,
+} from "wesl-gpu";
+import type { DiscoveredResource } from "wesl-reflect";
+import type { BuildResult, LinkOptions, RenderState } from "./Renderer.ts";
+import {
+  type BuildBranchParams,
+  destroyPlayResources,
+  disposeResources,
+  mergeResourcePlugins,
+} from "./RenderResources.ts";
+
+/** Animation playback state. */
+export interface PlaybackState {
+  isPlaying: boolean;
+  startTime: number;
+  pausedDuration: number;
+}
+
+interface BuildRenderPipelineParams {
+  device: GPUDevice;
+  fragmentSource: string;
+  presentationFormat: GPUTextureFormat;
+  pipelineLayout: GPUPipelineLayout;
+  resources: DiscoveredResource[];
+  options?: LinkOptions;
+}
+
+/** Build the render pipeline and install it on state. */
+export async function buildFragment(
+  p: BuildBranchParams,
+): Promise<BuildResult> {
+  const newPipeline = await buildRenderPipeline({
+    device: p.state.device,
+    fragmentSource: p.shaderSource,
+    presentationFormat: p.state.presentationFormat,
+    pipelineLayout: p.pipelineLayout,
+    resources: p.resources,
+    options: p.options,
+  }).catch(err => {
+    destroyPlayResources(p.playResources);
+    p.state.pipeline = undefined;
+    throw err;
+  });
+
+  disposeResources(p.state);
+  p.state.pipeline = newPipeline;
+  p.state.bindGroup = p.bindGroup;
+  p.state.compute = undefined;
+  p.state.resourceTextures = p.playResources.textures;
+  p.state.resourceBuffers = p.playResources.buffers;
+  return { layout: p.layout, mode: "fragment" };
+}
+
+/** Render a single frame (used when paused). */
+export function renderOnce(state: RenderState, playback: PlaybackState): void {
+  if (!state.pipeline) return;
+  const time = calculateTime(playback);
+  const { mouse, canvas } = state;
+  submitFrame(state, {
+    resolution: [canvas.width, canvas.height],
+    time,
+    delta_time: 0,
+    frame: state.frameCount,
+    mouse_pos: mouse.pos,
+    mouse_delta: [0, 0],
+    mouse_button: mouse.button,
+  });
+}
+
+/** Start the render loop. Returns a stop function. */
+export function startRenderLoop(
+  state: RenderState,
+  playback: PlaybackState,
+): () => void {
+  let animationId: number;
+  let lastTime = 0;
+
+  function render(): void {
+    if (!state.pipeline) {
+      animationId = requestAnimationFrame(render);
+      return;
+    }
+
+    const time = calculateTime(playback);
+    const delta_time = time - lastTime;
+    lastTime = time;
+
+    const { mouse, canvas } = state;
+    const auto: AutoValues = {
+      resolution: [canvas.width, canvas.height],
+      time,
+      delta_time,
+      frame: state.frameCount,
+      mouse_pos: mouse.pos,
+      mouse_delta: mouse.delta,
+      mouse_button: mouse.button,
+    };
+    // Reset per-frame deltas after reading
+    mouse.delta = [0, 0];
+
+    submitFrame(state, auto);
+    animationId = requestAnimationFrame(render);
+  }
+
+  animationId = requestAnimationFrame(render);
+  return () => cancelAnimationFrame(animationId);
+}
+
+/** Seconds elapsed since playback start, frozen while paused. */
+export function calculateTime(playback: PlaybackState): number {
+  const currentTime = playback.isPlaying
+    ? performance.now()
+    : playback.startTime + playback.pausedDuration;
+  return (currentTime - playback.startTime) / 1000;
+}
+
+/** Link the shader and create the render pipeline, surfacing both JS and GPU
+ *  validation errors as a thrown rejection. */
+async function buildRenderPipeline(
+  p: BuildRenderPipelineParams,
+): Promise<GPURenderPipeline> {
+  const config = mergeResourcePlugins(p.options?.config, p.resources);
+  return withErrorScopes(p.device, () =>
+    linkAndCreatePipeline({
+      device: p.device,
+      fragmentSource: p.fragmentSource,
+      format: p.presentationFormat,
+      layout: p.pipelineLayout,
+      ...p.options,
+      config,
+    }),
+  );
+}
+
+/** Write uniforms, render to the current swap-chain texture, and tick frameCount. */
+function submitFrame(state: RenderState, auto: AutoValues): void {
+  const { device, context, bindGroup } = state;
+  writeUniforms(device, state.uniformState, auto);
+  const targetView = context.getCurrentTexture().createView();
+  renderFrame({ device, pipeline: state.pipeline!, bindGroup, targetView });
+  state.frameCount++;
+}

package/src/PlaybackControls.ts

@@ -2,12 +2,21 @@ import backToStartSvg from "./icons/backToStart.svg?raw";
 import expandSvg from "./icons/expand.svg?raw";
 import pauseSvg from "./icons/pause.svg?raw";
 import playSvg from "./icons/play.svg?raw";
+import refreshSvg from "./icons/refresh.svg?raw";
 import shrinkSvg from "./icons/shrink.svg?raw";
 
-/** Playback controls overlay for wgsl-play. */
+export type ControlsMode = "render" | "compute";
+
+/** Playback controls overlay for wgsl-play.
+ *
+ *  In "render" mode (default): play/pause + rewind + fullscreen.
+ *  In "compute" mode: refresh (re-dispatch) + fullscreen — play/pause and
+ *  rewind are hidden because compute mode is not animation-driven. */
 export class PlaybackControls {
   private container: HTMLDivElement;
   private playPauseBtn: HTMLButtonElement;
+  private rewindBtn: HTMLButtonElement;
+  private refreshBtn: HTMLButtonElement;
   private fullscreenBtn: HTMLButtonElement;
   private playing = true;
 
@@ -17,25 +26,25 @@ export class PlaybackControls {
     onPause: () => void,
     onRewind: () => void,
     onFullscreen: () => void,
+    onRefresh: () => void,
   ) {
     this.container = document.createElement("div");
     this.container.className = "controls";
 
-    this.fullscreenBtn = document.createElement("button");
-    this.fullscreenBtn.innerHTML = expandSvg;
-    this.fullscreenBtn.addEventListener("click", onFullscreen);
-
-    const rewindBtn = document.createElement("button");
-    rewindBtn.innerHTML = backToStartSvg;
-    rewindBtn.addEventListener("click", onRewind);
-
-    this.playPauseBtn = document.createElement("button");
-    this.playPauseBtn.innerHTML = pauseSvg;
-    this.playPauseBtn.addEventListener("click", () =>
+    this.fullscreenBtn = makeBtn(expandSvg, onFullscreen);
+    this.rewindBtn = makeBtn(backToStartSvg, onRewind);
+    this.playPauseBtn = makeBtn(pauseSvg, () =>
       this.playing ? onPause() : onPlay(),
     );
+    this.refreshBtn = makeBtn(refreshSvg, onRefresh);
+    this.refreshBtn.hidden = true;
 
-    this.container.append(this.fullscreenBtn, rewindBtn, this.playPauseBtn);
+    this.container.append(
+      this.fullscreenBtn,
+      this.rewindBtn,
+      this.playPauseBtn,
+      this.refreshBtn,
+    );
     shadow.appendChild(this.container);
   }
 
@@ -48,6 +57,13 @@ export class PlaybackControls {
     this.fullscreenBtn.innerHTML = isFullscreen ? shrinkSvg : expandSvg;
   }
 
+  setMode(mode: ControlsMode): void {
+    const isCompute = mode === "compute";
+    this.rewindBtn.hidden = isCompute;
+    this.playPauseBtn.hidden = isCompute;
+    this.refreshBtn.hidden = !isCompute;
+  }
+
   show(): void {
     this.container.style.display = "";
   }
@@ -56,3 +72,10 @@ export class PlaybackControls {
     this.container.style.display = "none";
   }
 }
+
+function makeBtn(html: string, handler: () => void): HTMLButtonElement {
+  const btn = document.createElement("button");
+  btn.innerHTML = html;
+  btn.addEventListener("click", handler);
+  return btn;
+}

package/src/RenderResources.ts

@@ -0,0 +1,132 @@
+import {
+  createPlayResources,
+  createUniformBuffer,
+  type PlayResources,
+  type ResolveUserTexture,
+  scanUniforms,
+  type UniformBufferState,
+} from "wesl-gpu";
+import {
+  type AnnotatedLayout,
+  annotatedResourcesPlugin,
+  type DiscoveredResource,
+} from "wesl-reflect";
+import type { LinkOptions, RenderState } from "./Renderer.ts";
+
+export interface PrepareResourcesParams {
+  state: RenderState;
+  shaderSource: string;
+  pkg: string;
+  root: string;
+  resources: DiscoveredResource[];
+  resolveTexture: ResolveUserTexture;
+}
+
+export interface ResourceSetup {
+  playResources: PlayResources;
+  pipelineLayout: GPUPipelineLayout;
+  bindGroup: GPUBindGroup;
+  layout: AnnotatedLayout | null;
+}
+
+/** Common params shared by both fragment and compute build paths. */
+export interface BuildBranchParams {
+  state: RenderState;
+  resources: DiscoveredResource[];
+  shaderSource: string;
+  pipelineLayout: GPUPipelineLayout;
+  bindGroup: GPUBindGroup;
+  playResources: PlayResources;
+  layout: AnnotatedLayout | null;
+  options?: LinkOptions;
+}
+
+/** Default allocation size (bytes) for runtime-sized `@buffer` arrays. The
+ *  WGSL gives no element count, so the playground picks one. 1024 bytes covers
+ *  256 f32s or 64 vec4f, enough for casual playground use. */
+const defaultRuntimeArrayBytes = 1024;
+
+/** Allocate user-declared resources, rebuild the uniform buffer to match the
+ *  shader's uniform layout, and assemble the pipeline layout + bind group. */
+export async function prepareResources(
+  p: PrepareResourcesParams,
+): Promise<ResourceSetup> {
+  const { state, resources, resolveTexture } = p;
+  const { device } = state;
+  const scan = scanUniforms(p.shaderSource, `${p.pkg}::${p.root}`);
+  const playResources = await createPlayResources({
+    device,
+    resources,
+    startBinding: 1,
+    resolveTexture,
+    minBufferBytes: defaultRuntimeArrayBytes,
+  });
+  state.uniformState.buffer.destroy();
+  state.uniformState = createUniformBuffer(device, scan.layout);
+  const bindGroupLayout = buildBindGroupLayout(device, playResources);
+  const pipelineLayout = device.createPipelineLayout({
+    bindGroupLayouts: [bindGroupLayout],
+  });
+  const bindGroup = buildBindGroup(
+    device,
+    bindGroupLayout,
+    state.uniformState,
+    playResources,
+  );
+  return { playResources, pipelineLayout, bindGroup, layout: scan.layout };
+}
+
+/** Destroy all textures and buffers owned by a PlayResources bundle. */
+export function destroyPlayResources(r: PlayResources): void {
+  for (const t of r.textures) t.destroy();
+  for (const b of r.buffers) b.destroy();
+}
+
+/** Dispose GPU resources owned by the current compile (textures + storage buffers). */
+export function disposeResources(state: RenderState): void {
+  for (const t of state.resourceTextures) t.destroy();
+  for (const b of state.resourceBuffers) b.destroy();
+  state.resourceTextures = [];
+  state.resourceBuffers = [];
+}
+
+/** Add the @buffer/@texture/@sampler plugin to the user-supplied config. */
+export function mergeResourcePlugins(
+  userConfig: LinkOptions["config"],
+  resources: DiscoveredResource[],
+): LinkOptions["config"] {
+  if (resources.length === 0) return userConfig;
+  const plugins = [
+    ...(userConfig?.plugins ?? []),
+    annotatedResourcesPlugin(resources, 1),
+  ];
+  return { ...userConfig, plugins };
+}
+
+function buildBindGroupLayout(
+  device: GPUDevice,
+  resources: PlayResources,
+): GPUBindGroupLayout {
+  const visibility = GPUShaderStage.COMPUTE | GPUShaderStage.FRAGMENT;
+  return device.createBindGroupLayout({
+    entries: [
+      { binding: 0, visibility, buffer: {} },
+      ...resources.layoutEntries,
+    ],
+  });
+}
+
+function buildBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  uniformState: UniformBufferState,
+  resources: PlayResources,
+): GPUBindGroup {
+  return device.createBindGroup({
+    layout,
+    entries: [
+      { binding: 0, resource: { buffer: uniformState.buffer } },
+      ...resources.entries,
+    ],
+  });
+}