wesl 0.6.48 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { AppState, ParseError, Span, SrcMap, Stream, TypedToken } from "mini-parse";
-
 //#region src/LiveDeclarations.d.ts
 /** decls currently visible in this scope */
 interface LiveDecls {
@@ -19,50 +17,57 @@ interface FlatImport {
   modulePath: string[];
 }
 //#endregion
-//#region src/WESLCollect.d.ts
-type OpenElem<T extends ContainerElem = ContainerElem> = Pick<T, "kind" | "contents">;
+//#region src/Span.d.ts
+/** A range, from start (inclusive) to end (exclusive). */
+type Span = readonly [number, number];
+//#endregion
+//#region src/ParseError.d.ts
+declare class ParseError extends Error {
+  span: Span;
+  constructor(msg: string, span: Span);
+}
 //#endregion
 //#region src/ParseWESL.d.ts
-/** result of a parse for one wesl module (e.g. one .wesl file)
+/** Partial element being constructed during parsing. */
+type OpenElem<T extends ContainerElem = ContainerElem> = Pick<T, "kind" | "contents">;
+/**
+ * Result of parsing one WESL module (e.g., one .wesl file).
  *
- * The parser constructs the AST constructed into three sections
- * for convenient access by the binding stage.
+ * The AST is constructed into three sections for the binding stage:
  *  - import statements
  *  - language elements (fn, struct, etc)
  *  - scopes
- *
  */
 interface WeslAST {
-  /** source text for this module */
+  /** Source text for this module. */
   srcModule: SrcModule;
-  /** root module element */
+  /** Root module element. */
   moduleElem: ModuleElem;
-  /** root scope for this module */
+  /** Root scope for this module. */
   rootScope: Scope;
-  /** imports found in this module */
+  /** Imports found in this module. */
   imports: ImportStatement[];
-  /** module level const_assert statements */
+  /** Module level const_assert statements. */
   moduleAsserts?: ConstAssertElem[];
 }
-/** an extended version of the AST */
+/** Extended AST with cached flattened imports. */
 interface BindingAST extends WeslAST {
+  /** Flattened import statements (cached on demand). */
   _flatImports?: FlatImport[];
 }
-/** stable and unstable state used during parsing */
-interface WeslParseState extends AppState<WeslParseContext, StableState> {
+/** Stable and unstable state used during parsing. */
+interface WeslParseState {
   context: WeslParseContext;
   stable: StableState;
 }
-/** stable values used or accumulated during parsing */
+/** Stable values used or accumulated during parsing. */
 type StableState = WeslAST;
-/** unstable values used during parse collection */
+/** Unstable values used during parse collection. */
 interface WeslParseContext {
   scope: Scope;
   openElems: OpenElem[];
 }
-/**
- * An error when parsing WESL fails. Designed to be human-readable.
- */
+/** Human-readable error when parsing WESL fails. */
 declare class WeslParseError extends Error {
   span: Span;
   src: SrcModule;
@@ -71,11 +76,9 @@ declare class WeslParseError extends Error {
     src: SrcModule;
   });
 }
-/** Parse a WESL file. Throws on error. */
+/** Parse a WESL file. */
 declare function parseSrcModule(srcModule: SrcModule): WeslAST;
-declare function blankWeslParseState(srcModule: SrcModule): WeslParseState;
-declare function syntheticWeslParseState(): WeslParseState;
-/** @return a flattened form of the import tree for convenience in binding idents. */
+/** @return flattened form of import tree for binding idents. */
 declare function flatImports(ast: BindingAST, conditions?: Conditions): FlatImport[];
 //#endregion
 //#region src/Scope.d.ts
@@ -99,6 +102,8 @@ interface RefIdent extends IdentBase {
   kind: "ref";
   refersTo?: Ident;
   std?: true;
+  /** True for identifiers in @if/@elif conditions. Binding skips these (for now). */
+  conditionRef?: true;
   ast: WeslAST;
   refIdentElem: RefIdentElem;
 }
@@ -167,23 +172,36 @@ declare function childIdent(child: Scope | Ident): child is Ident;
 //#endregion
 //#region src/AbstractElems.d.ts
 /**
- * Structures to describe the 'interesting' parts of a WESL source file.
+ * AST structures describing 'interesting' parts of WESL source.
  *
- * The parts of the source that need to analyze further in the linker
- * are pulled out into these structures.
- *
- * The parts that are uninteresting the the linker are recorded
- * as 'TextElem' nodes, which are generally just copied to the output WGSL
- * along with their containing element.
+ * Parts needing further analysis are pulled into these structures.
+ * Uninteresting parts are 'TextElem' nodes, copied to output WGSL.
  */
-type AbstractElem = GrammarElem | SyntheticElem;
+type AbstractElem = GrammarElem | SyntheticElem | ExpressionElem;
 type GrammarElem = ContainerElem | TerminalElem;
-type ContainerElem = AttributeElem | AliasElem | ConstAssertElem | ConstElem | UnknownExpressionElem | SimpleMemberRef | FnElem | TypedDeclElem | GlobalVarElem | LetElem | ModuleElem | OverrideElem | FnParamElem | StructElem | StructMemberElem | StuffElem | TypeRefElem | VarElem | StatementElem | SwitchClauseElem;
+type ContainerElem = AttributeElem | AliasElem | ConstAssertElem | ConstElem | ContinuingElem | UnknownExpressionElem | SimpleMemberRef | FnElem | TypedDeclElem | GlobalVarElem | LetElem | ModuleElem | OverrideElem | FnParamElem | StructElem | StructMemberElem | StuffElem | TypeRefElem | VarElem | StatementElem | SwitchClauseElem;
+/** Map from element kind string to element type, for type-safe element construction. */
+type ElemKindMap = {
+  alias: AliasElem;
+  assert: ConstAssertElem;
+  const: ConstElem;
+  continuing: ContinuingElem;
+  gvar: GlobalVarElem;
+  let: LetElem;
+  member: StructMemberElem;
+  override: OverrideElem;
+  param: FnParamElem;
+  statement: StatementElem;
+  struct: StructElem;
+  "switch-clause": SwitchClauseElem;
+  type: TypeRefElem;
+  var: VarElem;
+};
 /** Inspired by https://github.com/wgsl-tooling-wg/wesl-rs/blob/3b2434eac1b2ebda9eb8bfb25f43d8600d819872/crates/wgsl-parse/src/syntax.rs#L364 */
-type ExpressionElem = Literal | TranslateTimeFeature | RefIdentElem | ParenthesizedExpression | ComponentExpression | ComponentMemberExpression | UnaryExpression | BinaryExpression | FunctionCallExpression;
+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;
-type DeclarationElem = GlobalDeclarationElem | FnParamElem | VarElem;
+type DeclarationElem = GlobalDeclarationElem | FnParamElem | VarElem | LetElem;
 type ElemWithAttributes = Extract<AbstractElem, HasAttributes>;
 interface AbstractElemBase {
   kind: AbstractElem["kind"];
@@ -196,22 +214,12 @@ interface ElemWithContentsBase extends AbstractElemBase {
 interface HasAttributes {
   attributes?: AttributeElem[];
 }
-/**
- * a raw bit of text in WESL source that's typically copied to the linked WGSL.
- * e.g. a keyword  like 'var'
- * or a phrase we needn't analyze further like '@diagnostic(off,derivative_uniformity)'
- */
+/** Raw text copied to linked WGSL (e.g., 'var' or '@diagnostic(off,derivative_uniformity)'). */
 interface TextElem extends AbstractElemBase {
   kind: "text";
   srcModule: SrcModule;
 }
-/** a name that doesn't need to be an Ident
- * e.g.
- * - a struct member name
- * - a diagnostic rule name
- * - an enable-extension name
- * - an interpolation sampling name
- */
+/** A name that doesn't need to be an Ident (e.g., struct member, diagnostic rule). */
 interface NameElem extends AbstractElemBase {
   kind: "name";
   name: string;
@@ -233,59 +241,47 @@ interface ImportElem extends AbstractElemBase, HasAttributes {
   kind: "import";
   imports: ImportStatement;
 }
-/**
- * An import statement, which is tree shaped.
- * `import foo::bar::{baz, cat as neko};
- */
+/** Tree-shaped import statement: `import foo::bar::{baz, cat as neko};` */
 interface ImportStatement {
   kind: "import-statement";
   segments: ImportSegment[];
   finalSegment: ImportCollection | ImportItem;
 }
-/**
- * A collection of import trees.
- * `{baz, cat as neko}`
- */
+/** A segment in an import path: `foo` in `foo::bar`. */
 interface ImportSegment {
   kind: "import-segment";
   name: string;
 }
-/**
- * A primitive segment in an import statement.
- * `foo`
- */
+/** A collection of import trees: `{baz, cat as neko}`. */
 interface ImportCollection {
   kind: "import-collection";
   subtrees: ImportStatement[];
 }
-/**
- * A renamed item at the end of an import statement.
- * `cat as neko`
- */
+/** A renamed item at the end of an import statement: `cat as neko`. */
 interface ImportItem {
   kind: "import-item";
   name: string;
   as?: string;
 }
-/** generated element, produced after parsing and binding */
+/** Generated element produced after parsing and binding. */
 interface SyntheticElem {
   kind: "synthetic";
   text: string;
 }
-/** a declaration identifer with a possible type */
+/** A declaration identifier with an optional type. */
 interface TypedDeclElem extends ElemWithContentsBase {
   kind: "typeDecl";
   decl: DeclIdentElem;
   typeRef?: TypeRefElem;
   typeScope?: Scope;
 }
-/** an alias statement */
+/** An alias statement. */
 interface AliasElem extends ElemWithContentsBase, HasAttributes {
   kind: "alias";
   name: DeclIdentElem;
   typeRef: TypeRefElem;
 }
-/** an attribute like '@compute' or '@binding(0)' */
+/** An attribute like '@compute' or '@binding(0)'. */
 interface AttributeElem extends ElemWithContentsBase {
   kind: "attribute";
   attribute: Attribute;
@@ -304,10 +300,11 @@ interface BuiltinAttribute {
   kind: "@builtin";
   param: NameElem;
 }
+type DiagnosticRule = [NameElem, NameElem | null];
 interface DiagnosticAttribute {
   kind: "@diagnostic";
   severity: NameElem;
-  rule: [NameElem, NameElem | null];
+  rule: DiagnosticRule;
 }
 interface IfAttribute {
   kind: "@if";
@@ -320,71 +317,66 @@ interface ElifAttribute {
 interface ElseAttribute {
   kind: "@else";
 }
-/** a const_assert statement */
+type ConditionalAttribute = IfAttribute | ElifAttribute | ElseAttribute;
+/** A const_assert statement. */
 interface ConstAssertElem extends ElemWithContentsBase, HasAttributes {
   kind: "assert";
 }
-/** a const declaration */
+/** A const declaration. */
 interface ConstElem extends ElemWithContentsBase, HasAttributes {
   kind: "const";
   name: TypedDeclElem;
 }
-/** an expression w/o special handling, used inside attribute parameters */
+/** An expression without special handling, used in attribute parameters. */
 interface UnknownExpressionElem extends ElemWithContentsBase {
   kind: "expression";
 }
-/** an expression that can be safely evaluated at compile time */
+/** An expression that can be safely evaluated at compile time. */
 interface TranslateTimeExpressionElem {
   kind: "translate-time-expression";
   expression: ExpressionElem;
   span: Span;
 }
-/** A literal value in WESL source. A boolean or a number. */
-interface Literal {
+/** A literal value (boolean or number) in WESL source. */
+interface Literal extends AbstractElemBase {
   kind: "literal";
   value: string;
-  span: Span;
-}
-/** `words`s inside `@if` */
-interface TranslateTimeFeature {
-  kind: "translate-time-feature";
-  name: string;
-  span: Span;
 }
 /** (expr) */
-interface ParenthesizedExpression {
+interface ParenthesizedExpression extends AbstractElemBase {
   kind: "parenthesized-expression";
   expression: ExpressionElem;
 }
 /** `foo[expr]` */
-interface ComponentExpression {
+interface ComponentExpression extends AbstractElemBase {
   kind: "component-expression";
   base: ExpressionElem;
   access: ExpressionElem;
 }
 /** `foo.member` */
-interface ComponentMemberExpression {
+interface ComponentMemberExpression extends AbstractElemBase {
   kind: "component-member-expression";
   base: ExpressionElem;
   access: NameElem;
 }
 /** `+foo` */
-interface UnaryExpression {
+interface UnaryExpression extends AbstractElemBase {
   kind: "unary-expression";
   operator: UnaryOperator;
   expression: ExpressionElem;
 }
 /** `foo + bar` */
-interface BinaryExpression {
+interface BinaryExpression extends AbstractElemBase {
   kind: "binary-expression";
   operator: BinaryOperator;
   left: ExpressionElem;
   right: ExpressionElem;
 }
-/** `foo(arg, arg)` */
-interface FunctionCallExpression {
+/** `foo<T>(arg, arg)` */
+interface FunctionCallExpression extends AbstractElemBase {
   kind: "call-expression";
-  function: RefIdentElem;
+  function: RefIdentElem | TypeRefElem;
+  templateArgs?: TypeTemplateParameter[];
   arguments: ExpressionElem[];
 }
 interface UnaryOperator {
@@ -413,7 +405,7 @@ interface RequiresDirective {
   kind: "requires";
   extensions: NameElem[];
 }
-/** a function declaration */
+/** A function declaration. */
 interface FnElem extends ElemWithContentsBase, HasAttributes {
   kind: "fn";
   name: DeclIdentElem;
@@ -422,64 +414,63 @@ interface FnElem extends ElemWithContentsBase, HasAttributes {
   returnAttributes?: AttributeElem[];
   returnType?: TypeRefElem;
 }
-/** a global variable declaration (at the root level) */
+/** A global variable declaration (at the root level). */
 interface GlobalVarElem extends ElemWithContentsBase, HasAttributes {
   kind: "gvar";
   name: TypedDeclElem;
 }
-/** an entire file */
+/** An entire file. */
 interface ModuleElem extends ElemWithContentsBase {
   kind: "module";
 }
-/** an override declaration */
+/** An override declaration. */
 interface OverrideElem extends ElemWithContentsBase, HasAttributes {
   kind: "override";
   name: TypedDeclElem;
 }
-/** a parameter in a function declaration */
+/** A parameter in a function declaration. */
 interface FnParamElem extends ElemWithContentsBase, HasAttributes {
   kind: "param";
   name: TypedDeclElem;
 }
-/** simple references to structures, like myStruct.bar
- * (used for transforming refs to binding structs) */
+/** Simple struct references like `myStruct.bar` (for binding struct transforms). */
 interface SimpleMemberRef extends ElemWithContentsBase {
   kind: "memberRef";
   name: RefIdentElem;
   member: NameElem;
   extraComponents?: StuffElem;
 }
-/** a struct declaration */
+/** A struct declaration. */
 interface StructElem extends ElemWithContentsBase, HasAttributes {
   kind: "struct";
   name: DeclIdentElem;
   members: StructMemberElem[];
   bindingStruct?: true;
 }
-/** generic container of other elements */
+/** Generic container of other elements. */
 interface StuffElem extends ElemWithContentsBase {
   kind: "stuff";
 }
-/** a struct declaration that's been marked as a bindingStruct */
+/** A struct declaration marked as a binding struct. */
 interface BindingStructElem extends StructElem {
   bindingStruct: true;
   entryFn?: FnElem;
 }
-/** a member of a struct declaration */
+/** A member of a struct declaration. */
 interface StructMemberElem extends ElemWithContentsBase, HasAttributes {
   kind: "member";
   name: NameElem;
   typeRef: TypeRefElem;
   mangledVarName?: string;
 }
-type TypeTemplateParameter = TypeRefElem | UnknownExpressionElem;
-/** a reference to a type, like 'f32', or 'MyStruct', or 'ptr<storage, array<f32>, read_only>'   */
+type TypeTemplateParameter = ExpressionElem;
+/** A type reference like 'f32', 'MyStruct', or 'ptr<storage, array<f32>, read_only>'. */
 interface TypeRefElem extends ElemWithContentsBase {
   kind: "type";
   name: RefIdent;
   templateParams?: TypeTemplateParameter[];
 }
-/** a variable declaration */
+/** A variable declaration. */
 interface VarElem extends ElemWithContentsBase, HasAttributes {
   kind: "var";
   name: TypedDeclElem;
@@ -491,10 +482,76 @@ interface LetElem extends ElemWithContentsBase, HasAttributes {
 interface StatementElem extends ElemWithContentsBase, HasAttributes {
   kind: "statement";
 }
+interface ContinuingElem extends ElemWithContentsBase, HasAttributes {
+  kind: "continuing";
+}
+/** Statement or continuing - used in loop body parsing. */
+type BlockStatement = StatementElem | ContinuingElem;
 interface SwitchClauseElem extends ElemWithContentsBase, HasAttributes {
   kind: "switch-clause";
 }
 //#endregion
+//#region src/SrcMap.d.ts
+/** A source map file, and a path for debug purposes. */
+interface SrcWithPath {
+  /** User friendly path */
+  path?: string;
+  text: string;
+}
+interface SrcMapEntry {
+  src: SrcWithPath;
+  srcStart: number;
+  srcEnd: number;
+  destStart: number;
+  destEnd: number;
+}
+interface SrcPosition {
+  src: SrcWithPath;
+  position: number;
+}
+/** map text ranges in multiple src texts to a single dest text */
+declare class SrcMap {
+  entries: SrcMapEntry[];
+  dest: SrcWithPath;
+  constructor(dest: SrcWithPath, entries?: SrcMapEntry[]);
+  /** add a new mapping from src to dest ranges (must be non-overlapping in destination) */
+  addEntries(newEntries: SrcMapEntry[]): void;
+  /** given positions in the dest string, return corresponding positions in the src strings */
+  mapPositions(...positions: number[]): SrcPosition[];
+  /** internally compress adjacent entries where possible */
+  compact(): void;
+  /** sort in destination order */
+  sort(): void;
+  /**
+   * This SrcMap's destination is a src for the other srcmap,
+   * so combine the two and return the result.
+   */
+  merge(other: SrcMap): SrcMap;
+  /** @return the source position corresponding to a provided destination position */
+  destToSrc(destPos: number): SrcPosition;
+}
+/** Incrementally append to a string, tracking source references */
+declare class SrcMapBuilder {
+  #private;
+  source: SrcWithPath;
+  constructor(source: SrcWithPath);
+  /** append a string fragment to the destination string */
+  add(fragment: string, srcStart: number, srcEnd: number): void;
+  /**
+   * Append a fragment to the destination string,
+   * mapping source to the previous,
+   * and guessing that the source fragment is just as long as the dest fragment.
+   */
+  appendNext(fragment: string): void;
+  addSynthetic(fragment: string, syntheticSource: string, srcStart: number, srcEnd: number): void;
+  /** append a synthetic newline, mapped to previous source location */
+  addNl(): void;
+  /** copy a string fragment from the src to the destination string */
+  addCopy(srcStart: number, srcEnd: number): void;
+  /** return a SrcMap */
+  static build(builders: SrcMapBuilder[]): SrcMap;
+}
+//#endregion
 //#region src/WeslDevice.d.ts
 /**
  * A {@link GPUDevice} with extensions for WESL. Created with {@link makeWeslDevice}.
@@ -629,26 +686,14 @@ interface WeslBundle {
 }
 //#endregion
 //#region src/ModuleResolver.d.ts
-/**
- * Resolves module paths to parsed ASTs.
- *
- * Implementations may cache ASTs or load them lazily.
- */
+/** Resolves module paths to parsed ASTs. Implementations may cache or load lazily. */
 interface ModuleResolver {
-  /**
-   * Resolve a module path to its parsed AST.
-   *
-   * @param modulePath - Module path in :: format (e.g., "package::foo::bar")
-   * @returns Parsed AST or undefined if module not found
-   */
+  /** Resolve module path (e.g., "package::foo::bar") to AST, or undefined if not found. */
   resolveModule(modulePath: string): WeslAST | undefined;
 }
 /** Module resolver that supports batch enumeration of all modules. */
 interface BatchModuleResolver extends ModuleResolver {
-  /**
-   * Return all modules, parsing them on-demand if needed.
-   * Implementations should ensure all sources are parsed before returning.
-   */
+  /** Return all modules, parsing them on-demand if needed. */
   allModules(): Iterable<[string, WeslAST]>;
 }
 interface RecordResolverOptions {
@@ -666,9 +711,10 @@ declare class RecordResolver implements BatchModuleResolver {
   constructor(sources: Record<string, string>, options?: RecordResolverOptions);
   resolveModule(modulePath: string): WeslAST | undefined;
   private findSource;
+  /** Convert module path to file path, or undefined if not local. */
   private moduleToFilePath;
   private modulePathToDebugPath;
-  /** Return all modules, parsing them on-demand if needed. */
+  /** Parse all modules and return entries. */
   allModules(): Iterable<[string, WeslAST]>;
 }
 /** Composite resolver that tries each resolver in order until one succeeds. */
@@ -689,6 +735,8 @@ declare class BundleResolver implements ModuleResolver {
   private moduleToFilePath;
   private modulePathToDebugPath;
 }
+/** Convert file path to module path (e.g., "foo/bar.wesl" to "package::foo::bar"). */
+declare function fileToModulePath(filePath: string, packageName: string, treatLibAsRoot: boolean): string;
 //#endregion
 //#region src/Linker.d.ts
 type LinkerTransform = (boundAST: TransformedAST) => TransformedAST;
@@ -784,132 +832,87 @@ declare function normalizeModuleName(name: string): string;
 //#endregion
 //#region src/BindIdents.d.ts
 /**
-  BindIdents pass
-
-  Goals:
-  - link references identifiers to their declaration identifiers.
-  - produce a list of declarations that are used (and need to be emitted in the link)
-  - create mangled names for global declarations (to avoid name conflicts)
-
-  BindIdents proceeds as a recursive tree walk of the scope tree, starting from the root module (e.g. main.wesl).
-  It traverses the scope tree depth first (and not the syntax tree).
-  - For each ref ident, search prior declarations in the current scope, then
-    up the scope tree to find a matching declaration
-  - If no local match is found, check for partial matches with import statements
-    - combine the ident with import statement to match a decl in an exporting module
-  - As global declaration identifies are found, also:
-     - mutate their mangled name to be globally unique.
-     - collect the declarations (they will be emitted)
-
-  When iterating through the idents inside a scope, we maintain a parallel data structure of
-  'liveDecls', the declarations that are visible in the current scope at the currently
-  processed ident, along with a link to parent liveDecls for their current decl visibility.
-
-  @if/@else Handling:
-  The binding phase respects conditional compilation by tracking @else validity state as it
-  processes sibling scopes. This prevents references from within filtered @else blocks from
-  pulling in declarations that won't be emitted. The algorithm mirrors the emission phase's
-  filterValidElements approach but operates on scopes rather than elements.
-*/
-/** results returned from binding pass */
+ * 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
+ *
+ * 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.
+ */
+/** Results returned from binding pass. */
 interface BindResults {
-  /** root level names (including names mangled due to conflict with earlier names) */
+  /** Root level names (including mangled names from conflicts). */
   globalNames: Set<string>;
-  /** global declarations that were referenced (these will need to be emitted in the link) */
+  /** Global declarations referenced (to emit in link). */
   decls: DeclIdent[];
-  /** additional global statements to include in linked results
-   * (e.g. for adding module level const_assert statements) */
+  /** Additional global statements to emit (e.g., const_assert). */
   newStatements: EmittableElem[];
-  /** if accumulateUnbound is true, collection of unbound module paths */
+  /** Unbound module paths (only if accumulateUnbound is true). */
   unbound?: string[][];
 }
-/** an element that can be directly emitted into the linked result */
+/** An element that can be directly emitted into the linked result. */
 interface EmittableElem {
   srcModule: SrcModule;
   elem: AbstractElem;
 }
-/** virtual package, generated by code generation function. */
+/** Virtual package generated by code generation function. */
 interface VirtualLibrary {
-  /** function to generate the module */
+  /** Function to generate the module. */
   fn: VirtualLibraryFn;
-  /** parsed AST for the module (constructed lazily) */
+  /** Parsed AST for the module (constructed lazily). */
   ast?: WeslAST;
 }
-/** key is virtual module name */
+/** Key is virtual module name. */
 type VirtualLibrarySet = Record<string, VirtualLibrary>;
 interface BindIdentsParams extends Pick<LinkRegistryParams, "resolver" | "conditions" | "mangler"> {
   rootAst: WeslAST;
   virtuals?: VirtualLibrarySet;
-  /** if false, throw on unbound identifiers. If true, accumulate unbound identifiers into
-   * a BindResults.unbound.  */
+  /** If true, accumulate unbound identifiers into BindResults.unbound instead of throwing. */
   accumulateUnbound?: true;
 }
-/**
- * Bind active reference idents to declaration Idents by mutating the refersTo: field
- * Also in this pass, set the mangledName: field for all active global declaration idents.
- *
- * @param parsed
- * @param conditions  only bind to/from idents that are valid with the current condition set
- * @return any new declaration elements found (they will need to be emitted)
- */
+/** Bind ref idents to declarations and mangle global declaration names. */
 declare function bindIdents(params: BindIdentsParams): BindResults;
-/**
- * Find all conditionally valid declarations at the root level.
- * Declarations are either directly in the root scope or in conditionally valid partial scopes.
- *
- * This function tracks @else state to ensure that declarations in @else blocks are only
- * included when the corresponding @if block is invalid. This is essential for preventing
- * unused declarations from being included in the output.
- *
- * Results are cached on the root scope's _validRootDecls field.
- * Used both for binding and for publicDecl() lookups.
- *
- * @param rootScope The root scope to search
- * @param conditions Current conditional compilation settings
- * @return Array of valid declaration identifiers
- */
+/** Find all conditionally valid declarations at the root level. */
 declare function findValidRootDecls(rootScope: Scope, conditions: Conditions): DeclIdent[];
-/** Find a public declaration with the given original name */
+/** Find a public declaration with the given original name. */
 declare function publicDecl(scope: Scope, name: string, conditions: Conditions): DeclIdent | undefined;
-/** @return true if this decl is at the root scope level of a module */
-declare function isGlobal(declIdent: DeclIdent): boolean;
-/** state used during the recursive scope tree walk to bind references to declarations */
+/** State used during the recursive scope tree walk to bind references to declarations. */
 interface BindContext {
   resolver: ModuleResolver;
-  conditions: Record<string, any>;
-  /** decl idents discovered so far (to avoid re-traversing) */
+  conditions: Conditions;
+  /** Decl idents discovered so far (to avoid re-traversing). */
   knownDecls: Set<DeclIdent>;
-  /** save work by not processing scopes multiple times */
+  /** Scopes already processed (avoid duplicate work). */
   foundScopes: Set<Scope>;
-  /** root level names used so far (enables manglers/plugins to pick unique names) */
+  /** Root level names used so far (enables manglers to pick unique names). */
   globalNames: Set<string>;
-  /** additional global statements to emit (e.g. module level const_assert, indexed by elem for uniqueness) */
+  /** Additional global statements to emit (indexed by elem for uniqueness). */
   globalStatements: Map<AbstractElem, EmittableElem>;
-  /** construct unique identifer names for global declarations */
+  /** Construct unique identifier names for global declarations. */
   mangler: ManglerFn;
   virtuals?: VirtualLibrarySet;
-  /** list of unbound identifiers if accumulateUnbound is true */
+  /** Unbound identifiers if accumulateUnbound is true. */
   unbound?: string[][];
-  /** don't follow references from declarations (used for library dependency detection) */
+  /** Don't follow references from declarations (for library dependency detection). */
   dontFollowDecls?: boolean;
 }
 /**
- * Recursively bind references to declarations in this scope and
- * any child scopes referenced by these declarations.
- * Uses a hash set of found declarations to avoid duplication.
- *
- * IMPORTANT: This function tracks @else state while traversing sibling scopes.
- * When an @if scope is processed, its validity determines whether the following
- * @else scope should be considered valid. This ensures that references from
- * filtered @else blocks don't pull in unused declarations.
- *
- * @return any new declarations found
- * @param liveDecls current set of live declaration in this scope
- *  (empty when traversing to a new scope, possibly non-empty for a partial scope)
- * @param isRoot liveDecls refers to a prepopulated root scope
- *  (root scope declarations may appear in any order)
+ * 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
  */
-declare function bindIdentsRecursive(scope: Scope, bindContext: BindContext, liveDecls: LiveDecls, isRoot?: boolean): DeclIdent[];
+declare function bindIdentsRecursive(scope: Scope, bindContext: BindContext, liveDecls: LiveDecls): DeclIdent[];
 //#endregion
 //#region src/debug/ASTtoString.d.ts
 declare function astToString(elem: AbstractElem, indent?: number): string;
@@ -980,6 +983,47 @@ declare function sanitizePackageName(npmName: string): string;
  */
 declare function npmNameVariations(sanitizedPath: string): Generator<string>;
 //#endregion
+//#region src/Logging.d.ts
+/** base logger (can be overridden to a capturing logger for tests) */
+declare let log: (...data: any[]) => void;
+/** enable debug assertions and verbose error messages (set false via bundler for smaller builds) */
+declare const debug = true;
+/** enable user-facing validation like operator binding rules (set false via bundler for smaller builds) */
+declare const validation = true;
+/** use temporary logger for async tests */
+declare function withLoggerAsync<T>(logFn: typeof console.log, fn: () => Promise<T>): Promise<T>;
+/**
+ * Log a message along with the source line and a caret indicating the error position.
+ * @param pos is the position in the source string, or if src is a SrcMap,
+ *   then pos is the position in the dest (e.g. preprocessed) text
+ */
+declare function srcLog(src: string | SrcMap, pos: number | [number, number], ...msgs: any[]): void;
+//#endregion
+//#region src/ModulePathUtil.d.ts
+/** WESL module path utilities for converting between :: and / separators. */
+/**
+ * Convert module path segments to relative file path.
+ * Handles package/packageName prefixes and super:: resolution.
+ *
+ * @param parts - module path as array e.g., ["package", "utils", "helper"]
+ * @param packageName - the current package's name (required)
+ * @param srcModuleParts - source module path for super:: resolution (optional)
+ * @returns relative file path e.g., "utils/helper", or undefined if external
+ */
+declare function modulePartsToRelativePath(parts: string[], packageName: string, srcModuleParts?: string[]): string | undefined;
+/** String variant of modulePartsToRelativePath. */
+declare function moduleToRelativePath(modulePath: string, packageName: string, srcModulePath?: string): string | undefined;
+/**
+ * Resolve super:: elements to absolute module path.
+ *
+ * @param parts - module path with potential super:: elements
+ * @param srcModuleParts - source module path for context
+ * @returns absolute module path parts (no super:: elements)
+ */
+declare function resolveSuper(parts: string[], srcModuleParts: string[]): string[];
+/** Normalize debug root to end with / or be empty. */
+declare function normalizeDebugRoot(root?: string): string;
+//#endregion
 //#region src/PathUtil.d.ts
 /** simplistic path manipulation utilities */
 /** return path with ./ and foo/.. elements removed */
@@ -988,6 +1032,34 @@ declare function normalize(path: string): string;
  * e.g. /foo/bar.wgsl => /foo/bar */
 declare function noSuffix(path: string): string;
 //#endregion
+//#region src/Stream.d.ts
+/**
+ * Interface for a tokenizer. Returns a "next token", and can be reset to
+ * previously saved positions (checkpoints).
+ */
+interface Stream<T extends Token> {
+  /** Returns the current position */
+  checkpoint(): number;
+  /** Restores a position */
+  reset(position: number): void;
+  /**
+   * Returns the next token, or `null` if the end of the stream has been reached.
+   * Always leaves `checkpoint` right after the token.
+   */
+  nextToken(): T | null;
+  /** src text */
+  src: string;
+}
+/** A text token */
+interface Token {
+  kind: string;
+  text: string;
+  span: Span;
+}
+interface TypedToken<Kind extends string> extends Token {
+  kind: Kind;
+}
+//#endregion
 //#region src/parse/WeslStream.d.ts
 type WeslTokenKind = "word" | "keyword" | "number" | "symbol";
 type WeslToken<Kind extends WeslTokenKind = WeslTokenKind> = TypedToken<Kind>;
@@ -996,13 +1068,22 @@ declare class WeslStream implements Stream<WeslToken> {
   private stream;
   /** New line */
   private eolPattern;
-  /** Block comments */
   private blockCommentPattern;
   src: string;
   constructor(src: string);
   checkpoint(): number;
   reset(position: number): void;
   nextToken(): WeslToken | null;
+  /** Peek at the next token without consuming it */
+  peek(): WeslToken | null;
+  /** Consume token if text matches, otherwise leave position unchanged */
+  matchText(text: string): WeslToken | null;
+  /** Consume token if kind matches (and optionally text), otherwise leave position unchanged */
+  matchKind<K extends WeslTokenKind>(kind: K, text?: string): WeslToken<K> | null;
+  /** Consume token if predicate matches, otherwise leave position unchanged */
+  nextIf(predicate: (token: WeslToken) => boolean): WeslToken | null;
+  /** Match a sequence of tokens by text. Resets and returns null if any fails. */
+  matchSequence(...texts: string[]): WeslToken[] | null;
   private skipToEol;
   private skipBlockComment;
   /**
@@ -1016,12 +1097,12 @@ declare class WeslStream implements Stream<WeslToken> {
   nextTemplateEndToken(): (WeslToken & {
     kind: "symbol";
   }) | null;
-  isTemplateStart(afterToken: number): boolean;
+  private isTemplateStart;
   /**
    * Call this after consuming an opening bracket.
    * Skips until a closing bracket. This also consumes the closing bracket.
    */
-  skipBracketsTo(closingBracket: string): void;
+  private skipBracketsTo;
 }
 //#endregion
 //#region src/TransformBindingStructs.d.ts
@@ -1119,4 +1200,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, BoundAndTransformed, BuiltinAttribute, BundleResolver, ComponentExpression, ComponentMemberExpression, CompositeResolver, Conditions, ConstAssertElem, ConstElem, ContainerElem, DeclIdent, DeclIdentElem, DeclarationElem, DiagnosticAttribute, DiagnosticDirective, DirectiveElem, DirectiveVariant, 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, OverrideElem, ParenthesizedExpression, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, SimpleMemberRef, SrcModule, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TransformedAST, TranslateTimeExpressionElem, TranslateTimeFeature, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnknownExpressionElem, VarElem, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslStream, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, bindingStructsPlugin, blankWeslParseState, childIdent, childScope, containsScope, debugContentsToString, emptyScope, errorHighlight, filterMap, findMap, findRefsToBindingStructs, findUnboundIdents, findValidRootDecls, flatImports, groupBy, grouped, identToString, isGlobal, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, multiKeySet, nextIdentId, noSuffix, normalize, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, sanitizePackageName, scan, scopeToString, scopeToStringLong, syntheticWeslParseState, transformBindingReference, transformBindingStruct, underscoreMangle };
+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, PartialScope, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, Scope, SimpleMemberRef, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, StatementElem, StructElem, StructMemberElem, StuffElem, SwitchClauseElem, SyntheticElem, TerminalElem, TextElem, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, 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, emptyScope, errorHighlight, fileToModulePath, filterMap, findMap, findRefsToBindingStructs, findUnboundIdents, findValidRootDecls, flatImports, groupBy, grouped, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, lowerBindingStructs, makeLiveDecls, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, modulePartsToRelativePath, moduleToRelativePath, multiKeySet, nextIdentId, noSuffix, normalize, normalizeDebugRoot, normalizeModuleName, npmNameVariations, offsetToLineNumber, overlapTail, parseSrcModule, partition, publicDecl, replaceWords, requestWeslDevice, resetScopeIds, resolveSuper, sanitizePackageName, scan, scopeToString, scopeToStringLong, srcLog, transformBindingReference, transformBindingStruct, underscoreMangle, validation, withLoggerAsync };