wesl-plugin 0.6.47 → 0.6.49

package/README.md

@@ -1,109 +1,135 @@
-# **WESL Plugin**
+# WESL Plugin
 
 [![NPM Version](https://img.shields.io/npm/v/wesl-plugin)](https://www.npmjs.com/package/wesl-plugin)
 [![Static Badge](https://img.shields.io/badge/Read%20the%20-Docs-blue)](https://wesl-lang.dev/)
 
-> The wesl-plugin handles `.wesl` and `.wgsl` files
-in JavaScript bundlers to make using webgpu shaders more convenient.
+Bundler plugin for importing `.wesl` and `.wgsl` shader files in JavaScript/TypeScript.
 
-Plugin features are accessed from JavaScript and TypeScript with `import` statements:
+## Install
 
-```ts
-import linkConfig from "./shaders/app.wesl?link";
 ```
-
-```ts
-import linkConfig from "./shaders/app.wesl?static";
+npm install wesl wesl-plugin
 ```
 
-Each plugin ?feature is enabled by its own wesl-plugin [extension](#extensions).
+## Quick Start
 
-## Install
+### Build-time linking (?static)
+
+Link shaders at build time for the smallest application bundle size. 
+
+```ts
+// vite.config.ts
+import { staticBuildExtension } from "wesl-plugin";
+import viteWesl from "wesl-plugin/vite";
 
+export default {
+  plugins: [viteWesl({ extensions: [staticBuildExtension] })]
+};
 ```
-npm install wesl
-npm install wesl-plugin
+
+```ts
+// app.ts
+import wgsl from "./shaders/main.wesl?static";
+
+const module = device.createShaderModule({ code: wgsl });
 ```
 
-### Vite Configuration
+### Runtime linking (?link)
 
-Add the wesl-plugin along with any selected extensions to `vite.config.ts`:
+Link shaders at runtime when you need dynamic conditions or constants:
 
 ```ts
-import { UserConfig } from "vite";
-import weslPlugin from "wesl-plugin/vite";
+// vite.config.ts
 import { linkBuildExtension } from "wesl-plugin";
+import viteWesl from "wesl-plugin/vite";
 
-const config: UserConfig = {
-  plugins: [ weslPlugin({ extensions: [linkBuildExtension] }) ],
+export default {
+  plugins: [viteWesl({ extensions: [linkBuildExtension] })]
 };
+```
+
+```ts
+// app.ts
+import { link } from "wesl";
+import shaderConfig from "./shaders/main.wesl?link";
+
+const linked = await link({
+  ...shaderConfig,
+  conditions: { MOBILE: isMobileGPU },
+  constants: { num_lights: 4 }
+});
 
-export default config;
+const module = linked.createShaderModule(device, {});
 ```
 
-In your JavaScript or TypeScript program you can then import
-wesl or wgsl shaders with a `?link` suffix and link them into WGSL at runtime.
+## Other Bundlers
 
 ```ts
-import linkConfig from "./shaders/app.wesl?link";
-
-function makeShaders() {
-  const vertShader = await link({
-    ...linkConfig, 
-    rootModuleName: "myVerts.wesl",
-    conditions: {mobileGPU: true}
-  });
-  const computeShader = await link({
-    ...linkConfig, 
-    rootModuleName: "myCompute.wesl",
-    constants: {num_lights: 1}
-  });
-}
-
+import viteWesl from "wesl-plugin/vite";
+import esbuildWesl from "wesl-plugin/esbuild";
+import rollupWesl from "wesl-plugin/rollup";
+import webpackWesl from "wesl-plugin/webpack";
+// Also: nuxt, farm, rspack, astro
 ```
 
-### Other Bundlers
+## Extensions
+
+Extensions enable different import suffixes:
+
+| Extension | Suffix | Output | Use Case |
+|-----------|--------|--------|----------|
+| `staticBuildExtension` | `?static` | WGSL string | Build-time linking, simplest |
+| `linkBuildExtension` | `?link` | LinkParams object | Runtime conditions/constants |
 
-The wesl-plugin is available for many popular bundlers:
+### Combining Extensions
 
-``` ts
-import weslPlugin from "wesl-plugin/esbuild"; 
-import weslPlugin from "wesl-plugin/rollup"; 
-import weslPlugin from "wesl-plugin/webpack"; 
-import weslPlugin from "wesl-plugin/nuxt"; 
-import weslPlugin from "wesl-plugin/farm"; 
-import weslPlugin from "wesl-plugin/rpack"; 
-// etc.
+```ts
+import { staticBuildExtension, linkBuildExtension } from "wesl-plugin";
+import viteWesl from "wesl-plugin/vite";
+
+export default {
+  plugins: [viteWesl({
+    extensions: [staticBuildExtension, linkBuildExtension]
+  })]
+};
 ```
 
-## Extensions
+### Conditions in Import Path
 
-- **LinkExtension** - import `?link` in JavaScript/TypeScript programs to conveniently assemble shader files and libraries for linking at runtime.
-Reads the `wesl.toml` file to find local shader files and libraries,
-Returns a `LinkParams` object ready to use for runtime linking.
+For `?static`, you can specify conditions directly in the import:
 
-- **StaticExtension** - import `?static` in JavaScript/TypeScript programs to
-link shader files at build time.
-Reads the `wesl.toml` file to find local shader files and libraries,
-Returns a wgsl string ready to use for `createShaderModule`.
+```ts
+import wgsl from "./app.wesl MOBILE=true DEBUG=false ?static";
+```
+
+## Configuration (wesl.toml)
+
+The plugin reads `wesl.toml` to find shader files and dependencies:
 
-### Prototype Extensions
+```toml
+weslFiles = ["shaders/**/*.wesl"]
+weslRoot = "shaders"
+dependencies = ["auto"]  # Auto-detect from package.json
+```
 
-- **SimpleReReflectExtension** - (_demo for extension writers_) import `?simple_reflect` to
-translate some wgsl `struct` elements into JavaScript and TypeScript.
-Demonstrates to wesl-plugin extension authors how to connect
-to the wesl-plugin, how to produce JavaScript, and how to produce TypeScript.
-- **BindingLayoutExtension** - (_prototype_) import `?bindingLayout` to collect JavaScript
-`BindingGroupLayout` objects.
-Works in concert with the `bindingStructsPlugin` to translate a proposed new WGSL
-feature for defining binding group layouts in shaders [#4957](https://github.com/gpuweb/gpuweb/issues/4957).
+## Prototype Extensions
 
-## Developing a wesl-plugin extension
+- **SimpleReflectExtension** - Demo for extension authors showing how to generate JS/TS from shader structs
+- **BindingLayoutExtension** - Prototype for generating `BindGroupLayout` objects from shaders
 
-To add a new extension to the wesl-plugin:
+## Writing Custom Extensions
 
-- Pick an import suffix (e.g. `?myExtension`).
-- Implement a function that returns a JavaScript string.
-  - Extensions have access to wgsl/wesl sources, a parsed abstract syntax tree for the sources, etc.
+```ts
+import type { PluginExtension } from "wesl-plugin";
+
+const myExtension: PluginExtension = {
+  extensionName: "myfeature",  // enables ?myfeature imports
+  emitFn: async (shaderPath, api, conditions) => {
+    const sources = await api.weslSrc();
+    // Return JavaScript code as a string
+    return `export default ${JSON.stringify(sources)};`;
+  }
+};
+```
 
-See [PluginExtension.ts](https://github.com/wgsl-tooling-wg/wesl-js/blob/master/tools/packages/wesl-plugin/src/PluginExtension.ts) for details.
+See [PluginExtension.ts](https://github.com/wgsl-tooling-wg/wesl-js/blob/main/tools/packages/wesl-plugin/src/PluginExtension.ts) for the full API.

package/dist/{WeslPlugin-BhkB-CW-.js → WeslPlugin-JYxf2uLM.js}

@@ -9880,11 +9880,14 @@ function weslPlugin(options, meta) {
 		meta,
 		options
 	};
+	const log = options.debug ? debugLog : noopLog;
+	log("init", { extensions: options.extensions?.map((e) => e.extensionName) });
 	return {
 		name: "wesl-plugin",
-		resolveId: buildResolver(options, context),
-		load: buildLoader(context),
+		resolveId: buildResolver(options, context, log),
+		load: buildLoader(context, log),
 		watchChange(id, _change) {
+			log("watchChange", { id });
 			if (id.endsWith("wesl.toml")) {
 				cache.weslToml = void 0;
 				cache.registry = void 0;
@@ -9905,15 +9908,18 @@ function pluginsByName(options) {
 * or
 *   foo/bar.wesl COND=false ?static
 *
+* Bundlers may add extra query params (e.g. Vite adds ?import for dynamic imports,
+* ?t=123 for cache busting), so we capture the full query and search within it.
+*
 * someday it'd be nice to support import attributes like:
 *    import "foo.bar.wesl?static" with { COND: false};
 * (but that doesn't seem supported to be supported in the the bundler plugins yet)
 */
-const pluginMatch = /(^^)?(?<baseId>.*\.w[eg]sl)(?<cond>(\s*\w+(=\w+)?\s*)*)\?(?<pluginName>[\w_-]+)$/;
+const pluginMatch = /(^^)?(?<baseId>.*\.w[eg]sl)(?<cond>(\s*\w+(=\w+)?\s*)*)\?(?<query>.+)$/;
 const resolvedPrefix = "^^";
 /** build plugin entry for 'resolverId'
 * to validate our javascript virtual module imports (with e.g. ?static or ?link suffixes) */
-function buildResolver(options, context) {
+function buildResolver(options, context, log) {
 	const suffixes = pluginNames(options);
 	return resolver;
 	/**
@@ -9927,39 +9933,58 @@ function buildResolver(options, context) {
 		if (id.startsWith(resolvedPrefix)) return id;
 		if (id === context.weslToml) return id;
 		const matched = pluginSuffixMatch(id, suffixes);
+		log("resolveId", {
+			id,
+			matched: !!matched,
+			suffixes
+		});
 		if (matched) {
 			const { importParams, baseId, pluginName } = matched;
 			const importerDir = path.dirname(importer);
-			return resolvedPrefix + path.join(importerDir, baseId) + importParams + "?" + pluginName;
+			const result = resolvedPrefix + path.join(importerDir, baseId) + importParams + "?" + pluginName;
+			log("resolveId resolved", { result });
+			return result;
 		}
 		return matched ? id : null;
 	}
 }
+/** Find matching plugin suffix in query string (handles ?import&static, ?t=123&static, etc.) */
 function pluginSuffixMatch(id, suffixes) {
-	const suffixMatch = id.match(pluginMatch);
-	const pluginName = suffixMatch?.groups?.pluginName;
-	if (!pluginName || !suffixes.includes(pluginName)) return null;
+	const match$1 = id.match(pluginMatch);
+	const query = match$1?.groups?.query;
+	if (!query) return null;
+	const segments = query.split("&");
+	const pluginName = suffixes.find((s) => segments.includes(s));
+	if (!pluginName) return null;
 	return {
 		pluginName,
-		baseId: suffixMatch.groups.baseId,
-		importParams: suffixMatch.groups?.cond
+		baseId: match$1.groups.baseId,
+		importParams: match$1.groups?.cond
 	};
 }
 /** build plugin function for serving a javascript module in response to
 * an import of of our virtual import modules. */
-function buildLoader(context) {
+function buildLoader(context, log) {
 	const { options } = context;
 	const suffixes = pluginNames(options);
 	const pluginsMap = pluginsByName(options);
 	return loader;
 	async function loader(id) {
 		const matched = pluginSuffixMatch(id, suffixes);
+		log("load", {
+			id,
+			matched: matched?.pluginName ?? null
+		});
 		if (matched) {
 			const buildPluginApi = buildApi(context, this);
 			const plugin = pluginsMap[matched.pluginName];
 			const { baseId, importParams } = matched;
 			const conditions = importParamsToConditions(importParams);
 			const shaderPath = baseId.startsWith(resolvedPrefix) ? baseId.slice(2) : baseId;
+			log("load emitting", {
+				shaderPath,
+				conditions
+			});
 			return await plugin.emitFn(shaderPath, buildPluginApi, conditions);
 		}
 		return null;
@@ -9981,6 +10006,13 @@ function importParamsToConditions(importParams) {
 	});
 	return Object.fromEntries(condEntries);
 }
+function fmtDebugData(data) {
+	return data ? " " + JSON.stringify(data) : "";
+}
+function debugLog(msg, data) {
+	console.error(`[wesl-plugin] ${msg}${fmtDebugData(data)}`);
+}
+function noopLog() {}
 const unplugin = createUnplugin((options, meta) => {
 	return weslPlugin(options, meta);
 });

package/dist/{WeslPluginOptions-BXvD7dWh.d.ts → WeslPluginOptions-BljqDSO5.d.ts}

@@ -4,6 +4,8 @@ import { n as PluginExtension } from "./PluginExtension-DlhUTOLC.js";
 interface WeslPluginOptions {
   weslToml?: string;
   extensions?: PluginExtension[];
+  /** Log plugin activity to stderr for debugging */
+  debug?: boolean;
 }
 //#endregion
 export { WeslPluginOptions as t };

package/dist/pluginIndex.js

@@ -17,7 +17,7 @@ async function emitLinkJs(baseId, api) {
 	const autoDeps = await api.weslDependencies();
 	const sanitizedDeps = autoDeps.map((dep) => dep.replaceAll("/", "_"));
 	const bundleImports = autoDeps.map((p, i) => `import ${sanitizedDeps[i]} from "${p}";`).join("\n");
-	const paramsName = `link${path.basename(rootModuleName)}Config`;
+	const paramsName = `link${path.basename(rootModuleName).replace(/\W/g, "_")}Config`;
 	const linkParams = {
 		rootModuleName,
 		weslSrc,

package/dist/plugins/astro.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 
 //#region src/plugins/astro.d.ts
 declare const _default: (options: WeslPluginOptions) => any;

package/dist/plugins/astro.js

@@ -1,4 +1,4 @@
-import { t as WeslPlugin_default } from "../WeslPlugin-BhkB-CW-.js";
+import { t as WeslPlugin_default } from "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
 
 //#region src/plugins/astro.ts

package/dist/plugins/esbuild.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as esbuild0 from "esbuild";
 
 //#region src/plugins/esbuild.d.ts

package/dist/plugins/esbuild.js

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "../WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
 import { createEsbuildPlugin } from "unplugin";
 

package/dist/plugins/farm.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as _farmfe_core0 from "@farmfe/core";
 
 //#region src/plugins/farm.d.ts

package/dist/plugins/farm.js

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "../WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
 import { createFarmPlugin } from "unplugin";
 

package/dist/plugins/nuxt.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as _nuxt_schema0 from "@nuxt/schema";
 
 //#region src/plugins/nuxt.d.ts

package/dist/plugins/nuxt.js

@@ -1,7 +1,7 @@
-import "../WeslPlugin-BhkB-CW-.js";
+import "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
-import { t as vite_default } from "../vite-BqdMYd8l.js";
-import { t as webpack_default } from "../webpack-D-jacRMO.js";
+import { t as vite_default } from "../vite-CE8Yhwk-.js";
+import { t as webpack_default } from "../webpack-C7YoLSyP.js";
 import { addVitePlugin, addWebpackPlugin, defineNuxtModule } from "@nuxt/kit";
 import "@nuxt/schema";
 

package/dist/plugins/rollup.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as rollup0 from "rollup";
 
 //#region src/plugins/rollup.d.ts

package/dist/plugins/rollup.js

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "../WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
 import { createRollupPlugin } from "unplugin";
 

package/dist/plugins/rspack.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 
 //#region src/plugins/rspack.d.ts
 declare const _default: (options: WeslPluginOptions) => RspackPluginInstance;

package/dist/plugins/rspack.js

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "../WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
 import { createRspackPlugin } from "unplugin";
 

package/dist/plugins/vite.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as vite0 from "vite";
 
 //#region src/plugins/vite.d.ts

package/dist/plugins/vite.js

@@ -1,5 +1,5 @@
-import "../WeslPlugin-BhkB-CW-.js";
+import "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
-import { t as vite_default } from "../vite-BqdMYd8l.js";
+import { t as vite_default } from "../vite-CE8Yhwk-.js";
 
 export { vite_default as default };

package/dist/plugins/webpack.d.ts

@@ -1,5 +1,5 @@
 import "../PluginExtension-DlhUTOLC.js";
-import { t as WeslPluginOptions } from "../WeslPluginOptions-BXvD7dWh.js";
+import { t as WeslPluginOptions } from "../WeslPluginOptions-BljqDSO5.js";
 import * as webpack0 from "webpack";
 
 //#region src/plugins/webpack.d.ts

package/dist/plugins/webpack.js

@@ -1,5 +1,5 @@
-import "../WeslPlugin-BhkB-CW-.js";
+import "../WeslPlugin-JYxf2uLM.js";
 import "../import-meta-resolve-CUFqnZwT.js";
-import { t as webpack_default } from "../webpack-D-jacRMO.js";
+import { t as webpack_default } from "../webpack-C7YoLSyP.js";
 
 export { webpack_default as default };

package/dist/{vite-BqdMYd8l.js → vite-CE8Yhwk-.js}

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "./WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "./WeslPlugin-JYxf2uLM.js";
 import { createVitePlugin } from "unplugin";
 
 //#region src/plugins/vite.ts

package/dist/{webpack-D-jacRMO.js → webpack-C7YoLSyP.js}

@@ -1,4 +1,4 @@
-import { n as weslPlugin } from "./WeslPlugin-BhkB-CW-.js";
+import { n as weslPlugin } from "./WeslPlugin-JYxf2uLM.js";
 import { createWebpackPlugin } from "unplugin";
 
 //#region src/plugins/webpack.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wesl-plugin",
   "description": "",
-  "version": "0.6.47",
+  "version": "0.6.49",
   "type": "module",
   "files": [
     "src",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "unplugin": "^2.3.5",
-    "wesl": "0.6.47"
+    "wesl": "0.6.49"
   },
   "devDependencies": {
     "@nuxt/kit": "^3.17.6",

package/src/WeslPlugin.ts

@@ -50,6 +50,8 @@ export interface PluginContext {
   weslToml?: string;
 }
 
+type DebugLog = (msg: string, data?: Record<string, unknown>) => void;
+
 /**
  * A bundler plugin for processing WESL files.
  *
@@ -66,12 +68,16 @@ export function weslPlugin(
 ): UnpluginOptions {
   const cache: PluginCache = {};
   const context: PluginContext = { cache, meta, options };
+  const log = options.debug ? debugLog : noopLog;
+
+  log("init", { extensions: options.extensions?.map(e => e.extensionName) });
 
   return {
     name: "wesl-plugin",
-    resolveId: buildResolver(options, context),
-    load: buildLoader(context),
+    resolveId: buildResolver(options, context, log),
+    load: buildLoader(context, log),
     watchChange(id, _change) {
+      log("watchChange", { id });
       if (id.endsWith("wesl.toml")) {
         // The cache is shared for multiple imports
         cache.weslToml = undefined;
@@ -100,12 +106,15 @@ function pluginsByName(
  * or
  *   foo/bar.wesl COND=false ?static
  *
+ * Bundlers may add extra query params (e.g. Vite adds ?import for dynamic imports,
+ * ?t=123 for cache busting), so we capture the full query and search within it.
+ *
  * someday it'd be nice to support import attributes like:
  *    import "foo.bar.wesl?static" with { COND: false};
  * (but that doesn't seem supported to be supported in the the bundler plugins yet)
  */
 const pluginMatch =
-  /(^^)?(?<baseId>.*\.w[eg]sl)(?<cond>(\s*\w+(=\w+)?\s*)*)\?(?<pluginName>[\w_-]+)$/;
+  /(^^)?(?<baseId>.*\.w[eg]sl)(?<cond>(\s*\w+(=\w+)?\s*)*)\?(?<query>.+)$/;
 
 const resolvedPrefix = "^^";
 
@@ -114,6 +123,7 @@ const resolvedPrefix = "^^";
 function buildResolver(
   options: WeslPluginOptions,
   context: PluginContext,
+  log: DebugLog,
 ): Resolver {
   const suffixes = pluginNames(options);
   return resolver;
@@ -141,6 +151,7 @@ function buildResolver(
       return id;
     }
     const matched = pluginSuffixMatch(id, suffixes);
+    log("resolveId", { id, matched: !!matched, suffixes });
     if (matched) {
       const { importParams, baseId, pluginName } = matched;
 
@@ -149,6 +160,7 @@ function buildResolver(
       const pathToShader = path.join(importerDir, baseId);
       const result =
         resolvedPrefix + pathToShader + importParams + "?" + pluginName;
+      log("resolveId resolved", { result });
       return result;
     }
     return matched ? id : null; // this case doesn't happen AFAIK
@@ -161,20 +173,27 @@ interface PluginMatch {
   pluginName: string;
 }
 
+/** Find matching plugin suffix in query string (handles ?import&static, ?t=123&static, etc.) */
 function pluginSuffixMatch(id: string, suffixes: string[]): PluginMatch | null {
-  const suffixMatch = id.match(pluginMatch);
-  const pluginName = suffixMatch?.groups?.pluginName;
-  if (!pluginName || !suffixes.includes(pluginName)) return null;
+  const match = id.match(pluginMatch);
+  const query = match?.groups?.query;
+  if (!query) return null;
+
+  // Query params are &-separated; find one that matches a configured suffix
+  const segments = query.split("&");
+  const pluginName = suffixes.find(s => segments.includes(s));
+  if (!pluginName) return null;
+
   return {
     pluginName,
-    baseId: suffixMatch.groups!.baseId,
-    importParams: suffixMatch.groups?.cond,
+    baseId: match.groups!.baseId,
+    importParams: match.groups?.cond,
   };
 }
 
 /** build plugin function for serving a javascript module in response to
  * an import of of our virtual import modules. */
-function buildLoader(context: PluginContext): Loader {
+function buildLoader(context: PluginContext, log: DebugLog): Loader {
   const { options } = context;
   const suffixes = pluginNames(options);
   const pluginsMap = pluginsByName(options);
@@ -185,6 +204,7 @@ function buildLoader(context: PluginContext): Loader {
     id: string,
   ) {
     const matched = pluginSuffixMatch(id, suffixes);
+    log("load", { id, matched: matched?.pluginName ?? null });
     if (matched) {
       const buildPluginApi = buildApi(context, this);
       const plugin = pluginsMap[matched.pluginName];
@@ -194,6 +214,7 @@ function buildLoader(context: PluginContext): Loader {
         ? baseId.slice(resolvedPrefix.length)
         : baseId;
 
+      log("load emitting", { shaderPath, conditions });
       return await plugin.emitFn(shaderPath, buildPluginApi, conditions);
     }
 
@@ -226,6 +247,16 @@ function importParamsToConditions(
   return conditions;
 }
 
+function fmtDebugData(data?: Record<string, unknown>): string {
+  return data ? " " + JSON.stringify(data) : "";
+}
+
+function debugLog(msg: string, data?: Record<string, unknown>): void {
+  console.error(`[wesl-plugin] ${msg}${fmtDebugData(data)}`);
+}
+
+function noopLog(): void {}
+
 export const unplugin = createUnplugin(
   (options: WeslPluginOptions, meta: UnpluginContextMeta) => {
     return weslPlugin(options, meta);

package/src/WeslPluginOptions.ts

@@ -3,4 +3,7 @@ import type { PluginExtension } from "./PluginExtension.ts";
 export interface WeslPluginOptions {
   weslToml?: string;
   extensions?: PluginExtension[];
+
+  /** Log plugin activity to stderr for debugging */
+  debug?: boolean;
 }

package/src/extensions/LinkExtension.ts

@@ -32,7 +32,7 @@ async function emitLinkJs(
     .map((p, i) => `import ${sanitizedDeps[i]} from "${p}";`)
     .join("\n");
 
-  const rootName = path.basename(rootModuleName);
+  const rootName = path.basename(rootModuleName).replace(/\W/g, "_");
   const paramsName = `link${rootName}Config`;
 
   const linkParams: LinkParams = {