wgsl-play 0.0.38 → 0.0.39

package/README.md

@@ -29,11 +29,94 @@ 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);
+```
 
 ### Inline source
 
@@ -81,6 +164,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 +176,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 +186,29 @@ 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
+- `setUniform(name, value)` - Set a uniform value programmatically
 - `showError(message)` - Display error (empty string clears)
 
 ### Events
 - `compile-error` - `{ message: string }`
 - `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
 

package/dist/{WgslPlay-uTIOrTQq.d.ts → WgslPlay-CSjRo-5Z.d.ts}

@@ -35,9 +35,11 @@ declare class WgslPlay extends HTMLElement {
   private canvas;
   private errorOverlay;
   private controls;
+  private settings;
   private resizeObserver;
   private stopRenderLoop?;
   private renderState?;
+  private pendingUniforms;
   private playback;
   private _weslSrc;
   private _rootModuleName;
@@ -53,6 +55,8 @@ declare class WgslPlay extends HTMLElement {
   private _theme;
   private _mediaQuery;
   private _onFullscreenChange;
+  private _pointerCleanup?;
+  private _resizeCleanup?;
   /** Get config overrides from element attributes. */
   private getConfigOverrides;
   constructor();
@@ -77,6 +81,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. */
@@ -96,8 +103,19 @@ declare class WgslPlay extends HTMLElement {
   rewind(): void;
   /** 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;
+  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;
   private updateTheme;
   /** Set up WebGPU and load initial shader. Returns true if successful. */
   private initialize;
@@ -112,6 +130,10 @@ 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;
+  /** Apply a successful build: flush uniforms, update controls, render. */
+  private applyBuild;
   private handleCompileError;
   /** Extract source locations from a WESL parse error or GPU compilation error. */
   private extractLocations;