wesl 0.7.24 → 0.7.26

package/README.md

@@ -41,5 +41,5 @@ fn random_color(uv: vec2u) -> vec3f {
 </pre>
 
 [wesl plugin]: https://www.npmjs.com/package/wesl-plugin
-[examples]: https://github.com/wgsl-tooling-wg/wesl-js/tree/main/tools/examples 
+[examples]: https://github.com/wgsl-tooling-wg/wesl-js/tree/main/examples 
 [wesl]: https://www.npmjs.com/package/wesl

package/dist/index.d.ts

@@ -887,8 +887,16 @@ interface LinkParams {
   /** function to construct globally unique wgsl identifiers */
   mangler?: ManglerFn;
 }
-/** Generate a virtual WESL module based on a set of conditions. */
-type VirtualLibraryFn = (conditions: Conditions) => string;
+/** Project config for web components and tools. */
+type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName">;
+/** Context passed to virtual library generators. */
+interface VirtualLibContext {
+  conditions: Conditions;
+  rootModulePath: string;
+  packageName: string;
+}
+/** Generate a virtual WESL module. */
+type VirtualLibraryFn = (ctx: VirtualLibContext) => string;
 /**
  * Link a set of WESL source modules (typically the text from .wesl files) into a single WGSL string.
  * Linking starts with a specified 'root' source module, and recursively incorporates code
@@ -925,23 +933,12 @@ declare function normalizeModuleName(name: string): string;
 //#endregion
 //#region src/BindIdents.d.ts
 /**
- * BindIdents pass: link reference identifiers to declarations.
- *
- * Goals:
- * - Link reference idents to declaration idents
- * - Collect used declarations (to emit in link)
- * - Create mangled names for globals to avoid conflicts
+ * BindIdents pass: depth-first walk of the scope tree (not syntax tree),
+ * linking ref idents to declarations and mangling global names.
  *
- * Algorithm:
- * - Recursive depth-first walk of scope tree (not syntax tree)
- * - For each ref: search current scope, then up to parent scopes
- * - If no local match: check import statements for external matches
- * - For found global decls: mangle name to be unique, collect for emission
- *
- * LiveDecls: tracks visible declarations at the current position, with parent links.
- *
- * @if/@else: respects conditional compilation by tracking @else validity state,
- * mirroring the emission phase's filterValidElements but on scopes.
+ * For each ref: search current scope upward, then check imports for external matches.
+ * LiveDecls tracks visible declarations with parent links.
+ * @if/@else: mirrors filterValidElements but on scopes.
  */
 /** Results returned from binding pass. */
 interface BindResults {
@@ -1012,6 +1009,8 @@ interface BindContext {
   virtuals?: VirtualLibrarySet;
   /** Host package name for resolving package:: in virtual modules. */
   packageName: string;
+  /** Root module path (e.g., "package::main"). */
+  rootModulePath: string;
   /** Unbound identifiers if accumulateUnbound is true. */
   unbound?: UnboundRef[];
   /** Don't follow references from declarations (for library dependency detection). */
@@ -1019,11 +1018,7 @@ interface BindContext {
   /** Visit all conditional branches (for dependency discovery). */
   discoveryMode?: boolean;
 }
-/**
- * Recursively bind references to declarations in this scope and child scopes.
- * Tracks @else state to ensure filtered @else blocks don't pull in unused declarations.
- * @return new declarations found
- */
+/** Recursively bind refs to decls in this scope and children. @return new declarations found */
 declare function bindIdentsRecursive(scope: Scope, bindContext: BindContext, liveDecls: LiveDecls): DeclIdent[];
 //#endregion
 //#region src/Conditions.d.ts
@@ -1282,4 +1277,4 @@ declare function offsetToLineNumber(offset: number, text: string): [lineNum: num
  */
 declare function errorHighlight(source: string, span: Span): [string, string];
 //#endregion
-export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BlockStatement, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, ConditionalAttribute, Conditions, ConstAssertElem, ConstElem, ContainerElem, ContinuingElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DiagnosticRule, DirectiveElem, DirectiveVariant, ElemKindMap, ElemWithAttributes, ElemWithContentsBase, ElifAttribute, ElseAttribute, EmittableElem, EnableDirective, ExpressionElem, ExtendedGPUValidationError, FnElem, FnParamElem, FunctionCallExpression, GlobalDeclarationElem, GlobalVarElem, GrammarElem, HasAttributes, Ident, IfAttribute, ImportCollection, ImportElem, ImportItem, ImportSegment, ImportStatement, InterpolateAttribute, LetElem, LexicalScope, LinkConfig, LinkParams, LinkRegistryParams, LinkedWesl, LinkerTransform, Literal, LiveDecls, ManglerFn, ModuleElem, ModuleResolver, NameElem, OpenElem, OverrideElem, ParenthesizedExpression, ParseError, type ParseOptions, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, ScopeItem, SimpleMemberRef, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TrackingResolver, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnboundRef, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, discoverModules, emptyScope, errorHighlight, fileToModulePath, filterMap, filterValidElements, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, freshResolver, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, wgslStandardAttributes, withLoggerAsync };
+export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BlockStatement, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, ConditionalAttribute, Conditions, ConstAssertElem, ConstElem, ContainerElem, ContinuingElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DiagnosticRule, DirectiveElem, DirectiveVariant, ElemKindMap, ElemWithAttributes, ElemWithContentsBase, ElifAttribute, ElseAttribute, EmittableElem, EnableDirective, ExpressionElem, ExtendedGPUValidationError, FnElem, FnParamElem, FunctionCallExpression, GlobalDeclarationElem, GlobalVarElem, GrammarElem, HasAttributes, Ident, IfAttribute, ImportCollection, ImportElem, ImportItem, ImportSegment, ImportStatement, InterpolateAttribute, LetElem, LexicalScope, LinkConfig, LinkParams, LinkRegistryParams, LinkedWesl, LinkerTransform, Literal, LiveDecls, ManglerFn, ModuleElem, ModuleResolver, NameElem, OpenElem, OverrideElem, ParenthesizedExpression, ParseError, type ParseOptions, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, ScopeItem, SimpleMemberRef, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TrackingResolver, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnboundRef, UnknownExpressionElem, VarElem, VirtualLibContext, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslProject, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, childIdent, childScope, containsScope, debug, debugContentsToString, discoverModules, emptyScope, errorHighlight, fileToModulePath, filterMap, filterValidElements, findAllRootDecls, findMap, findRefsToBindingStructs, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, freshResolver, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, multisampledTextureTypes, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveModulePath, sampledTextureTypes, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, stdEnumerant, stdEnumerants, stdFn, stdFns, stdType, stdTypes, textureStorageTypes, transformBindingReference, transformBindingStruct, underscoreMangle, validation, wgslStandardAttributes, withLoggerAsync };

package/dist/index.js

@@ -3633,9 +3633,8 @@ function flatImports(ast, conditions) {
 //#region src/BindIdents.ts
 /** Bind ref idents to declarations and mangle global declaration names. */
 function bindIdents(params) {
-	const { rootAst, resolver, virtuals, accumulateUnbound } = params;
+	const { rootAst, resolver, virtuals, accumulateUnbound, discoveryMode } = params;
 	const { conditions = {}, mangler = minimalMangle } = params;
-	const { discoveryMode } = params;
 	const packageName = rootAst.srcModule.modulePath.split("::")[0];
 	const rootDecls = discoveryMode ? findAllRootDecls(rootAst.rootScope) : findValidRootDecls(rootAst.rootScope, conditions);
 	const { globalNames, knownDecls } = initRootDecls(rootDecls);
@@ -3646,6 +3645,7 @@ function bindIdents(params) {
 		virtuals,
 		mangler,
 		packageName,
+		rootModulePath: rootAst.srcModule.modulePath,
 		foundScopes: /* @__PURE__ */ new Set(),
 		globalNames,
 		globalStatements: /* @__PURE__ */ new Map(),
@@ -3656,8 +3656,9 @@ function bindIdents(params) {
 		decls: new Map(rootDecls.map((d) => [d.originalName, d])),
 		parent: null
 	};
-	const fromRootDecls = rootDecls.flatMap((decl) => processDependentScope(decl, bindContext));
-	const fromRefs = bindIdentsRecursive(rootAst.rootScope, bindContext, liveDecls);
+	const fromRootDecls = rootDecls.flatMap((d) => processDependentScope(d, bindContext));
+	const { rootScope } = rootAst;
+	const fromRefs = bindIdentsRecursive(rootScope, bindContext, liveDecls);
 	const newStatements = [...bindContext.globalStatements.values()];
 	return {
 		decls: [...fromRootDecls, ...fromRefs],
@@ -3702,11 +3703,7 @@ function findAllRootDecls(rootScope) {
 function publicDecl(scope, name, conditions) {
 	return getValidRootDecls(scope, conditions).find((d) => d.originalName === name);
 }
-/**
-* Recursively bind references to declarations in this scope and child scopes.
-* Tracks @else state to ensure filtered @else blocks don't pull in unused declarations.
-* @return new declarations found
-*/
+/** Recursively bind refs to decls in this scope and children. @return new declarations found */
 function bindIdentsRecursive(scope, bindContext, liveDecls) {
 	const { dontFollowDecls, foundScopes } = bindContext;
 	if (foundScopes.has(scope)) return [];
@@ -3744,11 +3741,7 @@ function processDependentScope(decl, ctx) {
 	if (!rootDecls) return [];
 	return bindIdentsRecursive(dependentScope, ctx, makeLiveDecls(rootDecls));
 }
-/**
-* Trace references to their declarations.
-* Mutates to mangle declarations and mark std references.
-* @return found declaration, or undefined if already processed
-*/
+/** Resolve a ref to its declaration, mangling globals and marking std refs. */
 function handleRef(ident, liveDecls, bindContext) {
 	if (ident.refersTo || ident.std) return;
 	if (ident.conditionRef) return;
@@ -3828,7 +3821,8 @@ function findExport(pathParts, srcModule, ctx) {
 	const modulePath = resolveModulePath(pathParts, srcModule.modulePath.split("::")).slice(0, -1).join("::");
 	const moduleAst = ctx.resolver.resolveModule(modulePath) ?? virtualModule(pathParts[0], ctx);
 	if (!moduleAst) return void 0;
-	const decl = publicDecl(moduleAst.rootScope, last(pathParts), ctx.conditions);
+	const name = last(pathParts);
+	const decl = publicDecl(moduleAst.rootScope, name, ctx.conditions);
 	if (decl) return {
 		decl,
 		moduleAst
@@ -3839,9 +3833,14 @@ function virtualModule(moduleName, ctx) {
 	const found = ctx.virtuals?.[moduleName];
 	if (!found) return void 0;
 	if (found.ast) return found.ast;
-	const src = found.fn(ctx.conditions);
+	const { conditions, rootModulePath, packageName } = ctx;
+	const src = found.fn({
+		conditions,
+		rootModulePath,
+		packageName
+	});
 	found.ast = parseSrcModule({
-		modulePath: ctx.packageName + "::" + moduleName,
+		modulePath: packageName + "::" + moduleName,
 		debugFilePath: moduleName,
 		src
 	});
@@ -3861,8 +3860,8 @@ function rootLiveDecls(decl, conditions) {
 	assertThatDebug(scope.kind === "scope");
 	const root = scope;
 	if (!root._scopeDecls) {
-		const rootDecls = findValidRootDecls(scope, conditions);
-		root._scopeDecls = { decls: new Map(rootDecls.map((d) => [d.originalName, d])) };
+		const decls = findValidRootDecls(scope, conditions);
+		root._scopeDecls = { decls: new Map(decls.map((d) => [d.originalName, d])) };
 	}
 	return root._scopeDecls;
 }
@@ -4083,6 +4082,7 @@ function findUnboundRefs(resolver) {
 		globalStatements: /* @__PURE__ */ new Map(),
 		mangler: minimalMangle,
 		packageName: "package",
+		rootModulePath: "package::main",
 		unbound: [],
 		dontFollowDecls: true,
 		discoveryMode: true
@@ -4515,8 +4515,9 @@ function flattenLibraryTree(libs) {
 * that share some sources.)
 */
 function linkRegistry(params) {
-	const { transformedAst, newDecls, newStatements } = bindAndTransform(params);
-	return SrcMapBuilder.build(emitWgsl(transformedAst.moduleElem, transformedAst.srcModule, newDecls, newStatements, params.conditions));
+	const { transformedAst: ast, newDecls, newStatements } = bindAndTransform(params);
+	const builders = emitWgsl(ast.moduleElem, ast.srcModule, newDecls, newStatements, params.conditions);
+	return SrcMapBuilder.build(builders);
 }
 /** Bind identifiers and apply transform plugins */
 function bindAndTransform(params) {
@@ -4574,6 +4575,7 @@ function applyTransformPlugins(rootModule, globalNames, config) {
 	};
 	return filterMap(config?.plugins ?? [], (plugin) => plugin.transform).reduce((ast, transform) => transform(ast), startAst);
 }
+/** Assemble WGSL output from prologue statements, root module, and imported declarations. */
 function emitWgsl(rootModuleElem, srcModule, newDecls, newStatements, conditions = {}) {
 	const prologueBuilders = newStatements.map((s) => emitStatement(s, conditions));
 	const rootBuilder = new SrcMapBuilder({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wesl",
-  "version": "0.7.24",
+  "version": "0.7.26",
   "type": "module",
   "files": [
     "dist",
@@ -23,8 +23,7 @@
     "multi_pkg": "x",
     "terser": "^5.43.1",
     "typedoc": "^0.28.7",
-    "typedoc-theme-hierarchy": "^6.0.0",
-    "wrangler": "^4.22.0"
+    "typedoc-theme-hierarchy": "^6.0.0"
   },
   "license": "MIT",
   "keywords": [
@@ -38,7 +37,7 @@
     "build:nodebug": "vite build --config vite.nodebug.config.ts",
     "build:size": "./scripts/size-check.ts",
     "deploy:docsite": "run-s build:docs pages:deploy",
-    "pages:deploy": "wrangler pages deploy --project-name wesl-js docs",
+    "pages:deploy": "pnpx wrangler pages deploy --project-name wesl-js docs",
     "test": "vitest --hideSkippedTests",
     "test:cts": "./scripts/test-cts.ts",
     "test:nodebug": "vitest run --config vitest.nodebug.config.ts",

package/src/BindIdents.ts

@@ -28,23 +28,12 @@ import {
 import { last } from "./Util.ts";
 
 /**
- * BindIdents pass: link reference identifiers to declarations.
+ * BindIdents pass: depth-first walk of the scope tree (not syntax tree),
+ * linking ref idents to declarations and mangling global names.
  *
- * Goals:
- * - Link reference idents to declaration idents
- * - Collect used declarations (to emit in link)
- * - Create mangled names for globals to avoid conflicts
- *
- * Algorithm:
- * - Recursive depth-first walk of scope tree (not syntax tree)
- * - For each ref: search current scope, then up to parent scopes
- * - If no local match: check import statements for external matches
- * - For found global decls: mangle name to be unique, collect for emission
- *
- * LiveDecls: tracks visible declarations at the current position, with parent links.
- *
- * @if/@else: respects conditional compilation by tracking @else validity state,
- * mirroring the emission phase's filterValidElements but on scopes.
+ * For each ref: search current scope upward, then check imports for external matches.
+ * LiveDecls tracks visible declarations with parent links.
+ * @if/@else: mirrors filterValidElements but on scopes.
  */
 
 /** Results returned from binding pass. */
@@ -107,9 +96,9 @@ export interface BindIdentsParams
 
 /** Bind ref idents to declarations and mangle global declaration names. */
 export function bindIdents(params: BindIdentsParams): BindResults {
-  const { rootAst, resolver, virtuals, accumulateUnbound } = params;
+  const { rootAst, resolver, virtuals, accumulateUnbound, discoveryMode } =
+    params;
   const { conditions = {}, mangler = minimalMangle } = params;
-  const { discoveryMode } = params;
   const packageName = rootAst.srcModule.modulePath.split("::")[0];
 
   const rootDecls = discoveryMode
@@ -117,6 +106,7 @@ export function bindIdents(params: BindIdentsParams): BindResults {
     : findValidRootDecls(rootAst.rootScope, conditions);
   const { globalNames, knownDecls } = initRootDecls(rootDecls);
 
+  const rootModulePath = rootAst.srcModule.modulePath;
   const bindContext = {
     resolver,
     conditions,
@@ -124,6 +114,7 @@ export function bindIdents(params: BindIdentsParams): BindResults {
     virtuals,
     mangler,
     packageName,
+    rootModulePath,
     foundScopes: new Set<Scope>(),
     globalNames,
     globalStatements: new Map<AbstractElem, EmittableElem>(),
@@ -134,15 +125,11 @@ export function bindIdents(params: BindIdentsParams): BindResults {
   const decls = new Map(rootDecls.map(d => [d.originalName, d] as const));
   const liveDecls: LiveDecls = { decls, parent: null };
 
-  const fromRootDecls = rootDecls.flatMap(decl =>
-    processDependentScope(decl, bindContext),
-  );
-
-  const fromRefs = bindIdentsRecursive(
-    rootAst.rootScope,
-    bindContext,
-    liveDecls,
+  const fromRootDecls = rootDecls.flatMap(d =>
+    processDependentScope(d, bindContext),
   );
+  const { rootScope } = rootAst;
+  const fromRefs = bindIdentsRecursive(rootScope, bindContext, liveDecls);
   const newStatements = [...bindContext.globalStatements.values()];
   return {
     decls: [...fromRootDecls, ...fromRefs],
@@ -233,6 +220,9 @@ interface BindContext {
   /** Host package name for resolving package:: in virtual modules. */
   packageName: string;
 
+  /** Root module path (e.g., "package::main"). */
+  rootModulePath: string;
+
   /** Unbound identifiers if accumulateUnbound is true. */
   unbound?: UnboundRef[];
 
@@ -243,11 +233,7 @@ interface BindContext {
   discoveryMode?: boolean;
 }
 
-/**
- * Recursively bind references to declarations in this scope and child scopes.
- * Tracks @else state to ensure filtered @else blocks don't pull in unused declarations.
- * @return new declarations found
- */
+/** Recursively bind refs to decls in this scope and children. @return new declarations found */
 export function bindIdentsRecursive(
   scope: Scope,
   bindContext: BindContext,
@@ -257,8 +243,11 @@ export function bindIdentsRecursive(
   if (foundScopes.has(scope)) return [];
   foundScopes.add(scope);
 
-  const result = processScope(scope, bindContext, liveDecls);
-  const { newGlobals, newFromChildren } = result;
+  const { newGlobals, newFromChildren } = processScope(
+    scope,
+    bindContext,
+    liveDecls,
+  );
   const newFromRefs = dontFollowDecls
     ? []
     : handleDecls(newGlobals, bindContext);
@@ -301,11 +290,7 @@ function processDependentScope(decl: DeclIdent, ctx: BindContext): DeclIdent[] {
   return bindIdentsRecursive(dependentScope, ctx, makeLiveDecls(rootDecls));
 }
 
-/**
- * Trace references to their declarations.
- * Mutates to mangle declarations and mark std references.
- * @return found declaration, or undefined if already processed
- */
+/** Resolve a ref to its declaration, mangling globals and marking std refs. */
 function handleRef(
   ident: RefIdent,
   liveDecls: LiveDecls,
@@ -443,11 +428,8 @@ function findExport(
     ctx.resolver.resolveModule(modulePath) ?? virtualModule(pathParts[0], ctx);
   if (!moduleAst) return undefined;
 
-  const decl = publicDecl(
-    moduleAst.rootScope,
-    last(pathParts)!,
-    ctx.conditions,
-  );
+  const name = last(pathParts)!;
+  const decl = publicDecl(moduleAst.rootScope, name, ctx.conditions);
   if (decl) return { decl, moduleAst };
 }
 
@@ -460,10 +442,10 @@ function virtualModule(
   if (!found) return undefined;
   if (found.ast) return found.ast;
 
-  const src = found.fn(ctx.conditions);
-  const modulePath = ctx.packageName + "::" + moduleName;
-  const debugFilePath = moduleName;
-  found.ast = parseSrcModule({ modulePath, debugFilePath, src });
+  const { conditions, rootModulePath, packageName } = ctx;
+  const src = found.fn({ conditions, rootModulePath, packageName });
+  const modulePath = packageName + "::" + moduleName;
+  found.ast = parseSrcModule({ modulePath, debugFilePath: moduleName, src });
   return found.ast;
 }
 
@@ -490,10 +472,8 @@ function rootLiveDecls(
 
   const root = scope as LexicalScope;
   if (!root._scopeDecls) {
-    const rootDecls = findValidRootDecls(scope, conditions);
-    root._scopeDecls = {
-      decls: new Map(rootDecls.map(d => [d.originalName, d])),
-    };
+    const decls = findValidRootDecls(scope, conditions);
+    root._scopeDecls = { decls: new Map(decls.map(d => [d.originalName, d])) };
   }
   return root._scopeDecls;
 }

package/src/Linker.ts

@@ -91,8 +91,26 @@ export interface LinkParams {
   mangler?: ManglerFn;
 }
 
-/** Generate a virtual WESL module based on a set of conditions. */
-export type VirtualLibraryFn = (conditions: Conditions) => string;
+/** Project config for web components and tools. */
+export type WeslProject = Pick<
+  LinkParams,
+  | "weslSrc"
+  | "rootModuleName"
+  | "conditions"
+  | "constants"
+  | "libs"
+  | "packageName"
+>;
+
+/** Context passed to virtual library generators. */
+export interface VirtualLibContext {
+  conditions: Conditions;
+  rootModulePath: string;
+  packageName: string;
+}
+
+/** Generate a virtual WESL module. */
+export type VirtualLibraryFn = (ctx: VirtualLibContext) => string;
 
 /**
  * Link a set of WESL source modules (typically the text from .wesl files) into a single WGSL string.
@@ -182,18 +200,19 @@ export interface LinkRegistryParams
  * that share some sources.)
  */
 export function linkRegistry(params: LinkRegistryParams): SrcMap {
-  const bound = bindAndTransform(params);
-  const { transformedAst, newDecls, newStatements } = bound;
-
-  return SrcMapBuilder.build(
-    emitWgsl(
-      transformedAst.moduleElem,
-      transformedAst.srcModule,
-      newDecls,
-      newStatements,
-      params.conditions,
-    ),
+  const {
+    transformedAst: ast,
+    newDecls,
+    newStatements,
+  } = bindAndTransform(params);
+  const builders = emitWgsl(
+    ast.moduleElem,
+    ast.srcModule,
+    newDecls,
+    newStatements,
+    params.conditions,
   );
+  return SrcMapBuilder.build(builders);
 }
 
 export interface BoundAndTransformed {
@@ -214,15 +233,14 @@ export function bindAndTransform(
 
   const virtuals = setupVirtualLibs(params.virtualLibs, constants);
 
-  const bindParams = {
+  const bound = bindIdents({
     rootAst,
     resolver,
     conditions,
     virtuals,
     mangler,
-  };
-  const bindResults = bindIdents(bindParams);
-  const { globalNames, decls: newDecls, newStatements } = bindResults;
+  });
+  const { globalNames, decls: newDecls, newStatements } = bound;
 
   const transformedAst = applyTransformPlugins(rootAst, globalNames, config);
   return { transformedAst, newDecls, newStatements };
@@ -264,7 +282,7 @@ function setupVirtualLibs(
 ): VirtualLibrarySet | undefined {
   let libs = virtualLibs;
   if (constants) {
-    const constantsGen = () =>
+    const constantsGen: VirtualLibraryFn = () =>
       Object.entries(constants)
         .map(([name, value]) => `const ${name} = ${value};`)
         .join("\n");
@@ -284,14 +302,10 @@ function applyTransformPlugins(
   const startAst = { moduleElem, srcModule, globalNames, notableElems: {} };
   const plugins = config?.plugins ?? [];
   const transforms = filterMap(plugins, plugin => plugin.transform);
-  const transformedAst = transforms.reduce(
-    (ast, transform) => transform(ast),
-    startAst,
-  );
-
-  return transformedAst;
+  return transforms.reduce((ast, transform) => transform(ast), startAst);
 }
 
+/** Assemble WGSL output from prologue statements, root module, and imported declarations. */
 function emitWgsl(
   rootModuleElem: ModuleElem,
   srcModule: SrcModule,
@@ -342,7 +356,6 @@ function emitDecl(decl: DeclIdent, conditions: Conditions): SrcMapBuilder {
   return builder;
 }
 
-/* ---- Commentary on present and future features ---- */
 /*
 
 LATER

package/src/discovery/FindUnboundIdents.ts

@@ -42,6 +42,7 @@ export function findUnboundRefs(resolver: BatchModuleResolver): UnboundRef[] {
     globalStatements: new Map<AbstractElem, EmittableElem>(),
     mangler: minimalMangle,
     packageName: "package",
+    rootModulePath: "package::main",
     unbound: [] as UnboundRef[],
     dontFollowDecls: true,
     discoveryMode: true,