wgsl-play 0.0.38 → 0.0.40

package/README.md

@@ -29,11 +29,150 @@ import env::u;
 }
 ```
 
-| Uniform | Type | Description |
-|---------|------|-------------|
-| `resolution` | `vec2f` | Canvas dimensions in pixels |
+When no `@uniforms` struct is declared, a default is provided with `resolution` and `time`.
+
+### Custom Uniforms
+
+Declare a struct with `@uniforms` to add your own fields with UI controls:
+
+```wgsl
+import env::u;
+
+@uniforms struct Params {
+  @auto resolution: vec2f,
+  @auto time: f32,
+  @range(1.0, 20.0, 5.0, 6.0) frequency: f32,
+  @color(0.2, 0.5, 1.0) tint: vec3f,
+  @toggle(0) invert: u32,
+}
+
+@fragment fn main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let wave = sin(pos.x * u.frequency + u.time);
+  var color = wave * u.tint;
+  if u.invert == 1u { color = 1.0 - color; }
+  return vec4f(color, 1.0);
+}
+```
+
+### `@auto` -- Runtime Fields
+
+The player fills these automatically each frame. The field name determines
+which value is bound (or use `@auto(name)` when the field name differs):
+
+| Name | Type | Description |
+|------|------|-------------|
+| `resolution` | `vec2f` | Canvas size in pixels |
 | `time` | `f32` | Elapsed time in seconds |
-| `mouse` | `vec2f` | Mouse position (normalized 0-1) |
+| `delta_time` | `f32` | Delta time since last frame |
+| `frame` | `u32` | Frame count |
+| `mouse_pos` | `vec2f` | Pointer position in pixels |
+| `mouse_delta` | `vec2f` | Pointer movement since last frame |
+| `mouse_button` | `i32` | Active button: 0=none, 1=left, 2=middle, 3=right |
+
+### UI Annotations
+
+These generate interactive controls in the player.
+
+#### `@range(min, max [, step [, initial]])`
+
+Slider for `f32` or `i32`. Step defaults to `0.01` for `f32`, `1` for `i32`.
+Initial defaults to `min`.
+
+```wgsl
+@range(1.0, 20.0)              frequency: f32,
+@range(1.0, 20.0, 5.0)         frequency: f32,  // step=5
+@range(1.0, 20.0, 0.5, 5.0)    frequency: f32,  // step=0.5, initial=5
+```
+
+#### `@color(r, g, b)`
+
+Color picker for `vec3f`:
+
+```wgsl
+@color(0.2, 0.5, 1.0) tint: vec3f,
+```
+
+#### `@toggle([initial])`
+
+Boolean toggle for `u32` (0 or 1). WGSL forbids `bool` in uniform buffers.
+
+```wgsl
+@toggle     invert: u32,    // default=0
+@toggle(1)  invert: u32,    // default=1
+```
+
+### Plain Fields
+
+Fields without annotations are zero-initialized and settable from JavaScript
+via `setUniform()`. This works before or after compilation.
+
+```wgsl
+@uniforms struct Params {
+  @auto resolution: vec2f,
+  brightness: f32,           // no annotation — set from JS
+}
+```
+
+```javascript
+const player = document.querySelector("wgsl-play");
+player.setUniform("brightness", 0.8);
+```
+
+### Resource Annotations
+
+Bind GPU resources by annotating shader globals. The component owns
+`@group(0)` — `@binding(0)` is the uniform buffer, and annotated resources
+take `@binding(1)` and onward in declaration order.
+
+#### `@texture(name)` — host-provided image
+
+Resolves to a child `<img>` or `<canvas>` of the `<wgsl-play>` element.
+Lookup matches `[data-texture="name"]` first, then falls back to `#name`.
+The image is decoded and uploaded as `rgba8unorm`.
+
+```html
+<wgsl-play>
+  <script type="text/wesl">
+    import env::u;
+    @texture(nebula) var photo: texture_2d<f32>;
+    @sampler(linear) var samp: sampler;
+
+    @fragment fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      return textureSample(photo, samp, pos.xy / u.resolution);
+    }
+  </script>
+  <img data-texture="nebula" src="/images/nebula.jpg" hidden>
+</wgsl-play>
+```
+
+Only `texture_2d<f32>` is supported. `texture_cube`, `texture_2d_array`,
+and storage textures are rejected with a clear error. `<img>` decoding
+uses `imageOrientation: "from-image"`, `premultiplyAlpha: "none"`, and
+`colorSpaceConversion: "none"` for deterministic uploads.
+
+Changing an `<img>` `src`, swapping `data-texture`, or adding/removing
+texture children rebuilds the pipeline automatically.
+
+#### `@sampler(filter)`
+
+Creates a sampler with `clamp-to-edge` addressing. Filter is `linear` or
+`nearest`.
+
+```wgsl
+@sampler(nearest) var samp: sampler;
+```
+
+#### `@buffer`
+
+Zero-initialized storage buffer; size inferred from the WGSL type.
+`read` and `read_write` are both allowed.
+
+```wgsl
+@buffer var<storage, read> palette: array<vec4f, 8>;
+```
+
+`@test_texture` (the wgsl-test fixture annotation) is rejected at
+runtime — use `@texture(name)` with a host element instead.
 
 ### Inline source
 
