wesl 0.7.25 → 0.7.27

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/examples 
+[examples]: https://github.com/webgpu-tools/wesl-js/tree/main/examples 
 [wesl]: https://www.npmjs.com/package/wesl

package/dist/index.d.ts

@@ -279,7 +279,7 @@ type ElemKindMap = {
   type: TypeRefElem;
   var: VarElem;
 };
-/** Inspired by https://github.com/wgsl-tooling-wg/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
+/** Inspired by https://github.com/webgpu-tools/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
 type ExpressionElem = Literal | RefIdentElem | TypeRefElem | ParenthesizedExpression | ComponentExpression | ComponentMemberExpression | UnaryExpression | BinaryExpression | FunctionCallExpression;
 type TerminalElem = DirectiveElem | DeclIdentElem | NameElem | RefIdentElem | TextElem | ImportElem;
 type GlobalDeclarationElem = AliasElem | ConstElem | FnElem | GlobalVarElem | OverrideElem | StructElem;
@@ -737,7 +737,7 @@ globalNames: Set<string>) => string;
 /**
  * Construct a globally unique name based on the declaration
  * module path separated by underscores.
- * Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/wgsl-tooling-wg/wesl-spec/blob/main/NameMangling.md)
+ * Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/webgpu-tools/wesl-spec/blob/main/NameMangling.md)
  */
 declare function underscoreMangle(decl: DeclIdent, srcModule: SrcModule): string;
 /**
@@ -844,27 +844,15 @@ interface LinkConfig {
   plugins?: WeslJsPlugin[];
 }
 interface LinkParams {
-  /** Module resolver for lazy loading (NEW API - preferred)
-   * Replaces weslSrc for lazy module loading.
-   * If provided, weslSrc will be ignored. */
+  /** Module resolver for lazy loading. If provided, weslSrc is ignored. */
   resolver?: ModuleResolver;
-  /** record of file paths and wesl text for modules (LEGACY API - still supported).
-   *   key is module path or file path
-   *     `package::foo::bar`, or './foo/bar.wesl', or './foo/bar'
-   *   value is wesl src
-   *
-   *
-   * Only accepts unix-style, relative filesystem paths that are valid WGSL identifiers
-   * - Unix-style: Slashes as separators.
-   * - Valid WGSL identifiers: No backslashes, no `..`, or other non-identifier symbols.
-   * - Relative paths: They have to be relative to the wesl root.
-   */
+  /** Record of module sources keyed by module path (`package::foo::bar`)
+   * or relative file path (`./foo/bar.wesl`). Paths must be unix-style,
+   * relative to the wesl root, and valid WGSL identifiers. */
   weslSrc?: Record<string, string>;
-  /** name of root wesl module
-   *    for an app, the root module normally contains the '@compute', '@vertex' or '@fragment' entry points
-   *    for a library, the root module defines the public api fo the library
-   *  can be specified as file path (./main.wesl), a module path (package::main), or just a module name (main)
-   */
+  /** Root module name: file path (`./main.wesl`), module path (`package::main`), or bare name (`main`).
+   * For apps, the root module contains entry points (`@compute`, `@vertex`, `@fragment`).
+   * For libraries, it defines the public API. */
   rootModuleName?: string;
   /** For debug logging. Will be prepended to file paths. */
   debugWeslRoot?: string;
@@ -888,9 +876,17 @@ interface LinkParams {
   mangler?: ManglerFn;
 }
 /** Project config for web components and tools. */
-type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName">;
-/** Generate a virtual WESL module based on a set of conditions. */
-type VirtualLibraryFn = (conditions: Conditions) => string;
+type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName"> & {
+  /** Shader directory relative to project root (set by ?link from wesl.toml). */shaderRoot?: string;
+};
+/** 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
@@ -927,23 +923,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
- *
- * 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
+ * BindIdents pass: depth-first walk of the scope tree (not syntax tree),
+ * linking ref idents to declarations and mangling global names.
  *
- * 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 {
@@ -1014,6 +999,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). */
@@ -1021,11 +1008,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
@@ -1284,4 +1267,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, 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 };
+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

