wgsl-play 0.0.39 → 0.1.0

package/README.md

@@ -118,6 +118,62 @@ 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
 
 You can include shader code inline if you'd prefer. Use a `<script type="text/wgsl">` (or `<script type="text/wesl">`) tag.
@@ -186,11 +242,12 @@ 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)
@@ -255,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-CSjRo-5Z.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,34 @@ 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;
@@ -56,11 +76,15 @@ declare class WgslPlay extends HTMLElement {
   private _mediaQuery;
   private _onFullscreenChange;
   private _pointerCleanup?;
-  private _resizeCleanup?;
+  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). */
@@ -99,12 +123,25 @@ 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[]>;
@@ -116,9 +153,11 @@ declare class WgslPlay extends HTMLElement {
   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;
@@ -132,11 +171,21 @@ declare class WgslPlay extends HTMLElement {
   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 };