@@ -81,6 +220,11 @@ The `?raw` suffix imports the file as a string. This keeps shaders alongside you
 - `autoplay` - Start animating on load (default: `true`). Set `autoplay="false"` to start paused
 - `transparent` - Use premultiplied alpha for transparent backgrounds (default: opaque)
 - `from` - Element ID of a source provider (e.g., wgsl-edit) to connect to
+- `no-controls` - Hide playback controls (play/pause, rewind, fullscreen)
+- `no-settings` - Hide the uniform controls panel
+- `width` / `height` - Fixed canvas resolution in pixels, independent of display size. When set, the canvas is not resized by the CSS layout
+- `pixel-ratio` - Scale factor from CSS pixels to canvas pixels (default: `devicePixelRatio`). Set `pixel-ratio="1"` for 1:1 CSS pixels (no HiDPI scaling)
+- `resizable` - Show a drag handle to let users resize the element interactively
 - `fetch-libs` - Auto-fetch missing libraries from npm (default: `true`). Set `fetch-libs="false"` to disable
 - `fetch-sources` - Auto-fetch local .wesl source files via HTTP (default: `true`). Set `fetch-sources="false"` to disable
 
@@ -88,6 +232,7 @@ The `?raw` suffix imports the file as a string. This keeps shaders alongside you
 - `shader: string` - Get/set shader source (single-file convenience)
 - `conditions: Record<string, boolean>` - Get/set conditions for conditional compilation (`@if`/`@elif`/`@else`)
 - `project: WeslProject` - Get/set full project config (weslSrc, libs, conditions, constants)
+- `pixelRatio: number` - Get/set canvas-to-CSS pixel ratio (default: `devicePixelRatio`)
 - `isPlaying: boolean` - Playback state (readonly)
 - `time: number` - Animation time in seconds (readonly)
 - `hasError: boolean` - Compilation error state (readonly)
@@ -97,12 +242,30 @@ The `?raw` suffix imports the file as a string. This keeps shaders alongside you
 - `play()` - Start/resume animation
 - `pause()` - Pause animation
 - `rewind()` - Reset to t=0
+- `renderFrame()` - Wait for any in-flight build, render one frame, and resolve once it has been presented (for snapshotting the canvas)
+- `setUniform(name, value)` - Set a uniform value programmatically
 - `showError(message)` - Display error (empty string clears)
 
 ### Events
-- `compile-error` - `{ message: string }`
+- `compile-error` - `{ message, source: "wesl"|"webgpu", kind: "shader"|"resource", resourceSource?, locations }`. `kind: "resource"` covers missing `@texture` host elements, unsupported texture dims, and `@test_texture` rejection; `resourceSource` names the offending var/source
 - `init-error` - `{ message: string }` (WebGPU init failed)
 - `playback-change` - `{ isPlaying: boolean }`
