wgsl-play 0.0.37 → 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
 
@@ -56,7 +139,7 @@ You can include shader code inline if you'd prefer. Use a `<script type="text/wg
 
 ```typescript
 const player = document.querySelector("wgsl-play");
-player.source = shaderCode;
+player.shader = shaderCode;
 player.pause();
 player.rewind();
 player.play();
@@ -68,7 +151,7 @@ player.play();
 import shader from './examples/noise.wesl?raw';
 
 const player = document.querySelector("wgsl-play");
-player.source = shader;
+player.shader = shader;
 ```
 
 The `?raw` suffix imports the file as a string. This keeps shaders alongside your source files with HMR support.
@@ -80,12 +163,20 @@ The `?raw` suffix imports the file as a string. This keeps shaders alongside you
 - `shader-root` - Root path for internal imports (default: `/shaders`)
 - `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
 
 ### Properties
-- `source: string` - Get/set shader source
+- `shader: string` - Get/set shader source (single-file convenience)
 - `conditions: Record<string, boolean>` - Get/set conditions for conditional compilation (`@if`/`@elif`/`@else`)
-- `project: WeslProject` - Set full project config (weslSrc, libs, conditions, constants)
+- `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)
@@ -95,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
 
@@ -147,7 +255,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/tools/packages/wesl-plugin) to
+For more control, use the [wesl-plugin](https://github.com/wgsl-tooling-wg/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-B86UkrM7.d.ts → WgslPlay-CSjRo-5Z.d.ts}

@@ -1,4 +1,4 @@
-import { Conditions, LinkParams } from "wesl";
+import { Conditions, WeslProject } from "wesl";
 
 //#region src/Config.d.ts
 /** Configuration for wgsl-play. */
@@ -14,8 +14,6 @@ declare function getConfig(overrides?: Partial<WgslPlayConfig>): WgslPlayConfig;
 declare function resetConfig(): void;
 //#endregion
 //#region src/WgslPlay.d.ts
-/** Project configuration for multi-file shaders (subset of wesl link() API). */
-type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName">;
 /** One source location within a compile error. */
 interface CompileErrorLocation {
   file?: string;
@@ -37,15 +35,17 @@ 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;
   private _libs?;
   private _linkOptions;
-  private _fromFullProject;
+  private _fetchSources;
   private _initPromise?;
   private _sourceEl;
   private _sourceListener;
@@ -55,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();
@@ -62,22 +64,26 @@ declare class WgslPlay extends HTMLElement {
   disconnectedCallback(): void;
   attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
   /** Current shader source code (main module). */
-  get source(): string;
-  /** Set shader source directly. */
-  set source(value: string);
+  get shader(): string;
+  /** Set shader source directly (single-file convenience). */
+  set shader(value: string);
   /** Conditions for conditional compilation (@if/@elif/@else). */
   get conditions(): Conditions;
   set conditions(value: Conditions);
   /** Set project configuration (mirrors wesl link() API). */
   set project(value: WeslProject);
-  /** Set sources from a full project with weslSrc. */
-  private setProjectSources;
   /** Whether to auto-fetch missing library packages from npm (default: true). */
   get fetchLibs(): boolean;
   set fetchLibs(value: boolean);
+  /** Whether to fetch local .wesl source files via HTTP (default: true). */
+  get fetchSources(): boolean;
+  set fetchSources(value: boolean);
   /** 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. */
@@ -97,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;
@@ -106,16 +123,20 @@ declare class WgslPlay extends HTMLElement {
   /** Load from source element, src URL, script child, or inline textContent. */
   private loadInitialContent;
   /** Connect to a source provider element (e.g., wgsl-edit). */
-  private connectToSource;
+  private connectFrom;
   /** Fetch shader from URL, then trigger a build. */
   private loadFromUrl;
   /** Mark build as needed. Coalesces rapid requests into a single build. */
   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;
 }
 //#endregion
-export { WgslPlayConfig as a, resetConfig as c, WgslPlay as i, CompileErrorLocation as n, defaults as o, WeslProject as r, getConfig as s, CompileErrorDetail as t };
+export { defaults as a, WgslPlayConfig as i, CompileErrorLocation as n, getConfig as o, WgslPlay as r, resetConfig as s, CompileErrorDetail as t };