@@ -283,12 +283,13 @@ const isBrowser = "document" in globalThis;
 /** Throw an error with an embedded source map so that browser users can
 *  click on the error in the browser debug console and see the wesl source code.  */
 function throwClickableError(params) {
-	const { url, text, lineNumber, lineColumn, length, error } = params;
+	const { url, text, lineNumber, lineColumn, length, offset, error } = params;
 	const weslLocation = {
 		file: url,
 		line: lineNumber,
 		column: lineColumn,
-		length
+		length,
+		offset
 	};
 	error.weslLocation = weslLocation;
 	if (!isBrowser) throw error;
@@ -349,6 +350,7 @@ function failIdentElem(identElem, msg = "") {
 		lineNumber,
 		lineColumn,
 		length: end - start,
+		offset: start,
 		error: new Error(detailedMessage)
 	});
 }
@@ -656,7 +658,7 @@ function lowerAndEmitElem(e, ctx) {
 		case "let":
 		case "statement":
 		case "continuing":
-			emitStatement$1(e, ctx);
+			emitStatement(e, ctx);
 			return;
 		case "override":
 		case "const":
@@ -694,7 +696,7 @@ function emitModule(e, ctx) {
 		lowerAndEmitElem(child, ctx);
 	}
 }
-function emitStatement$1(e, ctx) {
+function emitStatement(e, ctx) {
 	if (!(e.contents.length > 0 && e.contents[0].kind === "attribute")) emitAttributes(e.attributes, ctx);
 	emitContents(e, ctx);
 }
@@ -1257,7 +1259,7 @@ function liveDeclsToString(liveDecls) {
 /**
 * Construct a globally unique name based on the declaration
 * module path separated by underscores.
-* Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/wgsl-tooling-wg/wesl-spec/blob/main/NameMangling.md)
+* Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/webgpu-tools/wesl-spec/blob/main/NameMangling.md)
 */
 function underscoreMangle(decl, srcModule) {
 	const { modulePath } = srcModule;
@@ -3633,9 +3635,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 +3647,7 @@ function bindIdents(params) {
 		virtuals,
 		mangler,
 		packageName,
+		rootModulePath: rootAst.srcModule.modulePath,
 		foundScopes: /* @__PURE__ */ new Set(),
 		globalNames,
 		globalStatements: /* @__PURE__ */ new Map(),
@@ -3656,8 +3658,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 +3705,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 +3743,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 +3823,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 +3835,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 +3862,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 +4084,7 @@ function findUnboundRefs(resolver) {
 		globalStatements: /* @__PURE__ */ new Map(),
 		mangler: minimalMangle,
 		packageName: "package",
+		rootModulePath: "package::main",
 		unbound: [],
 		dontFollowDecls: true,
 		discoveryMode: true
@@ -4468,20 +4470,13 @@ async function link(params) {
 }
 /** linker api for benchmarking */
 function _linkSync(params) {
-	const { weslSrc, libs = [], packageName, debugWeslRoot } = params;
-	const { resolver } = params;
-	const resolvers = [];
-	if (resolver) resolvers.push(resolver);
-	else if (weslSrc) resolvers.push(new RecordResolver(weslSrc, {
+	const { weslSrc, libs = [], packageName, debugWeslRoot, resolver } = params;
+	if (!resolver && !weslSrc) throw new Error("Either resolver or weslSrc must be provided");
+	const allResolvers = [resolver ?? new RecordResolver(weslSrc, {
 		packageName,
 		debugWeslRoot
-	}));
-	else throw new Error("Either resolver or weslSrc must be provided");
-	if (libs.length > 0) {
-		const libResolvers = createLibraryResolvers(libs, debugWeslRoot);
-		resolvers.push(...libResolvers);
-	}
-	const finalResolver = resolvers.length === 1 ? resolvers[0] : new CompositeResolver(resolvers);
+	}), ...createLibraryResolvers(libs, debugWeslRoot)];
+	const finalResolver = allResolvers.length === 1 ? allResolvers[0] : new CompositeResolver(allResolvers);
 	return linkRegistry({
 		...params,
 		resolver: finalResolver
@@ -4515,8 +4510,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) {
@@ -4564,6 +4560,7 @@ function setupVirtualLibs(virtualLibs, constants) {
 	}
 	return libs && mapValues(libs, (fn) => ({ fn }));
 }
+/** Run registered transform plugins over the bound AST. */
 function applyTransformPlugins(rootModule, globalNames, config) {
 	const { moduleElem, srcModule } = rootModule;
 	const startAst = {
@@ -4574,54 +4571,40 @@ 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({
-		text: srcModule.src,
-		path: srcModule.debugFilePath
-	});
+	const prologueBuilders = newStatements.map((s) => emitElem(s.srcModule, s.elem, conditions, { addNl: true }));
+	const rootBuilder = builderFromModule(srcModule);
 	lowerAndEmit({
 		srcBuilder: rootBuilder,
 		rootElems: [rootModuleElem],
 		conditions,
 		extracting: false
 	});
-	const declBuilders = newDecls.map((decl) => emitDecl(decl, conditions));
+	const declBuilders = newDecls.map((decl) => emitElem(decl.srcModule, decl.declElem, conditions, { skipConditionalFiltering: true }));
 	return [
 		...prologueBuilders,
 		rootBuilder,
 		...declBuilders
 	];
 }
-function emitStatement(s, conditions) {
-	const { elem, srcModule } = s;
-	const { src: text, debugFilePath: path } = srcModule;
-	const builder = new SrcMapBuilder({
-		text,
-		path
-	});
+/** Emit a single element (prologue statement or imported declaration) into a SrcMapBuilder. */
+function emitElem(srcModule, elem, conditions, opts = {}) {
+	const builder = builderFromModule(srcModule);
 	lowerAndEmit({
 		srcBuilder: builder,
 		rootElems: [elem],
-		conditions
+		conditions,
+		skipConditionalFiltering: opts.skipConditionalFiltering
 	});
-	builder.addNl();
+	if (opts.addNl) builder.addNl();
 	return builder;
 }
-/** Skip conditional filtering because findValidRootDecls already validated these declarations */
-function emitDecl(decl, conditions) {
-	const { src: text, debugFilePath: path } = decl.srcModule;
-	const builder = new SrcMapBuilder({
-		text,
-		path
-	});
-	lowerAndEmit({
-		srcBuilder: builder,
-		rootElems: [decl.declElem],
-		conditions,
-		skipConditionalFiltering: true
+function builderFromModule(srcModule) {
+	return new SrcMapBuilder({
+		text: srcModule.src,
+		path: srcModule.debugFilePath
 	});
-	return builder;
 }
 //#endregion
 //#region src/LinkerUtil.ts
@@ -4922,6 +4905,7 @@ function makeWeslDevice(device) {
 					lineNumber: message.lineNum,
 					lineColumn: message.linePos,
 					length: message.length,
+					offset: message.offset,
 					error: /* @__PURE__ */ new Error(message.type + ": " + message.message)
 				});
 				else console.error(ev.error.message);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "wesl",
-  "version": "0.7.25",
+  "version": "0.7.27",
   "type": "module",
   "files": [
     "dist",
     "src"
   ],
-  "repository": "github:wgsl-tooling-wg/wesl-js",
+  "repository": "github:webgpu-tools/wesl-js",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/AbstractElems.ts

@@ -52,7 +52,7 @@ export type ElemKindMap = {
   var: VarElem;
 };
 
-/** Inspired by https://github.com/wgsl-tooling-wg/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
+/** Inspired by https://github.com/webgpu-tools/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
 export type ExpressionElem =
   | Literal
   | RefIdentElem

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/ClickableError.ts

@@ -9,6 +9,8 @@ export interface WeslErrorLocation {
   line: number;
   column: number;
   length: number;
+  /** byte offset into the source file */
+  offset: number;
 }
 
 export interface ClickableErrorParams {
@@ -27,6 +29,9 @@ export interface ClickableErrorParams {
   /** number of characters in the error section */
   length: number;
 
+  /** byte offset of the error section within the source text */
+  offset: number;
+
   /** the original error */
   error: Error;
 }
@@ -36,12 +41,13 @@ const isBrowser = "document" in globalThis;
 /** Throw an error with an embedded source map so that browser users can
  *  click on the error in the browser debug console and see the wesl source code.  */
 export function throwClickableError(params: ClickableErrorParams): void {
-  const { url, text, lineNumber, lineColumn, length, error } = params;
+  const { url, text, lineNumber, lineColumn, length, offset, error } = params;
   const weslLocation: WeslErrorLocation = {
     file: url,
     line: lineNumber,
     column: lineColumn,
     length,
+    offset,
   };
   (error as any).weslLocation = weslLocation;
   if (!debug || !isBrowser) throw error;
@@ -142,6 +148,7 @@ export function failIdentElem(
     lineNumber,
     lineColumn,
     length,
+    offset: start,
     error: new Error(detailedMessage),
   });
 }

package/src/Linker.ts

@@ -37,29 +37,17 @@ export interface LinkConfig {
 }
 
 export interface LinkParams {
-  /** Module resolver for lazy loading (NEW API - preferred)
-   * Replaces weslSrc for lazy module loading.
-   * If provided, weslSrc will be ignored. */
+  /** Module resolver for lazy loading. If provided, weslSrc is ignored. */
   resolver?: ModuleResolver;
 
-  /** record of file paths and wesl text for modules (LEGACY API - still supported).
-   *   key is module path or file path
-   *     `package::foo::bar`, or './foo/bar.wesl', or './foo/bar'
-   *   value is wesl src
-   *
-   *
-   * Only accepts unix-style, relative filesystem paths that are valid WGSL identifiers
-   * - Unix-style: Slashes as separators.
-   * - Valid WGSL identifiers: No backslashes, no `..`, or other non-identifier symbols.
-   * - Relative paths: They have to be relative to the wesl root.
-   */
+  /** Record of module sources keyed by module path (`package::foo::bar`)
+   * or relative file path (`./foo/bar.wesl`). Paths must be unix-style,
+   * relative to the wesl root, and valid WGSL identifiers. */
   weslSrc?: Record<string, string>;
 
-  /** name of root wesl module
-   *    for an app, the root module normally contains the '@compute', '@vertex' or '@fragment' entry points
-   *    for a library, the root module defines the public api fo the library
-   *  can be specified as file path (./main.wesl), a module path (package::main), or just a module name (main)
-   */
+  /** Root module name: file path (`./main.wesl`), module path (`package::main`), or bare name (`main`).
+   * For apps, the root module contains entry points (`@compute`, `@vertex`, `@fragment`).
+   * For libraries, it defines the public API. */
   rootModuleName?: string;
 
   /** For debug logging. Will be prepended to file paths. */
@@ -100,10 +88,20 @@ export type WeslProject = Pick<
   | "constants"
   | "libs"
   | "packageName"
->;
+> & {
+  /** Shader directory relative to project root (set by ?link from wesl.toml). */
+  shaderRoot?: string;
+};
+
+/** Context passed to virtual library generators. */
+export interface VirtualLibContext {
+  conditions: Conditions;
+  rootModulePath: string;
+  packageName: string;
+}
 
-/** Generate a virtual WESL module based on a set of conditions. */
-export type VirtualLibraryFn = (conditions: Conditions) => 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.
@@ -120,26 +118,20 @@ export async function link(params: LinkParams): Promise<LinkedWesl> {
 
 /** linker api for benchmarking */
 export function _linkSync(params: LinkParams): SrcMap {
-  const { weslSrc, libs = [], packageName, debugWeslRoot } = params;
-  const { resolver } = params;
-
-  const resolvers: ModuleResolver[] = [];
+  const { weslSrc, libs = [], packageName, debugWeslRoot, resolver } = params;
 
-  if (resolver) {
-    resolvers.push(resolver);
-  } else if (weslSrc) {
-    resolvers.push(new RecordResolver(weslSrc, { packageName, debugWeslRoot }));
-  } else {
+  if (!resolver && !weslSrc) {
     throw new Error("Either resolver or weslSrc must be provided");
   }
+  const primaryResolver =
+    resolver ?? new RecordResolver(weslSrc!, { packageName, debugWeslRoot });
 
-  if (libs.length > 0) {
-    const libResolvers = createLibraryResolvers(libs, debugWeslRoot);
-    resolvers.push(...libResolvers);
-  }
-
+  const libResolvers = createLibraryResolvers(libs, debugWeslRoot);
+  const allResolvers = [primaryResolver, ...libResolvers];
   const finalResolver =
-    resolvers.length === 1 ? resolvers[0] : new CompositeResolver(resolvers);
+    allResolvers.length === 1
+      ? allResolvers[0]
+      : new CompositeResolver(allResolvers);
 
   return linkRegistry({ ...params, resolver: finalResolver });
 }
@@ -194,17 +186,15 @@ export interface LinkRegistryParams
  */
 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 } = bound;
+  const builders = emitWgsl(
+    ast.moduleElem,
+    ast.srcModule,
+    newDecls,
+    newStatements,
+    params.conditions,
   );
+  return SrcMapBuilder.build(builders);
 }
 
 export interface BoundAndTransformed {
@@ -222,18 +212,16 @@ export function bindAndTransform(
 
   const modulePath = normalizeModuleName(rootModuleName);
   const rootAst = getRootModule(resolver, modulePath, rootModuleName);
-
   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 };
@@ -275,7 +263,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,25 +272,21 @@ function setupVirtualLibs(
   return libs && mapValues(libs, fn => ({ fn }));
 }
 
+/** Run registered transform plugins over the bound AST. */
 function applyTransformPlugins(
   rootModule: WeslAST,
   globalNames: Set<string>,
   config?: LinkConfig,
 ): TransformedAST {
-  const { moduleElem, srcModule } = rootModule;
-
   // for now only transform the root module
+  const { moduleElem, srcModule } = rootModule;
   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,
@@ -310,12 +294,11 @@ function emitWgsl(
   newStatements: EmittableElem[],
   conditions: Conditions = {},
 ): SrcMapBuilder[] {
-  const prologueBuilders = newStatements.map(s => emitStatement(s, conditions));
+  const prologueBuilders = newStatements.map(s =>
+    emitElem(s.srcModule, s.elem, conditions, { addNl: true }),
+  );
 
-  const rootBuilder = new SrcMapBuilder({
-    text: srcModule.src,
-    path: srcModule.debugFilePath,
-  });
+  const rootBuilder = builderFromModule(srcModule);
   lowerAndEmit({
     srcBuilder: rootBuilder,
     rootElems: [rootModuleElem],
@@ -323,37 +306,40 @@ function emitWgsl(
     extracting: false,
   });
 
-  const declBuilders = newDecls.map(decl => emitDecl(decl, conditions));
+  const declBuilders = newDecls.map(decl =>
+    emitElem(decl.srcModule, decl.declElem!, conditions, {
+      skipConditionalFiltering: true,
+    }),
+  );
 
   return [...prologueBuilders, rootBuilder, ...declBuilders];
 }
 
-function emitStatement(
-  s: EmittableElem,
+/** Emit a single element (prologue statement or imported declaration) into a SrcMapBuilder. */
+function emitElem(
+  srcModule: SrcModule,
+  elem: AbstractElem,
   conditions: Conditions,
+  opts: { addNl?: boolean; skipConditionalFiltering?: boolean } = {},
 ): SrcMapBuilder {
-  const { elem, srcModule } = s;
-  const { src: text, debugFilePath: path } = srcModule;
-  const builder = new SrcMapBuilder({ text, path });
-  lowerAndEmit({ srcBuilder: builder, rootElems: [elem], conditions });
-  builder.addNl();
-  return builder;
-}
-
-/** Skip conditional filtering because findValidRootDecls already validated these declarations */
-function emitDecl(decl: DeclIdent, conditions: Conditions): SrcMapBuilder {
-  const { src: text, debugFilePath: path } = decl.srcModule;
-  const builder = new SrcMapBuilder({ text, path });
+  const builder = builderFromModule(srcModule);
   lowerAndEmit({
     srcBuilder: builder,
-    rootElems: [decl.declElem!],
+    rootElems: [elem],
     conditions,
-    skipConditionalFiltering: true,
+    skipConditionalFiltering: opts.skipConditionalFiltering,
   });
+  if (opts.addNl) builder.addNl();
   return builder;
 }
 
-/* ---- Commentary on present and future features ---- */
+function builderFromModule(srcModule: SrcModule): SrcMapBuilder {
+  return new SrcMapBuilder({
+    text: srcModule.src,
+    path: srcModule.debugFilePath,
+  });
+}
+
 /*
 
 LATER

package/src/Mangler.ts

@@ -25,7 +25,7 @@ export type ManglerFn = (
 /**
  * Construct a globally unique name based on the declaration
  * module path separated by underscores.
- * Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/wgsl-tooling-wg/wesl-spec/blob/main/NameMangling.md)
+ * Corresponds to "Underscore-count mangling" from [NameMangling.md](https://github.com/webgpu-tools/wesl-spec/blob/main/NameMangling.md)
  */
 export function underscoreMangle(
   decl: DeclIdent,

package/src/StandardTypes.ts

@@ -1,5 +1,5 @@
 // From https://www.w3.org/TR/WGSL/#predeclared
-// Use https://github.com/wgsl-tooling-wg/wgsl-spec to regenerate these list in the future
+// Use https://github.com/webgpu-tools/wgsl-spec to regenerate these list in the future
 
 export const stdFns = `bitcast all any select arrayLength 
   abs acos acosh asin asinh atan atanh atan2 ceil clamp cos cosh 

package/src/WeslDevice.ts

@@ -89,6 +89,7 @@ export function makeWeslDevice(device: GPUDevice): WeslDevice {
                   lineNumber: message.lineNum,
                   lineColumn: message.linePos,
                   length: message.length,
+                  offset: message.offset,
                   error: new Error(message.type + ": " + message.message),
                 });
               }

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,

package/src/parse/Keywords.ts

@@ -1,4 +1,4 @@
-// Use https://github.com/wgsl-tooling-wg/wgsl-spec to check this list in the future
+// Use https://github.com/webgpu-tools/wgsl-spec to check this list in the future
 // I recommend checking whether a new list and the current list are equal
 
 /** https://www.w3.org/TR/WGSL/#keyword-summary */

package/src/parse/ParseStatement.ts

@@ -39,7 +39,7 @@ interface CompoundOptions {
 
 // Experimental: declarations in conditional blocks visible in outer scope.
 // e.g. @if(X) { let y = 1; } makes y visible outside the block.
-// see https://github.com/wgsl-tooling-wg/wesl-spec/issues/158
+// see https://github.com/webgpu-tools/wesl-spec/issues/158
 const conditionalBlockFeature = true;
 
 /** Function bodies share scope with parameters (per WGSL spec). */

package/src/test/BevyLink.test.ts

@@ -11,7 +11,7 @@ const bevyBulkTest = {
   name: "Bevy",
   baseDir: "bevy-wgsl",
   git: {
-    url: "https://github.com/wgsl-tooling-wg/bevy-wgsl.git",
+    url: "https://github.com/webgpu-tools/bevy-wgsl.git",
     revision: "84977ff025eaf8d92e56a9c35b815fae70eb4af0",
   },
 };