+- `uniforms-layout` - `{ detail: AnnotatedLayout }` (fired after each compile)
+
+## Canvas Sizing
+
+By default the canvas resolution tracks CSS size at `devicePixelRatio`.
+Use `pixel-ratio` or `width`/`height` to decouple:
+
+```html
+<!-- 1:1 CSS pixels (blocky on HiDPI, great for pixel art) -->
+<wgsl-play pixel-ratio="1" style="width:512px; height:512px"></wgsl-play>
+
+<!-- Fixed 64x64 canvas, stretched to whatever CSS size -->
+<wgsl-play width="64" height="64" style="width:512px; height:512px"></wgsl-play>
+```
+
+For crisp upscaling of low-res canvases, add `image-rendering: pixelated`:
 
 ## Styling
 
@@ -149,7 +312,7 @@ import super::common::tint;
 
 ## Using with wesl-plugin
 
-For more control, use the [wesl-plugin](https://github.com/wgsl-tooling-wg/wesl-js/tree/main/packages/wesl-plugin) to
+For more control, use the [wesl-plugin](https://github.com/webgpu-tools/wesl-js/tree/main/packages/wesl-plugin) to
 assemble shaders and libraries at build time and provide
 them wgsl-play in JavaScript or TypeScript.
 - provides full support for Hot Module Reloading during development

package/dist/{WgslPlay-uTIOrTQq.d.ts → WgslPlay-ouKx64GN.d.ts}

@@ -1,4 +1,5 @@
 import { Conditions, WeslProject } from "wesl";
+import { ResourceLoadError as ResourceLoadError$1 } from "wesl-gpu";
 
 //#region src/Config.d.ts
 /** Configuration for wgsl-play. */
@@ -20,6 +21,8 @@ interface CompileErrorLocation {
   line: number;
   column: number;
   length?: number;
+  /** byte offset into the source file */
+  offset: number;
   severity: "error" | "warning" | "info";
   message: string;
 }
@@ -27,17 +30,36 @@ interface CompileErrorLocation {
 interface CompileErrorDetail {
   message: string;
   source: "wesl" | "webgpu";
+  /** What kind of failure: a shader compile/link problem or a host-side resource problem. */
+  kind: "shader" | "resource";
+  /** For resource errors, the `@texture(name)` or buffer var referenced. */
+  resourceSource?: string;
   locations: CompileErrorLocation[];
 }
-/** <wgsl-play> web component for rendering WESL/WGSL fragment shaders.  */
+/** Attributes accepted by `<wgsl-play>` beyond standard HTML.
+ *  Source of truth for framework-specific JSX augmentations (see `./jsx-preact.ts`). */
+interface WgslPlayAttrs {
+  /** ID of a `<wgsl-edit>` (or compatible) element to source shader content from. */
+  from?: string;
+  /** Color theme; `"auto"` follows `prefers-color-scheme`. */
+  theme?: "light" | "dark" | "auto";
+  /** Allow drag-resize of the player via the corner handle. */
+  resizable?: boolean;
+}
+/** <wgsl-play> web component for rendering WESL/WGSL fragment shaders. */
 declare class WgslPlay extends HTMLElement {
   static observedAttributes: string[];
   private canvas;
+  private resultsPanel;
   private errorOverlay;
   private controls;
+  private settings;
   private resizeObserver;
   private stopRenderLoop?;
+  private _currentMode;
+  private _rerunPending;
   private renderState?;
+  private pendingUniforms;
   private playback;
   private _weslSrc;
   private _rootModuleName;
@@ -53,10 +75,16 @@ declare class WgslPlay extends HTMLElement {
   private _theme;
   private _mediaQuery;
   private _onFullscreenChange;
+  private _pointerCleanup?;
+  private _resizeCleanups;
+  private _childObserver?;
   /** Get config overrides from element attributes. */
   private getConfigOverrides;
   constructor();
   connectedCallback(): void;
+  /** Start watching element size. Deferred until after `initWebGPU` so the
+   *  observer has a real `maxTextureDimension2D` to clamp against. */
+  private observeCanvasSize;
   disconnectedCallback(): void;
   attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
   /** Current shader source code (main module). */
@@ -77,6 +105,9 @@ declare class WgslPlay extends HTMLElement {
   /** Whether autoplay is enabled (default: true). Set autoplay="false" to start paused. */
   get autoplay(): boolean;
   set autoplay(value: boolean | string);
+  /** Scale factor from CSS pixels to canvas pixels (default: devicePixelRatio). */
+  get pixelRatio(): number;
+  set pixelRatio(value: number);
   /** Whether the shader is currently playing. */
   get isPlaying(): boolean;
   /** Current animation time in seconds. */
@@ -92,15 +123,41 @@ declare class WgslPlay extends HTMLElement {
   /** Pause playback. */
   pause(): void;
   private setPlaying;
+  /** Mirror a default-true setter onto its attribute: absent = on, "false" = off. */
+  private setBoolAttr;
+  /** Wait for any in-flight build and render one frame to the canvas, resolving
+   *  once it has been presented. Read the canvas via
+   *  `element.shadowRoot.querySelector('canvas')`. */
+  renderFrame(): Promise<void>;
+  /** Resolve once initialization and any pending build have settled. Yields via
+   *  setTimeout so async build steps (network fetch, GPU validation) get a
+   *  chance to advance between polls. */
+  private awaitIdleBuild;
   /** Reset animation to time 0 and pause. */
   rewind(): void;
+  /** Stop the RAF loop, mark paused, and re-present the current frame. */
+  private stopAndPresent;
   /** Display error message in overlay. Pass empty string to clear. */
   showError(message: string): void;
+  /** Set a uniform value by name. Works before or after compilation. */
+  setUniform(name: string, value: number | number[]): void;
+  /** Apply uniforms set before the pipeline existed. */
+  private flushPendingUniforms;
+  /** Current uniform control values (readable). */
+  get uniforms(): Record<string, number | number[]>;
   /** Toggle fullscreen on this element. */
   toggleFullscreen(): void;
+  /** Track pointer events on canvas for mouse_pos @auto fields. */
+  private setupMouseTracking;
+  /** Drag-to-resize via a custom handle (works on touch + mouse). */
+  private setupResizeHandle;
+  /** Recompute canvas resolution from attributes or CSS size. */
+  private updateCanvasSize;
+  /** Toggle the `dark` class to match `theme` attr or system preference. */
   private updateTheme;
   /** Set up WebGPU and load initial shader. Returns true if successful. */
   private initialize;
+  /** Init WebGPU, wire observers/listeners, and dispatch ready/init-error. */
   private doInitialize;
   /** Load from source element, src URL, script child, or inline textContent. */
   private loadInitialContent;
@@ -112,9 +169,23 @@ declare class WgslPlay extends HTMLElement {
   private requestBuild;
   /** Run builds until no longer dirty. Only one instance runs at a time. */
   private runBuild;
+  /** Fetch deps if needed and create the render pipeline. */
+  private buildPipeline;
+  /** Resolve a @texture(name) to a decoded image from light-DOM children.
+   *  Prefers [data-texture="name"], falls back to #id. */
+  private resolveHostTexture;
+  /** Watch light-DOM for <img> add/remove/src changes and trigger a rebuild. */
+  private observeLightDomChildren;
+  /** Apply a successful build: flush uniforms, update controls, render. */
+  private applyBuild;
+  /** Show canvas vs results panel and (re-)render based on build mode. */
+  private applyMode;
+  /** Coalesce rapid uniform/refresh events into a single re-dispatch. */
+  private scheduleComputeRerun;
+  /** Show the error overlay and dispatch a `compile-error` event. */
   private handleCompileError;
   /** Extract source locations from a WESL parse error or GPU compilation error. */
   private extractLocations;
 }
 //#endregion
-export { defaults as a, WgslPlayConfig as i, CompileErrorLocation as n, getConfig as o, WgslPlay as r, resetConfig as s, CompileErrorDetail as t };
+export { WgslPlayAttrs as a, getConfig as c, WgslPlay as i, resetConfig as l, CompileErrorLocation as n, WgslPlayConfig as o, ResourceLoadError$1 as r, defaults as s, CompileErrorDetail as t };