wgsl-play 0.0.34 → 0.0.36

package/dist/{WgslPlay-Ben4VdsC.js → WgslPlay-BRvURGA3.js}

@@ -154,19 +154,25 @@ async function initWebGPU(canvas, alphaMode = "opaque") {
 /** Compile WESL fragment shader and create render pipeline. */
 async function createPipeline(state, fragmentSource, options) {
 	state.device.pushErrorScope("validation");
-	const pipeline = await linkAndCreatePipeline({
-		device: state.device,
-		fragmentSource,
-		format: state.presentationFormat,
-		layout: state.pipelineLayout,
-		...options
-	});
-	const gpuError = await state.device.popErrorScope();
-	if (gpuError) {
+	let gpuError;
+	let jsError;
+	try {
+		state.pipeline = await linkAndCreatePipeline({
+			device: state.device,
+			fragmentSource,
+			format: state.presentationFormat,
+			layout: state.pipelineLayout,
+			...options
+		});
+	} catch (e) {
+		jsError = e;
+	} finally {
+		gpuError = await state.device.popErrorScope();
+	}
+	if (jsError || gpuError) {
 		state.pipeline = void 0;
-		throw gpuError;
+		throw jsError ?? gpuError;
 	}
-	state.pipeline = pipeline;
 }
 /** Start the render loop. Returns a stop function. */
 function startRenderLoop(state, playback) {

package/dist/WgslPlay.d.ts

@@ -38,6 +38,8 @@ declare class WgslPlay extends HTMLElement {
   private _sourceEl;
   private _sourceListener;
   private _fetchLibs;
+  private _dirty;
+  private _building;
   private _theme;
   private _mediaQuery;
   private _onFullscreenChange;
@@ -93,12 +95,12 @@ declare class WgslPlay extends HTMLElement {
   private loadInitialContent;
   /** Connect to a source provider element (e.g., wgsl-edit). */
   private connectToSource;
-  /** Fetch shader from URL, auto-fetching any imported dependencies. */
+  /** Fetch shader from URL, then trigger a build. */
   private loadFromUrl;
-  /** Rebuild GPU pipeline using stored state. For full projects with all sources. */
-  private rebuildPipeline;
-  /** Discover dependencies and rebuild. For HTTP/inline sources that may need fetching. */
-  private discoverAndRebuild;
+  /** 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;
   private handleCompileError;
   /** Extract source locations from a WESL parse error or GPU compilation error. */
   private extractLocations;

package/dist/WgslPlay.js

@@ -1,4 +1,4 @@
-import { a as PlaybackControls, c as getConfig, i as startRenderLoop, l as resetConfig, n as createPipeline, o as ErrorOverlay, r as initWebGPU, s as defaults, t as WgslPlay_default } from "./WgslPlay-Ben4VdsC.js";
+import { a as PlaybackControls, c as getConfig, i as startRenderLoop, l as resetConfig, n as createPipeline, o as ErrorOverlay, r as initWebGPU, s as defaults, t as WgslPlay_default } from "./WgslPlay-BRvURGA3.js";
 import { fetchDependencies, loadShaderFromUrl } from "wesl-fetch";
 import { WeslParseError, fileToModulePath } from "wesl";
 
@@ -37,6 +37,8 @@ var WgslPlay = class extends HTMLElement {
 	_sourceEl = null;
 	_sourceListener = null;
 	_fetchLibs = true;
+	_dirty = false;
+	_building = false;
 	_theme = "auto";
 	_mediaQuery = null;
 	_onFullscreenChange = () => this.controls.setFullscreen(!!document.fullscreenElement);
@@ -117,7 +119,7 @@ var WgslPlay = class extends HTMLElement {
 		this._weslSrc = { [this._rootModuleName]: value };
 		this._libs = void 0;
 		this._fromFullProject = false;
-		this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Conditions for conditional compilation (@if/@elif/@else). */
 	get conditions() {
@@ -129,8 +131,7 @@ var WgslPlay = class extends HTMLElement {
 			conditions: value
 		};
 		if (Object.keys(this._weslSrc).length === 0) return;
-		if (this._fromFullProject) this.rebuildPipeline();
-		else this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Set project configuration (mirrors wesl link() API). */
 	set project(value) {
@@ -146,8 +147,7 @@ var WgslPlay = class extends HTMLElement {
 			return;
 		}
 		if (Object.keys(this._weslSrc).length === 0) return;
-		if (this._fromFullProject) this.rebuildPipeline();
-		else this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Set sources from a full project with weslSrc. */
 	setProjectSources(weslSrc, rootModuleName) {
@@ -156,7 +156,7 @@ var WgslPlay = class extends HTMLElement {
 		this._weslSrc = toModulePaths(weslSrc, pkg);
 		this._rootModuleName = fileToModulePath(root, pkg, false);
 		this._fromFullProject = true;
-		this.rebuildPipeline();
+		this.requestBuild();
 	}
 	/** Whether to auto-fetch missing library packages from npm (default: true). */
 	get fetchLibs() {
@@ -248,7 +248,7 @@ var WgslPlay = class extends HTMLElement {
 		try {
 			const alphaMode = this.hasAttribute("transparent") ? "premultiplied" : "opaque";
 			this.renderState = await initWebGPU(this.canvas, alphaMode);
-			await this.loadInitialContent();
+			this.loadInitialContent();
 			this.stopRenderLoop = startRenderLoop(this.renderState, this.playback);
 			this.dispatchEvent(new CustomEvent("ready"));
 			return true;
@@ -261,19 +261,25 @@ var WgslPlay = class extends HTMLElement {
 		}
 	}
 	/** Load from source element, src URL, script child, or inline textContent. */
-	async loadInitialContent() {
+	loadInitialContent() {
 		const sourceId = this.getAttribute("source");
-		if (sourceId) return this.connectToSource(sourceId);
+		if (sourceId) {
+			this.connectToSource(sourceId);
+			return;
+		}
 		const src = this.getAttribute("src");
-		if (src) return this.loadFromUrl(src);
+		if (src) {
+			this.loadFromUrl(src);
+			return;
+		}
 		const inlineSource = this.querySelector("script[type=\"text/wgsl\"], script[type=\"text/wesl\"]")?.textContent?.trim() ?? this.textContent?.trim();
 		if (!inlineSource) return;
 		this._weslSrc = { [this._rootModuleName]: inlineSource };
 		this._fromFullProject = false;
-		await this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Connect to a source provider element (e.g., wgsl-edit). */
-	async connectToSource(id) {
+	connectToSource(id) {
 		const el = document.getElementById(id);
 		if (!el) {
 			console.error(`wgsl-play: source element "${id}" not found`);
@@ -296,96 +302,74 @@ var WgslPlay = class extends HTMLElement {
 		};
 		if (libs) this._libs = libs;
 		this._fromFullProject = false;
-		await this.discoverAndRebuild();
-		this._fromFullProject = true;
+		this.requestBuild();
 		this._sourceListener = (e) => {
 			const detail = e.detail;
 			const fallback = { [this._rootModuleName]: detail?.source ?? "" };
 			this.project = {
 				weslSrc: detail?.sources ?? fallback,
 				rootModuleName: detail?.rootModuleName,
-				conditions: detail?.conditions
+				conditions: detail?.conditions,
+				libs: detail?.libs
 			};
 		};
 		el.addEventListener("change", this._sourceListener);
 	}
-	/** Fetch shader from URL, auto-fetching any imported dependencies. */
+	/** Fetch shader from URL, then trigger a build. */
 	async loadFromUrl(url) {
-		if (!this.renderState) return;
 		try {
-			this.errorOverlay.hide();
 			const { weslSrc, libs, rootModuleName } = await loadShaderFromUrl(url, this.getConfigOverrides()?.shaderRoot);
 			this._weslSrc = weslSrc;
 			this._libs = libs;
 			this._fromFullProject = false;
 			if (rootModuleName) this._rootModuleName = rootModuleName;
-			const mainSource = weslSrc[this._rootModuleName];
-			if (!mainSource) {
-				console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(weslSrc));
-				return;
-			}
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc,
-				libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
-		} catch (error) {
-			this.handleCompileError(error);
-		}
-	}
-	/** Rebuild GPU pipeline using stored state. For full projects with all sources. */
-	async rebuildPipeline() {
-		if (!await this.initialize()) return;
-		const mainSource = this._weslSrc[this._rootModuleName];
-		if (!mainSource) {
-			console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
-			return;
-		}
-		try {
-			this.errorOverlay.hide();
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc: this._weslSrc,
-				libs: this._libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
+			this.requestBuild();
 		} catch (error) {
 			this.handleCompileError(error);
 		}
 	}
-	/** Discover dependencies and rebuild. For HTTP/inline sources that may need fetching. */
-	async discoverAndRebuild() {
-		if (!await this.initialize()) return;
-		const mainSource = this._weslSrc[this._rootModuleName];
-		if (!mainSource) {
-			console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
-			return;
-		}
-		try {
-			this.errorOverlay.hide();
-			const { weslSrc, libs } = await fetchDependencies(mainSource, {
-				shaderRoot: this.getConfigOverrides()?.shaderRoot,
-				existingSources: this._weslSrc,
-				skipExternal: !this._fetchLibs
-			});
-			this._weslSrc = {
-				...this._weslSrc,
-				...weslSrc
-			};
-			this._libs = [...this._libs ?? [], ...libs];
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc: this._weslSrc,
-				libs: this._libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
-		} catch (error) {
-			this.handleCompileError(error);
+	/** Mark build as needed. Coalesces rapid requests into a single build. */
+	requestBuild() {
+		this._dirty = true;
+		if (!this._building) this.runBuild();
+	}
+	/** Run builds until no longer dirty. Only one instance runs at a time. */
+	async runBuild() {
+		this._building = true;
+		while (this._dirty) {
+			this._dirty = false;
+			if (!await this.initialize()) break;
+			const mainSource = this._weslSrc[this._rootModuleName];
+			if (!mainSource) {
+				console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
+				continue;
+			}
+			try {
+				this.errorOverlay.hide();
+				if (!this._fromFullProject) {
+					const { weslSrc, libs } = await fetchDependencies(mainSource, {
+						shaderRoot: this.getConfigOverrides()?.shaderRoot,
+						existingSources: this._weslSrc,
+						skipExternal: !this._fetchLibs
+					});
+					this._weslSrc = {
+						...this._weslSrc,
+						...weslSrc
+					};
+					this._libs = dedupLibs(this._libs, libs);
+				}
+				await createPipeline(this.renderState, mainSource, {
+					...this._linkOptions,
+					weslSrc: this._weslSrc,
+					libs: this._libs,
+					rootModuleName: this._rootModuleName
+				});
+				if (!this._dirty) this.dispatchEvent(new CustomEvent("compile-success"));
+			} catch (error) {
+				if (!this._dirty) this.handleCompileError(error);
+			}
 		}
+		this._building = false;
 	}
 	handleCompileError(error) {
 		const message = error?.message ?? String(error);
@@ -442,6 +426,12 @@ function upgradeProperty(el, prop) {
 		el[prop] = value;
 	}
 }
+/** Merge new libs, deduplicating by bundle name. */
+function dedupLibs(existing, newLibs) {
+	if (!existing || newLibs.length === 0) return [...existing ?? [], ...newLibs];
+	const names = new Set(newLibs.map((b) => b.name));
+	return [...existing.filter((b) => !names.has(b.name)), ...newLibs];
+}
 /** Normalize all keys in a weslSrc record to module paths. */
 function toModulePaths(weslSrc, pkg) {
 	const result = {};

package/dist/index.js

@@ -1,4 +1,4 @@
-import { c as getConfig, l as resetConfig, s as defaults } from "./WgslPlay-Ben4VdsC.js";
+import { c as getConfig, l as resetConfig, s as defaults } from "./WgslPlay-BRvURGA3.js";
 import { WgslPlay } from "./WgslPlay.js";
 
 export * from "wesl-fetch"

package/dist/wgsl-play.js

@@ -5641,19 +5641,25 @@ async function initWebGPU(canvas, alphaMode = "opaque") {
 /** Compile WESL fragment shader and create render pipeline. */
 async function createPipeline(state, fragmentSource, options) {
 	state.device.pushErrorScope("validation");
-	const pipeline = await linkAndCreatePipeline({
-		device: state.device,
-		fragmentSource,
-		format: state.presentationFormat,
-		layout: state.pipelineLayout,
-		...options
-	});
-	const gpuError = await state.device.popErrorScope();
-	if (gpuError) {
+	let gpuError;
+	let jsError;
+	try {
+		state.pipeline = await linkAndCreatePipeline({
+			device: state.device,
+			fragmentSource,
+			format: state.presentationFormat,
+			layout: state.pipelineLayout,
+			...options
+		});
+	} catch (e) {
+		jsError = e;
+	} finally {
+		gpuError = await state.device.popErrorScope();
+	}
+	if (jsError || gpuError) {
 		state.pipeline = void 0;
-		throw gpuError;
+		throw jsError ?? gpuError;
 	}
-	state.pipeline = pipeline;
 }
 /** Start the render loop. Returns a stop function. */
 function startRenderLoop(state, playback) {
@@ -5722,6 +5728,8 @@ var WgslPlay = class extends HTMLElement {
 	_sourceEl = null;
 	_sourceListener = null;
 	_fetchLibs = true;
+	_dirty = false;
+	_building = false;
 	_theme = "auto";
 	_mediaQuery = null;
 	_onFullscreenChange = () => this.controls.setFullscreen(!!document.fullscreenElement);
@@ -5802,7 +5810,7 @@ var WgslPlay = class extends HTMLElement {
 		this._weslSrc = { [this._rootModuleName]: value };
 		this._libs = void 0;
 		this._fromFullProject = false;
-		this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Conditions for conditional compilation (@if/@elif/@else). */
 	get conditions() {
@@ -5814,8 +5822,7 @@ var WgslPlay = class extends HTMLElement {
 			conditions: value
 		};
 		if (Object.keys(this._weslSrc).length === 0) return;
-		if (this._fromFullProject) this.rebuildPipeline();
-		else this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Set project configuration (mirrors wesl link() API). */
 	set project(value) {
@@ -5831,8 +5838,7 @@ var WgslPlay = class extends HTMLElement {
 			return;
 		}
 		if (Object.keys(this._weslSrc).length === 0) return;
-		if (this._fromFullProject) this.rebuildPipeline();
-		else this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Set sources from a full project with weslSrc. */
 	setProjectSources(weslSrc, rootModuleName) {
@@ -5841,7 +5847,7 @@ var WgslPlay = class extends HTMLElement {
 		this._weslSrc = toModulePaths(weslSrc, pkg);
 		this._rootModuleName = fileToModulePath(root, pkg, false);
 		this._fromFullProject = true;
-		this.rebuildPipeline();
+		this.requestBuild();
 	}
 	/** Whether to auto-fetch missing library packages from npm (default: true). */
 	get fetchLibs() {
@@ -5933,7 +5939,7 @@ var WgslPlay = class extends HTMLElement {
 		try {
 			const alphaMode = this.hasAttribute("transparent") ? "premultiplied" : "opaque";
 			this.renderState = await initWebGPU(this.canvas, alphaMode);
-			await this.loadInitialContent();
+			this.loadInitialContent();
 			this.stopRenderLoop = startRenderLoop(this.renderState, this.playback);
 			this.dispatchEvent(new CustomEvent("ready"));
 			return true;
@@ -5946,19 +5952,25 @@ var WgslPlay = class extends HTMLElement {
 		}
 	}
 	/** Load from source element, src URL, script child, or inline textContent. */
-	async loadInitialContent() {
+	loadInitialContent() {
 		const sourceId = this.getAttribute("source");
-		if (sourceId) return this.connectToSource(sourceId);
+		if (sourceId) {
+			this.connectToSource(sourceId);
+			return;
+		}
 		const src = this.getAttribute("src");
-		if (src) return this.loadFromUrl(src);
+		if (src) {
+			this.loadFromUrl(src);
+			return;
+		}
 		const inlineSource = this.querySelector("script[type=\"text/wgsl\"], script[type=\"text/wesl\"]")?.textContent?.trim() ?? this.textContent?.trim();
 		if (!inlineSource) return;
 		this._weslSrc = { [this._rootModuleName]: inlineSource };
 		this._fromFullProject = false;
-		await this.discoverAndRebuild();
+		this.requestBuild();
 	}
 	/** Connect to a source provider element (e.g., wgsl-edit). */
-	async connectToSource(id) {
+	connectToSource(id) {
 		const el = document.getElementById(id);
 		if (!el) {
 			console.error(`wgsl-play: source element "${id}" not found`);
@@ -5981,96 +5993,74 @@ var WgslPlay = class extends HTMLElement {
 		};
 		if (libs) this._libs = libs;
 		this._fromFullProject = false;
-		await this.discoverAndRebuild();
-		this._fromFullProject = true;
+		this.requestBuild();
 		this._sourceListener = (e) => {
 			const detail = e.detail;
 			const fallback = { [this._rootModuleName]: detail?.source ?? "" };
 			this.project = {
 				weslSrc: detail?.sources ?? fallback,
 				rootModuleName: detail?.rootModuleName,
-				conditions: detail?.conditions
+				conditions: detail?.conditions,
+				libs: detail?.libs
 			};
 		};
 		el.addEventListener("change", this._sourceListener);
 	}
-	/** Fetch shader from URL, auto-fetching any imported dependencies. */
+	/** Fetch shader from URL, then trigger a build. */
 	async loadFromUrl(url) {
-		if (!this.renderState) return;
 		try {
-			this.errorOverlay.hide();
 			const { weslSrc, libs, rootModuleName } = await loadShaderFromUrl(url, this.getConfigOverrides()?.shaderRoot);
 			this._weslSrc = weslSrc;
 			this._libs = libs;
 			this._fromFullProject = false;
 			if (rootModuleName) this._rootModuleName = rootModuleName;
-			const mainSource = weslSrc[this._rootModuleName];
-			if (!mainSource) {
-				console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(weslSrc));
-				return;
-			}
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc,
-				libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
+			this.requestBuild();
 		} catch (error) {
 			this.handleCompileError(error);
 		}
 	}
-	/** Rebuild GPU pipeline using stored state. For full projects with all sources. */
-	async rebuildPipeline() {
-		if (!await this.initialize()) return;
-		const mainSource = this._weslSrc[this._rootModuleName];
-		if (!mainSource) {
-			console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
-			return;
-		}
-		try {
-			this.errorOverlay.hide();
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc: this._weslSrc,
-				libs: this._libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
-		} catch (error) {
-			this.handleCompileError(error);
-		}
-	}
-	/** Discover dependencies and rebuild. For HTTP/inline sources that may need fetching. */
-	async discoverAndRebuild() {
-		if (!await this.initialize()) return;
-		const mainSource = this._weslSrc[this._rootModuleName];
-		if (!mainSource) {
-			console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
-			return;
-		}
-		try {
-			this.errorOverlay.hide();
-			const { weslSrc, libs } = await fetchDependencies(mainSource, {
-				shaderRoot: this.getConfigOverrides()?.shaderRoot,
-				existingSources: this._weslSrc,
-				skipExternal: !this._fetchLibs
-			});
-			this._weslSrc = {
-				...this._weslSrc,
-				...weslSrc
-			};
-			this._libs = [...this._libs ?? [], ...libs];
-			await createPipeline(this.renderState, mainSource, {
-				...this._linkOptions,
-				weslSrc: this._weslSrc,
-				libs: this._libs,
-				rootModuleName: this._rootModuleName
-			});
-			this.dispatchEvent(new CustomEvent("compile-success"));
-		} catch (error) {
-			this.handleCompileError(error);
+	/** Mark build as needed. Coalesces rapid requests into a single build. */
+	requestBuild() {
+		this._dirty = true;
+		if (!this._building) this.runBuild();
+	}
+	/** Run builds until no longer dirty. Only one instance runs at a time. */
+	async runBuild() {
+		this._building = true;
+		while (this._dirty) {
+			this._dirty = false;
+			if (!await this.initialize()) break;
+			const mainSource = this._weslSrc[this._rootModuleName];
+			if (!mainSource) {
+				console.warn(`wgsl-play: root module "${this._rootModuleName}" not found in sources:`, Object.keys(this._weslSrc));
+				continue;
+			}
+			try {
+				this.errorOverlay.hide();
+				if (!this._fromFullProject) {
+					const { weslSrc, libs } = await fetchDependencies(mainSource, {
+						shaderRoot: this.getConfigOverrides()?.shaderRoot,
+						existingSources: this._weslSrc,
+						skipExternal: !this._fetchLibs
+					});
+					this._weslSrc = {
+						...this._weslSrc,
+						...weslSrc
+					};
+					this._libs = dedupLibs(this._libs, libs);
+				}
+				await createPipeline(this.renderState, mainSource, {
+					...this._linkOptions,
+					weslSrc: this._weslSrc,
+					libs: this._libs,
+					rootModuleName: this._rootModuleName
+				});
+				if (!this._dirty) this.dispatchEvent(new CustomEvent("compile-success"));
+			} catch (error) {
+				if (!this._dirty) this.handleCompileError(error);
+			}
 		}
+		this._building = false;
 	}
 	handleCompileError(error) {
 		const message = error?.message ?? String(error);
@@ -6127,6 +6117,12 @@ function upgradeProperty(el, prop) {
 		el[prop] = value;
 	}
 }
+/** Merge new libs, deduplicating by bundle name. */
+function dedupLibs(existing, newLibs) {
+	if (!existing || newLibs.length === 0) return [...existing ?? [], ...newLibs];
+	const names = new Set(newLibs.map((b) => b.name));
+	return [...existing.filter((b) => !names.has(b.name)), ...newLibs];
+}
 /** Normalize all keys in a weslSrc record to module paths. */
 function toModulePaths(weslSrc, pkg) {
 	const result = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgsl-play",
-  "version": "0.0.34",
+  "version": "0.0.36",
   "type": "module",
   "files": [
     "dist",
@@ -23,8 +23,8 @@
   },
   "dependencies": {
     "wesl": "0.7.23",
-    "wesl-gpu": "0.1.25",
-    "wesl-fetch": "0.0.11"
+    "wesl-fetch": "0.0.11",
+    "wesl-gpu": "0.1.25"
   },
   "devDependencies": {
     "@playwright/test": "^1.53.2",

package/src/Renderer.ts

@@ -84,19 +84,25 @@ export async function createPipeline(
   options?: LinkOptions,
 ): Promise<void> {
   state.device.pushErrorScope("validation");
-  const pipeline = await linkAndCreatePipeline({
-    device: state.device,
-    fragmentSource,
-    format: state.presentationFormat,
-    layout: state.pipelineLayout,
-    ...options,
-  });
-  const gpuError = await state.device.popErrorScope();
-  if (gpuError) {
+  let gpuError: unknown;
+  let jsError: unknown;
+  try {
+    state.pipeline = await linkAndCreatePipeline({
+      device: state.device,
+      fragmentSource,
+      format: state.presentationFormat,
+      layout: state.pipelineLayout,
+      ...options,
+    });
+  } catch (e) {
+    jsError = e;
+  } finally {
+    gpuError = await state.device.popErrorScope();
+  }
+  if (jsError || gpuError) {
     state.pipeline = undefined;
-    throw gpuError;
+    throw jsError ?? gpuError;
   }
-  state.pipeline = pipeline;
 }
 
 /** Start the render loop. Returns a stop function. */

package/src/WgslPlay.ts

@@ -83,6 +83,8 @@ export class WgslPlay extends HTMLElement {
   private _sourceEl: HTMLElement | null = null;
   private _sourceListener: ((e: Event) => void) | null = null;
   private _fetchLibs = true;
+  private _dirty = false;
+  private _building = false;
   private _theme: "light" | "dark" | "auto" = "auto";
   private _mediaQuery: MediaQueryList | null = null;
   private _onFullscreenChange = () =>
@@ -193,7 +195,7 @@ export class WgslPlay extends HTMLElement {
     this._weslSrc = { [this._rootModuleName]: value };
     this._libs = undefined;
     this._fromFullProject = false;
-    this.discoverAndRebuild();
+    this.requestBuild();
   }
 
   /** Conditions for conditional compilation (@if/@elif/@else). */
@@ -204,8 +206,7 @@ export class WgslPlay extends HTMLElement {
   set conditions(value: Conditions) {
     this._linkOptions = { ...this._linkOptions, conditions: value };
     if (Object.keys(this._weslSrc).length === 0) return;
-    if (this._fromFullProject) this.rebuildPipeline();
-    else this.discoverAndRebuild();
+    this.requestBuild();
   }
 
   /** Set project configuration (mirrors wesl link() API). */
@@ -230,10 +231,8 @@ export class WgslPlay extends HTMLElement {
       return;
     }
 
-    // Partial update - may need to refetch if conditions changed
     if (Object.keys(this._weslSrc).length === 0) return;
-    if (this._fromFullProject) this.rebuildPipeline();
-    else this.discoverAndRebuild();
+    this.requestBuild();
   }
 
   /** Set sources from a full project with weslSrc. */
@@ -246,7 +245,7 @@ export class WgslPlay extends HTMLElement {
     this._weslSrc = toModulePaths(weslSrc, pkg);
     this._rootModuleName = fileToModulePath(root, pkg, false);
     this._fromFullProject = true;
-    this.rebuildPipeline();
+    this.requestBuild();
   }
 
   /** Whether to auto-fetch missing library packages from npm (default: true). */
@@ -365,7 +364,7 @@ export class WgslPlay extends HTMLElement {
         ? "premultiplied"
         : "opaque";
       this.renderState = await initWebGPU(this.canvas, alphaMode);
-      await this.loadInitialContent();
+      this.loadInitialContent();
       this.stopRenderLoop = startRenderLoop(this.renderState, this.playback);
       this.dispatchEvent(new CustomEvent("ready"));
       return true;
@@ -383,12 +382,18 @@ export class WgslPlay extends HTMLElement {
   }
 
   /** Load from source element, src URL, script child, or inline textContent. */
-  private async loadInitialContent(): Promise<void> {
+  private loadInitialContent(): void {
     const sourceId = this.getAttribute("source");
-    if (sourceId) return this.connectToSource(sourceId);
+    if (sourceId) {
+      this.connectToSource(sourceId);
+      return;
+    }
 
     const src = this.getAttribute("src");
-    if (src) return this.loadFromUrl(src);
+    if (src) {
+      this.loadFromUrl(src);
+      return;
+    }
 
     // Prefer <script type="text/wgsl"> or <script type="text/wesl"> (no HTML escaping needed)
     const script = this.querySelector(
@@ -400,11 +405,11 @@ export class WgslPlay extends HTMLElement {
 
     this._weslSrc = { [this._rootModuleName]: inlineSource };
     this._fromFullProject = false;
-    await this.discoverAndRebuild();
+    this.requestBuild();
   }
 
   /** Connect to a source provider element (e.g., wgsl-edit). */
-  private async connectToSource(id: string): Promise<void> {
+  private connectToSource(id: string): void {
     const el = document.getElementById(id);
     if (!el) {
       console.error(`wgsl-play: source element "${id}" not found`);
@@ -421,7 +426,6 @@ export class WgslPlay extends HTMLElement {
     };
 
     // Load initial sources, conditions, and libs from source element.
-    // Use discoverAndRebuild (not project setter) so external deps are fetched.
     const { conditions, rootModuleName, libs } = el as any;
     const root = rootModuleName ?? "main";
     this._weslSrc = getSources();
@@ -429,10 +433,9 @@ export class WgslPlay extends HTMLElement {
     if (conditions) this._linkOptions = { ...this._linkOptions, conditions };
     if (libs) this._libs = libs;
     this._fromFullProject = false;
-    await this.discoverAndRebuild();
-    this._fromFullProject = true; // fast rebuilds on subsequent edits
+    this.requestBuild();
 
-    // Listen for changes - rebuild with cached libs
+    // Listen for changes - rebuild with libs from source element
     this._sourceListener = (e: Event) => {
       const detail = (e as CustomEvent).detail;
       const fallback = { [this._rootModuleName]: detail?.source ?? "" };
@@ -440,17 +443,15 @@ export class WgslPlay extends HTMLElement {
         weslSrc: detail?.sources ?? fallback,
         rootModuleName: detail?.rootModuleName,
         conditions: detail?.conditions,
+        libs: detail?.libs,
       };
     };
     el.addEventListener("change", this._sourceListener);
   }
 
-  /** Fetch shader from URL, auto-fetching any imported dependencies. */
+  /** Fetch shader from URL, then trigger a build. */
   private async loadFromUrl(url: string): Promise<void> {
-    if (!this.renderState) return;
-
     try {
-      this.errorOverlay.hide();
       const { weslSrc, libs, rootModuleName } = await loadShaderFromUrl(
         url,
         this.getConfigOverrides()?.shaderRoot,
@@ -459,88 +460,58 @@ export class WgslPlay extends HTMLElement {
       this._libs = libs;
       this._fromFullProject = false;
       if (rootModuleName) this._rootModuleName = rootModuleName;
-
-      const mainSource = weslSrc[this._rootModuleName];
-      if (!mainSource) {
-        console.warn(
-          `wgsl-play: root module "${this._rootModuleName}" not found in sources:`,
-          Object.keys(weslSrc),
-        );
-        return;
-      }
-
-      await createPipeline(this.renderState, mainSource, {
-        ...this._linkOptions,
-        weslSrc,
-        libs,
-        rootModuleName: this._rootModuleName,
-      });
-      this.dispatchEvent(new CustomEvent("compile-success"));
+      this.requestBuild();
     } catch (error) {
       this.handleCompileError(error);
     }
   }
 
-  /** Rebuild GPU pipeline using stored state. For full projects with all sources. */
-  private async rebuildPipeline(): Promise<void> {
-    if (!(await this.initialize())) return;
-
-    const mainSource = this._weslSrc[this._rootModuleName];
-    if (!mainSource) {
-      console.warn(
-        `wgsl-play: root module "${this._rootModuleName}" not found in sources:`,
-        Object.keys(this._weslSrc),
-      );
-      return;
-    }
-
-    try {
-      this.errorOverlay.hide();
-      await createPipeline(this.renderState!, mainSource, {
-        ...this._linkOptions,
-        weslSrc: this._weslSrc,
-        libs: this._libs,
-        rootModuleName: this._rootModuleName,
-      });
-      this.dispatchEvent(new CustomEvent("compile-success"));
-    } catch (error) {
-      this.handleCompileError(error);
-    }
+  /** Mark build as needed. Coalesces rapid requests into a single build. */
+  private requestBuild(): void {
+    this._dirty = true;
+    if (!this._building) this.runBuild();
   }
 
-  /** Discover dependencies and rebuild. For HTTP/inline sources that may need fetching. */
-  private async discoverAndRebuild(): Promise<void> {
-    if (!(await this.initialize())) return;
+  /** Run builds until no longer dirty. Only one instance runs at a time. */
+  private async runBuild(): Promise<void> {
+    this._building = true;
+    while (this._dirty) {
+      this._dirty = false;
+      if (!(await this.initialize())) break;
 
-    const mainSource = this._weslSrc[this._rootModuleName];
-    if (!mainSource) {
-      console.warn(
-        `wgsl-play: root module "${this._rootModuleName}" not found in sources:`,
-        Object.keys(this._weslSrc),
-      );
-      return;
-    }
+      const mainSource = this._weslSrc[this._rootModuleName];
+      if (!mainSource) {
+        console.warn(
+          `wgsl-play: root module "${this._rootModuleName}" not found in sources:`,
+          Object.keys(this._weslSrc),
+        );
+        continue;
+      }
 
-    try {
-      this.errorOverlay.hide();
-      const { weslSrc, libs } = await fetchDependencies(mainSource, {
-        shaderRoot: this.getConfigOverrides()?.shaderRoot,
-        existingSources: this._weslSrc,
-        skipExternal: !this._fetchLibs,
-      });
-      this._weslSrc = { ...this._weslSrc, ...weslSrc };
-      this._libs = [...(this._libs ?? []), ...libs];
-
-      await createPipeline(this.renderState!, mainSource, {
-        ...this._linkOptions,
-        weslSrc: this._weslSrc,
-        libs: this._libs,
-        rootModuleName: this._rootModuleName,
-      });
-      this.dispatchEvent(new CustomEvent("compile-success"));
-    } catch (error) {
-      this.handleCompileError(error);
+      try {
+        this.errorOverlay.hide();
+        if (!this._fromFullProject) {
+          const { weslSrc, libs } = await fetchDependencies(mainSource, {
+            shaderRoot: this.getConfigOverrides()?.shaderRoot,
+            existingSources: this._weslSrc,
+            skipExternal: !this._fetchLibs,
+          });
+          this._weslSrc = { ...this._weslSrc, ...weslSrc };
+          this._libs = dedupLibs(this._libs, libs);
+        }
+        await createPipeline(this.renderState!, mainSource, {
+          ...this._linkOptions,
+          weslSrc: this._weslSrc,
+          libs: this._libs,
+          rootModuleName: this._rootModuleName,
+        });
+        if (!this._dirty)
+          this.dispatchEvent(new CustomEvent("compile-success"));
+      } catch (error) {
+        if (!this._dirty) this.handleCompileError(error);
+      }
     }
+    this._building = false;
   }
 
   private handleCompileError(error: unknown): void {
@@ -616,6 +587,17 @@ function upgradeProperty(el: HTMLElement, prop: string): void {
   }
 }
 
+/** Merge new libs, deduplicating by bundle name. */
+function dedupLibs(
+  existing: WeslBundle[] | undefined,
+  newLibs: WeslBundle[],
+): WeslBundle[] {
+  if (!existing || newLibs.length === 0)
+    return [...(existing ?? []), ...newLibs];
+  const names = new Set(newLibs.map(b => b.name));
+  return [...existing.filter(b => !names.has(b.name)), ...newLibs];
+}
+
 /** Normalize all keys in a weslSrc record to module paths. */
 function toModulePaths(
   weslSrc: Record<string, string>,

package/src/test/WgslPlay.e2e.ts

@@ -221,20 +221,36 @@ test("connectToSource - external deps are fetched", async ({ page }) => {
   await expectCanvasSnapshot(page, "#player11", "connect-source-external.png");
 });
 
+test("connectToSource - dynamic npm package loading", async ({ page }) => {
+  await page.goto("/");
+  await waitForFrame(page, "#player12");
+
+  // Inject code referencing random_wgsl (not in initial content)
+  await page.click("#inject-npm12");
+  await page.waitForLoadState("networkidle");
+  await waitForFrame(page, "#player12");
+
+  const hasError = await page.evaluate(
+    () => (document.querySelector("#player12") as any)?.hasError ?? true,
+  );
+  expect(hasError).toBe(false);
+  await expectCanvasSnapshot(page, "#player12", "connect-dynamic-npm.png");
+});
+
 test("editor.link() with virtualLibs resolves env:: module", async ({
   page,
 }) => {
   await page.goto("/");
   await waitForWgslPlay(page);
 
-  await page.click("#link-btn12");
+  await page.click("#link-btn13");
   await page.waitForFunction(
     () =>
-      document.querySelector("#link-output12")?.textContent !==
+      document.querySelector("#link-output13")?.textContent !==
       "Not linked yet",
   );
 
-  const output = await page.textContent("#link-output12");
+  const output = await page.textContent("#link-output13");
   expect(output).toContain("var<uniform>");
   expect(output).toContain("fs_main");
   expect(output).not.toContain("Error");