wesl-plugin 0.6.69 → 0.6.71

package/src/WeslPlugin.ts

@@ -19,23 +19,17 @@ import type { WeslPluginOptions } from "./WeslPluginOptions.ts";
 
 export type { WeslToml, WeslTomlInfo };
 
-/** internal cache used by the plugin to avoid reloading files
- * The assumption is that the plugin is used for a single wesl.toml and set of shaders
- * (a plugin instance supports only one shader project)
- */
+/** Cache for a single plugin instance (one wesl.toml / shader project). */
 interface PluginCache {
   registry?: RecordResolver;
   weslToml?: WeslTomlInfo;
 }
 
-/** some types from unplugin */
 type Resolver = (
   this: UnpluginBuildContext & UnpluginContext,
   id: string,
   importer: string | undefined,
-  options: {
-    isEntry: boolean;
-  },
+  options: { isEntry: boolean },
 ) => Thenable<string | ExternalIdResult | null | undefined>;
 
 type Loader = (
@@ -43,7 +37,7 @@ type Loader = (
   id: string,
 ) => Thenable<TransformResult>;
 
-/** convenient state for local functions */
+/** Shared state threaded through plugin functions. */
 export interface PluginContext {
   cache: PluginCache;
   options: WeslPluginOptions;
@@ -54,18 +48,9 @@ export interface PluginContext {
 
 type DebugLog = (msg: string, data?: Record<string, unknown>) => void;
 
-/**
- * A bundler plugin for processing WESL files.
- *
- * The plugin works by reading the wesl.toml file and possibly package.json
- *
- * The plugin is triggered by imports to special virtual module urls
- * two urls suffixes are supported:
- *  1. `import "./shaders/bar.wesl?reflect"` - produces a javascript file for binding struct reflection
- *  2. `import "./shaders/bar.wesl?link"` - produces a javascript file for preconstructed link functions
- */
 const builtinExtensions = [staticBuildExtension, linkBuildExtension];
 
+/** Bundler plugin for WESL files, triggered by ?link or ?static import suffixes. */
 export function weslPlugin(
   options: WeslPluginOptions | undefined,
   meta: UnpluginContextMeta,
@@ -85,13 +70,9 @@ export function weslPlugin(
     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;
-        cache.registry = undefined;
-      } else {
-        cache.registry = undefined;
-      }
+      // The cache is shared for multiple imports
+      if (id.endsWith("wesl.toml")) cache.weslToml = undefined;
+      cache.registry = undefined;
     },
   };
 }
@@ -107,26 +88,59 @@ function pluginsByName(
   return Object.fromEntries(entries);
 }
 
-/** wesl plugins match import statements of the form:
- *
- *   foo/bar.wesl?link
- * 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*)*)\?(?<query>.+)$/;
+/** Match .wesl/.wgsl imports with query params. Bundlers may append extra params. */
+const pluginMatch = /(^^)?(?<baseId>.*\.w[eg]sl)\?(?<query>.+)$/;
 
 const resolvedPrefix = "^^";
 
-/** build plugin entry for 'resolverId'
- * to validate our javascript virtual module imports (with e.g. ?static or ?link suffixes) */
+/** Reserved query param names (not treated as conditions). */
+const reservedParams = new Set(["include"]);
+
+interface ParsedQuery {
+  pluginName: string;
+  conditions?: Conditions;
+  options?: Record<string, string>;
+}
+
+/** Parse query string into plugin name, conditions, and options. */
+function parsePluginQuery(
+  query: string,
+  suffixes: string[],
+): ParsedQuery | null {
+  const segments = query.split("&");
+  const pluginName = suffixes.find(s => segments.includes(s));
+  if (!pluginName) return null;
+
+  const isBundlerParam = (s: string) => s === "import" || /^t=\d+/.test(s);
+  const userSegments = segments.filter(
+    s => s !== pluginName && !isBundlerParam(s),
+  );
+
+  const conditions: Record<string, boolean> = {};
+  const options: Record<string, string> = {};
+
+  for (const seg of userSegments) {
+    const eqIdx = seg.indexOf("=");
+    if (eqIdx === -1) {
+      conditions[seg] = true; // bare name like "FUN" ==> condition true
+    } else {
+      const key = seg.slice(0, eqIdx);
+      const val = seg.slice(eqIdx + 1);
+      if (reservedParams.has(key)) options[key] = val;
+      else conditions[key] = val !== "false";
+    }
+  }
+
+  const hasConds = Object.keys(conditions).length > 0;
+  const hasOpts = Object.keys(options).length > 0;
+  return {
+    pluginName,
+    conditions: hasConds ? conditions : undefined,
+    options: hasOpts ? options : undefined,
+  };
+}
+
+/** Build the resolveId hook for virtual module imports (?static, ?link, etc). */
 function buildResolver(
   options: WeslPluginOptions,
   context: PluginContext,
@@ -135,71 +149,34 @@ function buildResolver(
   const suffixes = pluginNames(options);
   return resolver;
 
-  // vite calls resolver only for odd import paths.
-  //   this doesn't call resolver: import wgsl from "../shaders/foo/app.wesl?static";
-  //   but this does call resolver: import wgsl from "../shaders/foo/app.wesl MOBILE=true FUN SAFE=false ?static";
-
-  /**
-   * For imports with conditions, vite won't resolve the module-path part of the js import
-   * so we do it here.
-   *
-   * To avoid recirculating on resolve(), we rewrite the resolution id to start with ^^
-   * The loader will drop the prefix.
-   */
+  // With pure query-param syntax, Vite resolves paths natively.
+  // The resolver is still needed for non-Vite bundlers that may not handle query params.
   function resolver(
     this: UnpluginBuildContext & UnpluginContext,
     id: string,
     importer: string | undefined,
   ): string | null {
-    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;
-
-      // resolve the path to the shader file
-      const importerDir = path.dirname(importer!);
-      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
+    if (id.startsWith(resolvedPrefix)) return id;
+    if (id === context.weslToml) return id;
+
+    const match = id.match(pluginMatch);
+    const query = match?.groups?.query;
+    if (!query) return null;
+
+    const parsed = parsePluginQuery(query, suffixes);
+    log("resolveId", { id, matched: !!parsed, suffixes });
+    if (!parsed) return null;
+
+    const baseId = match.groups!.baseId;
+    const importerDir = path.dirname(importer!);
+    const pathToShader = path.join(importerDir, baseId);
+    const result = resolvedPrefix + pathToShader + "?" + query;
+    log("resolveId resolved", { result });
+    return result;
   }
 }
 
-interface PluginMatch {
-  baseId: string;
-  importParams?: string;
-  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 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: 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. */
+/** Build the load hook that emits JS for virtual module imports. */
 function buildLoader(context: PluginContext, log: DebugLog): Loader {
   const { options } = context;
   const suffixes = pluginNames(options);
@@ -210,50 +187,27 @@ function buildLoader(context: PluginContext, log: DebugLog): Loader {
     this: UnpluginBuildContext & UnpluginContext,
     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];
-      const { baseId, importParams } = matched;
-      const conditions = importParamsToConditions(importParams);
-      const shaderPath = baseId.startsWith(resolvedPrefix)
-        ? baseId.slice(resolvedPrefix.length)
-        : baseId;
-
-      log("load emitting", { shaderPath, conditions });
-      return await plugin.emitFn(shaderPath, buildPluginApi, conditions);
-    }
-
-    return null;
+    const match = id.match(pluginMatch);
+    const query = match?.groups?.query;
+    if (!query) return null;
+
+    const parsed = parsePluginQuery(query, suffixes);
+    log("load", { id, matched: parsed?.pluginName ?? null });
+    if (!parsed) return null;
+
+    const buildPluginApi = buildApi(context, this);
+    const plugin = pluginsMap[parsed.pluginName];
+    const rawPath = match.groups!.baseId;
+    const shaderPath = rawPath.startsWith(resolvedPrefix)
+      ? rawPath.slice(resolvedPrefix.length)
+      : rawPath;
+
+    const { conditions, options: opts } = parsed;
+    log("load emitting", { shaderPath, conditions, options: opts });
+    return await plugin.emitFn(shaderPath, buildPluginApi, conditions, opts);
   }
 }
 
-/**
- * Convert an import parameters string to a Conditions record.
- *
- * Import parameters are key=value pairs separated by spaces.
- * Values may be "true" or "false" or missing (default to true)
- * e.g. ' MOBILE=true FUN SAFE=false '
- */
-function importParamsToConditions(
-  importParams: string | undefined,
-): Conditions | undefined {
-  if (!importParams) return undefined;
-  const params = importParams.trim().split(/\s+/);
-  const condEntries = params.map(p => {
-    const text = p.trim();
-    const [cond, value] = text.split("=");
-    if (value === undefined || value === "true") {
-      return [cond, true] as const;
-    } else {
-      return [cond, false] as const;
-    }
-  });
-  const conditions = Object.fromEntries(condEntries);
-  return conditions;
-}
-
 function fmtDebugData(data?: Record<string, unknown>): string {
   return data ? " " + JSON.stringify(data) : "";
 }
@@ -264,9 +218,5 @@ function debugLog(msg: string, data?: Record<string, unknown>): void {
 
 function noopLog(): void {}
 
-export const unplugin = createUnplugin(
-  (options: WeslPluginOptions, meta: UnpluginContextMeta) => {
-    return weslPlugin(options, meta);
-  },
-);
+export const unplugin = createUnplugin(weslPlugin);
 export default unplugin;

package/src/defaultSuffixTypes.d.ts

@@ -10,6 +10,12 @@ declare module "*?static" {
   export default wgsl;
 }
 
+/** @hidden */
+declare module "*?simple_reflect" {
+  import type { WeslStruct } from "wesl-reflect";
+  export const structs: WeslStruct[];
+}
+
 /** @hidden */ // LATER move to separate package
 declare module "*?bindingLayout" {
   export const layouts: Record<string, GPUBindGroupLayoutEntry[]>;

package/src/extensions/LinkExtension.ts

@@ -14,18 +14,18 @@ export const linkBuildExtension: PluginExtension = {
 async function emitLinkJs(
   baseId: string,
   api: PluginExtensionApi,
+  _conditions?: Record<string, boolean>,
+  options?: Record<string, string>,
 ): Promise<string> {
-  const { resolvedRoot, tomlDir } = await api.weslToml();
-
-  const weslSrc = await api.weslSrc();
-
   const rootModule = await api.weslMain(baseId);
   const rootModuleName = noSuffix(rootModule);
 
-  const tomlRelative = path.relative(tomlDir, resolvedRoot);
-  const debugWeslRoot = tomlRelative.replaceAll(path.sep, "/");
+  const [{ weslSrc, dependencies: autoDeps }, debugWeslRoot] =
+    await Promise.all([
+      api.fetchProject(rootModuleName, options),
+      api.debugWeslRoot(),
+    ]);
 
-  const autoDeps = await api.weslDependencies();
   const sanitizedDeps = autoDeps.map(dep => dep.replaceAll("/", "_"));
 
   const bundleImports = autoDeps
@@ -35,25 +35,18 @@ async function emitLinkJs(
   const rootName = path.basename(rootModuleName).replace(/\W/g, "_");
   const paramsName = `link${rootName}Config`;
 
-  const linkParams: LinkParams = {
-    rootModuleName,
-    weslSrc,
-    debugWeslRoot,
-  };
-
+  const linkParams: LinkParams = { rootModuleName, weslSrc, debugWeslRoot };
   const libsStr = `libs: [${sanitizedDeps.join(", ")}]`;
   const linkParamsStr = `{
     ${serializeFields(linkParams)},
     ${libsStr},
   }`;
 
-  const src = `
+  return `
     ${bundleImports}
     export const ${paramsName} = ${linkParamsStr};
     export default ${paramsName};
     `;
-
-  return src;
 }
 
 function serializeFields(record: Record<string, any>) {

package/src/extensions/ReflectExtension.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs/promises";
+import type { StructElem } from "wesl";
+import { originalTypeName, weslStructs, wgslTypeToTs } from "wesl-reflect";
+import type {
+  PluginExtension,
+  PluginExtensionApi,
+} from "../PluginExtension.ts";
+
+export interface SimpleReflectOptions {
+  /** directory to contain the .d.ts files or undefined to not write .d.ts files */
+  typesDir?: string;
+}
+
+/** wesl-js build extension to reflect wgsl structs into js and .d.ts files. */
+export function simpleReflect(
+  options: SimpleReflectOptions = {},
+): PluginExtension {
+  const { typesDir = "./src/types" } = options;
+  return {
+    extensionName: "simple_reflect",
+    emitFn: async (_baseId: string, api: PluginExtensionApi) => {
+      const registry = await api.weslRegistry();
+      const astStructs = [...registry.allModules()].flatMap(([, module]) =>
+        module.moduleElem.contents.filter(
+          (e): e is StructElem => e.kind === "struct",
+        ),
+      );
+
+      const jsStructs = weslStructs(astStructs);
+      if (typesDir) await writeTypes(astStructs, typesDir);
+
+      const structArray = JSON.stringify(jsStructs, null, 2);
+      return `export const structs = ${structArray};`;
+    },
+  };
+}
+
+/** Write .d.ts file with TypeScript interfaces for reflected structs. */
+async function writeTypes(
+  structs: StructElem[],
+  typesDir: string,
+): Promise<void> {
+  const tsdInterfaces = structs.map(s => {
+    const name = s.name.ident.originalName;
+    const entries = s.members.map(m => {
+      const tsType = wgslTypeToTs(originalTypeName(m.typeRef));
+      return `  ${m.name.name}: ${tsType};`;
+    });
+    return `interface ${name} {\n${entries.join("\n")}\n}`;
+  });
+  await fs.mkdir(typesDir, { recursive: true });
+  await fs.writeFile(`${typesDir}/reflectTypes.d.ts`, tsdInterfaces.join("\n"));
+}

package/src/extensions/StaticExtension.ts

@@ -7,64 +7,50 @@ import type {
   PluginExtensionApi,
 } from "../PluginExtension.ts";
 
-/**
- * a wesl-js ?static build extension that statically links from the root file
- * and emits a JavaScript file containing the linked wgsl string.
- *
- * use it like this:
- *   import wgsl from "./shaders/app.wesl?static";
- *
- * or with conditions, like this:
- *   import wgsl from "../shaders/foo/app.wesl MOBILE=true FUN SAFE=false ?static";
- */
+/** Build extension for ?static imports: links WESL at build time, emits WGSL string. */
 export const staticBuildExtension: PluginExtension = {
   extensionName: "static",
   emitFn: emitStaticJs,
 };
 
-/** Emit a JavaScript file containing the wgsl string */
+/** Emit a JS module exporting the statically linked WGSL string. */
 async function emitStaticJs(
   baseId: string,
   api: PluginExtensionApi,
   conditions?: Conditions,
+  _options?: Record<string, string>,
 ): Promise<string> {
   const { resolvedRoot, tomlDir } = await api.weslToml();
 
-  // resolve import module relative to the root of the shader project
-  const parentModule = url
-    .pathToFileURL(path.join(tomlDir, "wesl.toml"))
-    .toString();
+  const tomlUrl = url.pathToFileURL(path.join(tomlDir, "wesl.toml"));
+  const parentModule = tomlUrl.toString();
+
+  const rootModule = await api.weslMain(baseId);
+  const rootModuleName = noSuffix(rootModule);
+
+  const [weslSrc, dependencies] = await Promise.all([
+    api.weslSrc(),
+    api.weslDependencies(),
+  ]);
 
-  const dependencies = await api.weslDependencies();
   const libFileUrls = dependencies.map(d => resolve(d, parentModule));
 
-  // load the lib modules
-  const futureLibs = libFileUrls.map(f => import(f));
-  const libModules = await Promise.all(futureLibs);
+  const libModules = await Promise.all(libFileUrls.map(f => import(f)));
   const libs = libModules.map(m => m.default);
 
-  // find weslSrc and rootModule
-  const weslSrc = await api.weslSrc();
-  const rootModule = await api.weslMain(baseId);
-  const rootModuleName = noSuffix(rootModule);
-
-  // find weslRoot
   const tomlRelative = path.relative(tomlDir, resolvedRoot);
   const debugWeslRoot = tomlRelative.replaceAll(path.sep, "/");
 
-  const result = await link({
+  const { dest: wgsl } = await link({
     weslSrc,
     rootModuleName,
     debugWeslRoot,
     libs,
     conditions,
   });
-  const wgsl = result.dest;
 
-  const src = `
+  return `
     export const wgsl = \`${wgsl}\`;
     export default wgsl;
   `;
-
-  return src;
 }

package/src/pluginIndex.ts

@@ -1,3 +1,4 @@
 export * from "./extensions/LinkExtension.ts";
+export * from "./extensions/ReflectExtension.ts";
 export * from "./extensions/StaticExtension.ts";
 export * from "./PluginExtension.ts";