wesl 0.7.27 → 0.7.28

package/dist/index.d.ts

@@ -58,17 +58,42 @@ interface TypedToken<Kind extends string> extends Token {
 //#region src/parse/WeslStream.d.ts
 type WeslTokenKind = "word" | "keyword" | "number" | "symbol";
 type WeslToken<Kind extends WeslTokenKind = WeslTokenKind> = TypedToken<Kind>;
+/** A comment skipped by the tokenizer, recorded as leading trivia of the next token.
+ *  Line-break flags (newline/blank before) are not stored here: they are derived
+ *  on demand during comment attachment, so the tokenizer hot path never counts
+ *  line breaks. */
+interface CommentTrivia {
+  style: "line" | "block";
+  /** Source range of the comment text (excluding the trailing newline of a line comment). */
+  start: number;
+  end: number;
+}
 /** A stream that produces WESL tokens, skipping over comments and white space */
 declare class WeslStream implements Stream<WeslToken> {
   private stream;
-  /** New line */
+  /** New line (stateful: scanned via lastIndex, so kept per-instance). */
   private eolPattern;
   private blockCommentPattern;
+  /** Comments skipped before a real token, keyed by that token's start position. */
+  private triviaByPos;
+  /** Last peeked token, so the following nextToken() skips the rescan.
+   *  Never invalidated: tokenization is deterministic per position. */
+  private peeked;
   src: string;
   constructor(src: string);
   checkpoint(): number;
   reset(position: number): void;
+  /** All recorded comment runs (each a contiguous group of comments between two
+   *  real tokens), in source order. Consumed by the post-parse comment pass. */
+  commentRuns(): CommentTrivia[][];
+  private recordTrivia;
+  /** Next real token (comments/blankspace skipped and recorded as trivia); null at EOF. */
   nextToken(): WeslToken | null;
+  /** If the last peek() was at the current position, consume and return it. */
+  private usePeeked;
+  /** Skip a comment (rejecting embedded \0), advance the stream past it,
+   *  and return it as trivia. */
+  private consumeComment;
   /** Peek at the next token without consuming it */
   peek(): WeslToken | null;
   /** Consume token if text matches, otherwise leave position unchanged */
@@ -79,7 +104,10 @@ declare class WeslStream implements Stream<WeslToken> {
   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;
+  /** End position of a comment opened by a commentStart token. */
+  private commentEnd;
+  /** End of a line comment: the start of the next line break (or end of file). */
+  private lineCommentEnd;
   private skipBlockComment;
   /**
    * Only matches the `<` token if it is a template
@@ -89,9 +117,14 @@ declare class WeslStream implements Stream<WeslToken> {
   nextTemplateStartToken(): (WeslToken & {
     kind: "symbol";
   }) | null;
+  /** Match a template-closing `>`, splitting it off a `>>`/`>=`/`>>=` token when needed. */
   nextTemplateEndToken(): (WeslToken & {
     kind: "symbol";
   }) | null;
+  /** Next symbol from the raw stream, skipping comment bodies (so symbols
+   *  inside comments don't count) and non-symbol tokens; null at EOF. */
+  private nextRawSymbol;
+  /** Template-list discovery: scan forward from `<` for a balanced closing `>`. */
   private isTemplateStart;
   /**
    * Call this after consuming an opening bracket.
@@ -101,14 +134,17 @@ declare class WeslStream implements Stream<WeslToken> {
 }
 //#endregion
 //#region src/parse/ParsingContext.d.ts
+/** Opt-in toggles for not-yet-spec'd WESL/WGSL features (for prototyping). */
+interface WeslExtensions {
+  /** Parse `do name(...) { ... }` blocks. */
+  doBlocks?: boolean;
+}
 interface ParseOptions {
-  /** Store expression AST nodes in statement contents (for tooling/validation). */
-  preserveExpressions?: boolean;
+  /** Enable parsing of experimental, not-yet-spec'd syntax extensions. */
+  weslExtensions?: WeslExtensions;
 }
 //#endregion
 //#region src/ParseWESL.d.ts
-/** 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).
  *
@@ -128,6 +164,8 @@ interface WeslAST {
   imports: ImportStatement[];
   /** Module level const_assert statements. */
   moduleAsserts?: ConstAssertElem[];
+  /** Parse options used to produce this AST (so re-parsing preserves them). */
+  parseOptions?: ParseOptions;
 }
 /** Extended AST with cached flattened imports. */
 interface BindingAST extends WeslAST {
@@ -144,7 +182,6 @@ type StableState = WeslAST;
 /** Unstable values used during parse collection. */
 interface WeslParseContext {
   scope: Scope;
-  openElems: OpenElem[];
 }
 /** Human-readable error when parsing WESL fails. */
 declare class WeslParseError extends Error {
@@ -254,26 +291,38 @@ declare function childIdent(child: Scope | Ident): child is Ident;
 //#endregion
 //#region src/AbstractElems.d.ts
 /**
- * AST structures describing 'interesting' parts of WESL source.
- *
- * Parts needing further analysis are pulled into these structures.
- * Uninteresting parts are 'TextElem' nodes, copied to output WGSL.
+ * AST structures describing WESL source. Each element holds its interesting
+ * parts as typed child fields (name, type, init, body, ...); emit walks those
+ * fields and reconstructs the surrounding WGSL syntax rather than copying spans.
  */
-type AbstractElem = GrammarElem | SyntheticElem | ExpressionElem;
-type GrammarElem = ContainerElem | TerminalElem;
-type ContainerElem = AttributeElem | AliasElem | ConstAssertElem | ConstElem | ContinuingElem | UnknownExpressionElem | SimpleMemberRef | FnElem | TypedDeclElem | GlobalVarElem | LetElem | ModuleElem | OverrideElem | FnParamElem | StructElem | StructMemberElem | StuffElem | TypeRefElem | VarElem | StatementElem | SwitchClauseElem;
+type AbstractElem = GrammarElem | SyntheticElem | ExpressionElem | UnknownExpressionElem;
+type GrammarElem = ModuleElem | AttributeElem | Statement | SwitchClauseElem | AliasElem | GlobalVarElem | OverrideElem | StructElem | StructMemberElem | FnElem | FnParamElem | TypedDeclElem | TerminalElem | DoBlockElem;
 /** Map from element kind string to element type, for type-safe element construction. */
 type ElemKindMap = {
   alias: AliasElem;
   assert: ConstAssertElem;
+  block: BlockElem;
   const: ConstElem;
   continuing: ContinuingElem;
+  if: IfElem;
+  for: ForElem;
+  while: WhileElem;
+  loop: LoopElem;
+  switch: SwitchElem;
+  return: ReturnElem;
+  break: BreakElem;
+  continue: ContinueElem;
+  discard: DiscardElem;
+  assign: AssignElem;
+  increment: IncrementElem;
+  decrement: DecrementElem;
+  call: CallElem;
+  empty: EmptyElem;
   gvar: GlobalVarElem;
   let: LetElem;
   member: StructMemberElem;
   override: OverrideElem;
   param: FnParamElem;
-  statement: StatementElem;
   struct: StructElem;
   "switch-clause": SwitchClauseElem;
   type: TypeRefElem;
@@ -281,26 +330,36 @@ type ElemKindMap = {
 };
 /** 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;
+type TerminalElem = DirectiveElem | DeclIdentElem | NameElem | RefIdentElem | ImportElem;
+type GlobalDeclarationElem = AliasElem | ConstElem | DoBlockElem | FnElem | GlobalVarElem | OverrideElem | StructElem;
 type DeclarationElem = GlobalDeclarationElem | FnParamElem | VarElem | LetElem;
 type ElemWithAttributes = Extract<AbstractElem, HasAttributes>;
 interface AbstractElemBase {
   kind: AbstractElem["kind"];
   start: number;
   end: number;
+  /** Comments leading this element (on their own line above it). */
+  commentsBefore?: CommentElem[];
+  /** Comments trailing this element (on the same line after it). */
+  commentsAfter?: CommentElem[];
 }
-interface ElemWithContentsBase extends AbstractElemBase {
-  contents: AbstractElem[];
+/**
+ * A source comment attached to an element as leading or trailing trivia.
+ * Not part of the {@link AbstractElem} union: comments are node metadata
+ * (in `commentsBefore` / `commentsAfter`), never `contents` children.
+ */
+interface CommentElem {
+  kind: "comment";
+  style: "line" | "block";
+  start: number;
+  end: number;
+  srcModule: SrcModule;
+  /** Preserve one blank line above this comment (leading comments only). */
+  blankBefore?: boolean;
 }
 interface HasAttributes {
   attributes?: AttributeElem[];
 }
-/** 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., struct member, diagnostic rule). */
 interface NameElem extends AbstractElemBase {
   kind: "name";
@@ -351,20 +410,20 @@ interface SyntheticElem {
   text: string;
 }
 /** A declaration identifier with an optional type. */
-interface TypedDeclElem extends ElemWithContentsBase {
+interface TypedDeclElem extends AbstractElemBase {
   kind: "typeDecl";
   decl: DeclIdentElem;
   typeRef?: TypeRefElem;
   typeScope?: Scope;
 }
 /** An alias statement. */
-interface AliasElem extends ElemWithContentsBase, HasAttributes {
+interface AliasElem extends AbstractElemBase, HasAttributes {
   kind: "alias";
   name: DeclIdentElem;
   typeRef: TypeRefElem;
 }
 /** An attribute like '@compute' or '@binding(0)'. */
-interface AttributeElem extends ElemWithContentsBase {
+interface AttributeElem extends AbstractElemBase {
   kind: "attribute";
   attribute: Attribute;
 }
@@ -401,23 +460,27 @@ interface ElseAttribute {
 }
 type ConditionalAttribute = IfAttribute | ElifAttribute | ElseAttribute;
 /** A const_assert statement. */
-interface ConstAssertElem extends ElemWithContentsBase, HasAttributes {
+interface ConstAssertElem extends AbstractElemBase, HasAttributes {
   kind: "assert";
+  expression: ExpressionElem;
 }
 /** A const declaration. */
-interface ConstElem extends ElemWithContentsBase, HasAttributes {
+interface ConstElem extends AbstractElemBase, HasAttributes {
   kind: "const";
   name: TypedDeclElem;
+  init?: ExpressionElem;
 }
 /** An expression without special handling, used in attribute parameters. */
-interface UnknownExpressionElem extends ElemWithContentsBase {
+interface UnknownExpressionElem extends AbstractElemBase {
   kind: "expression";
+  expression: ExpressionElem;
 }
 /** An expression that can be safely evaluated at compile time. */
 interface TranslateTimeExpressionElem {
   kind: "translate-time-expression";
   expression: ExpressionElem;
-  span: Span;
+  start: number;
+  end: number;
 }
 /** A literal value (boolean or number) in WESL source. */
 interface Literal extends AbstractElemBase {
@@ -458,13 +521,21 @@ interface BinaryExpression extends AbstractElemBase {
 interface FunctionCallExpression extends AbstractElemBase {
   kind: "call-expression";
   function: RefIdentElem | TypeRefElem;
+  /** Only populated for function calls; constructor calls carry templates on `function`. */
   templateArgs?: TypeTemplateParameter[];
   arguments: ExpressionElem[];
 }
 interface UnaryOperator {
   value: "!" | "&" | "*" | "-" | "~";
-  span: Span;
+  start: number;
+  end: number;
 }
+/** Uses span (not inline start/end) so each operator object stays in a smaller
+ * V8 size class. Inline start/end uses slightly less memory overall (no separate
+ * span tuple) but each object is bigger and more likely to be promoted to old
+ * gen under sustained allocation pressure, triggering more major GCs and
+ * ~5% slower wall time on math-heavy parse workloads (bevy_env_map/parse).
+ * A rare case where allocating more bytes wins on GC. */
 interface BinaryOperator {
   value: ("||" | "&&" | "+" | "-" | "*" | "/" | "%" | "==") | ("!=" | "<" | "<=" | ">" | ">=" | "|" | "&" | "^") | ("<<" | ">>");
   span: Span;
@@ -487,90 +558,198 @@ interface RequiresDirective {
   kind: "requires";
   extensions: NameElem[];
 }
+/**
+ * A `do` block: a CPU-side dispatch script (`do name(params) { ... }`).
+ *
+ * Module-local: its name and body idents never enter bindIdents/the scope
+ * tree, and the linker drops it entirely from emitted WGSL. The parsed body
+ * is retained for the interpreter, which resolves names by AST match.
+ */
+interface DoBlockElem extends AbstractElemBase, HasAttributes {
+  kind: "do";
+  name: NameElem;
+  params: FnParamElem[];
+  body: BlockElem;
+}
 /** A function declaration. */
-interface FnElem extends ElemWithContentsBase, HasAttributes {
+interface FnElem extends AbstractElemBase, HasAttributes {
   kind: "fn";
   name: DeclIdentElem;
   params: FnParamElem[];
-  body: StatementElem;
+  body: BlockElem;
   returnAttributes?: AttributeElem[];
   returnType?: TypeRefElem;
 }
 /** A global variable declaration (at the root level). */
-interface GlobalVarElem extends ElemWithContentsBase, HasAttributes {
+interface GlobalVarElem extends AbstractElemBase, HasAttributes {
   kind: "gvar";
   name: TypedDeclElem;
+  /** Address-space / access-mode enumerants, e.g. `<storage, read_write>`. */
+  template?: NameElem[];
+  init?: ExpressionElem;
 }
 /** An entire file. */
-interface ModuleElem extends ElemWithContentsBase {
+interface ModuleElem extends AbstractElemBase {
   kind: "module";
+  /** Top-level children (imports, directives, declarations, and any synthetic
+   *  vars added by transforms) in source order. */
+  decls: AbstractElem[];
 }
 /** An override declaration. */
-interface OverrideElem extends ElemWithContentsBase, HasAttributes {
+interface OverrideElem extends AbstractElemBase, HasAttributes {
   kind: "override";
   name: TypedDeclElem;
+  init?: ExpressionElem;
 }
 /** A parameter in a function declaration. */
-interface FnParamElem extends ElemWithContentsBase, HasAttributes {
+interface FnParamElem extends AbstractElemBase, HasAttributes {
   kind: "param";
   name: TypedDeclElem;
 }
-/** 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. */
-interface StructElem extends ElemWithContentsBase, HasAttributes {
+interface StructElem extends AbstractElemBase, HasAttributes {
   kind: "struct";
   name: DeclIdentElem;
   members: StructMemberElem[];
-  bindingStruct?: true;
-}
-/** Generic container of other elements. */
-interface StuffElem extends ElemWithContentsBase {
-  kind: "stuff";
-}
-/** A struct declaration marked as a binding struct. */
-interface BindingStructElem extends StructElem {
-  bindingStruct: true;
-  entryFn?: FnElem;
 }
 /** A member of a struct declaration. */
-interface StructMemberElem extends ElemWithContentsBase, HasAttributes {
+interface StructMemberElem extends AbstractElemBase, HasAttributes {
   kind: "member";
   name: NameElem;
   typeRef: TypeRefElem;
-  mangledVarName?: string;
 }
 type TypeTemplateParameter = ExpressionElem;
 /** A type reference like 'f32', 'MyStruct', or 'ptr<storage, array<f32>, read_only>'. */
-interface TypeRefElem extends ElemWithContentsBase {
+interface TypeRefElem extends AbstractElemBase {
   kind: "type";
   name: RefIdent;
   templateParams?: TypeTemplateParameter[];
 }
 /** A variable declaration. */
-interface VarElem extends ElemWithContentsBase, HasAttributes {
+interface VarElem extends AbstractElemBase, HasAttributes {
   kind: "var";
   name: TypedDeclElem;
+  /** Address-space / access-mode enumerants, e.g. `<storage, read_write>`. */
+  template?: NameElem[];
+  init?: ExpressionElem;
 }
-interface LetElem extends ElemWithContentsBase, HasAttributes {
+interface LetElem extends AbstractElemBase, HasAttributes {
   kind: "let";
   name: TypedDeclElem;
-}
-interface StatementElem extends ElemWithContentsBase, HasAttributes {
-  kind: "statement";
-}
-interface ContinuingElem extends ElemWithContentsBase, HasAttributes {
+  init?: ExpressionElem;
+}
+/** Any WGSL statement inside a function or block body. */
+type Statement = BlockElem | IfElem | ForElem | WhileElem | LoopElem | ContinuingElem | SwitchElem | ReturnElem | BreakElem | ContinueElem | DiscardElem | AssignElem | IncrementElem | DecrementElem | CallElem | ConstAssertElem | EmptyElem | VarElem | LetElem | ConstElem;
+/** A bare `;` statement. Emits nothing, but kept in the AST as a statement node. */
+interface EmptyElem extends AbstractElemBase, HasAttributes {
+  kind: "empty";
+}
+/** A `{ ... }` compound statement. */
+interface BlockElem extends AbstractElemBase, HasAttributes {
+  kind: "block";
+  body: Statement[];
+  /** Comments inside an otherwise empty block, with no statement to attach to. */
+  innerComments?: CommentElem[];
+}
+/** An if / else-if / else chain. `else` nests: else-if is an IfElem, plain else a BlockElem. */
+interface IfElem extends AbstractElemBase, HasAttributes {
+  kind: "if";
+  condition: ExpressionElem;
+  body: BlockElem;
+  else?: IfElem | BlockElem;
+}
+/** A for loop. */
+interface ForElem extends AbstractElemBase, HasAttributes {
+  kind: "for";
+  init?: ForInit;
+  condition?: ExpressionElem;
+  update?: ForUpdate;
+  body: BlockElem;
+}
+type ForInit = VarElem | LetElem | ConstElem | AssignElem | IncrementElem | DecrementElem | CallElem;
+type ForUpdate = AssignElem | IncrementElem | DecrementElem | CallElem;
+/** A while loop. */
+interface WhileElem extends AbstractElemBase, HasAttributes {
+  kind: "while";
+  condition: ExpressionElem;
+  body: BlockElem;
+}
+/** A loop, optionally ending with a continuing block. */
+interface LoopElem extends AbstractElemBase, HasAttributes {
+  kind: "loop";
+  body: BlockElem;
+  continuing?: ContinuingElem;
+}
+/** A continuing block, optionally ending with `break if expr`. */
+interface ContinuingElem extends AbstractElemBase, HasAttributes {
   kind: "continuing";
-}
-/** Statement or continuing - used in loop body parsing. */
-type BlockStatement = StatementElem | ContinuingElem;
-interface SwitchClauseElem extends ElemWithContentsBase, HasAttributes {
+  body: BlockElem;
+  breakIf?: ExpressionElem;
+}
+/** A switch statement. */
+interface SwitchElem extends AbstractElemBase, HasAttributes {
+  kind: "switch";
+  selector: ExpressionElem;
+  clauses: SwitchClauseElem[];
+  /** Attributes on the switch body, between the selector and `{`. */
+  bodyAttributes?: AttributeElem[];
+}
+/** A case or default clause. `"default"` sentinel marks the default selector. */
+interface SwitchClauseElem extends AbstractElemBase, HasAttributes {
   kind: "switch-clause";
+  selectors: (ExpressionElem | "default")[];
+  body: BlockElem;
+}
+/** A return statement, with an optional value. */
+interface ReturnElem extends AbstractElemBase, HasAttributes {
+  kind: "return";
+  value?: ExpressionElem;
+}
+/** A break statement, or `break if expr`. */
+interface BreakElem extends AbstractElemBase, HasAttributes {
+  kind: "break";
+  condition?: ExpressionElem;
+}
+/** A continue statement. */
+interface ContinueElem extends AbstractElemBase, HasAttributes {
+  kind: "continue";
+}
+/** A discard statement. */
+interface DiscardElem extends AbstractElemBase, HasAttributes {
+  kind: "discard";
+}
+/** Assignment, compound assignment, or phony `_ = expr`. */
+interface AssignElem extends AbstractElemBase, HasAttributes {
+  kind: "assign";
+  lhs: ExpressionElem | PhonyTarget;
+  op: AssignOp;
+  rhs: ExpressionElem;
+}
+/** `i++` */
+interface IncrementElem extends AbstractElemBase, HasAttributes {
+  kind: "increment";
+  target: ExpressionElem;
+}
+/** `i--` */
+interface DecrementElem extends AbstractElemBase, HasAttributes {
+  kind: "decrement";
+  target: ExpressionElem;
+}
+/** A bare function call statement. */
+interface CallElem extends AbstractElemBase, HasAttributes {
+  kind: "call";
+  call: FunctionCallExpression;
+}
+/** The `_` discard target of a phony assignment; never enters the ident system. */
+interface PhonyTarget {
+  kind: "phony";
+  span: Span;
+}
+/** An assignment operator. Uses a span tuple (not inline start/end) to match
+ * BinaryOperator's smaller V8 size class; see the note there. */
+interface AssignOp {
+  value: ("=" | "+=" | "-=" | "*=" | "/=" | "%=") | ("&=" | "|=" | "^=" | "<<=" | ">>=");
+  span: Span;
 }
 //#endregion
 //#region src/SrcMap.d.ts
@@ -628,8 +807,6 @@ declare class SrcMapBuilder {
   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;
 }
@@ -787,6 +964,8 @@ interface RecordResolverOptions {
   packageName?: string;
   /** Debug path prefix for error messages */
   debugWeslRoot?: string;
+  /** Enable experimental, not-yet-spec'd syntax extensions while parsing. */
+  weslExtensions?: WeslExtensions;
 }
 /** Module resolver for in-memory source records. Lazy by default. */
 declare class RecordResolver implements BatchModuleResolver {
@@ -794,6 +973,7 @@ declare class RecordResolver implements BatchModuleResolver {
   readonly sources: Record<string, string>;
   readonly packageName: string;
   readonly debugWeslRoot: string;
+  readonly weslExtensions?: WeslExtensions;
   constructor(sources: Record<string, string>, options?: RecordResolverOptions);
   resolveModule(modulePath: string): WeslAST | undefined;
   private findSource;
@@ -874,9 +1054,13 @@ interface LinkParams {
   constants?: Record<string, string | number>;
   /** function to construct globally unique wgsl identifiers */
   mangler?: ManglerFn;
+  /** opt-in parsing of experimental, not-yet-spec'd syntax extensions.
+   * Only applied to the local source resolver built from `weslSrc`; callers
+   * that supply their own `resolver` must set it on that resolver. */
+  weslExtensions?: WeslExtensions;
 }
 /** Project config for web components and tools. */
-type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName"> & {
+type WeslProject = Pick<LinkParams, "weslSrc" | "rootModuleName" | "conditions" | "constants" | "libs" | "packageName" | "weslExtensions"> & {
   /** Shader directory relative to project root (set by ?link from wesl.toml). */shaderRoot?: string;
 };
 /** Context passed to virtual library generators. */
@@ -1026,7 +1210,6 @@ declare function filterValidElements<T extends AbstractElem>(elements: readonly
 declare function astToString(elem: AbstractElem, indent?: number): string;
 /** @return string representation of an attribute (for test/debug) */
 declare function attributeToString(attr: Attribute): string;
-declare function debugContentsToString(elem: StuffElem): string;
 //#endregion
 //#region src/debug/ScopeToString.d.ts
 /** A debugging print of the scope tree with identifiers in nested brackets */
@@ -1110,6 +1293,20 @@ declare function sanitizePackageName(npmName: string): string;
  */
 declare function npmNameVariations(sanitizedPath: string): Generator<string>;
 //#endregion
+//#region src/LinkerUtil.d.ts
+/** A module's top-level declarations of a given kind, narrowed to that elem type. */
+declare function declsOfKind<K extends AbstractElem["kind"]>(moduleElem: ModuleElem, kind: K): Extract<AbstractElem, {
+  kind: K;
+}>[];
+/** Visit an elem and all its descendants, parent before children (pre-order). */
+declare function visitAst(elem: AbstractElem, visitor: (elem: AbstractElem) => void): void;
+/**
+ * Child elems of any AST node: the typed structural fields (attributes plus
+ * body / condition / decls / ...) in source order. Returns [] for leaf elems.
+ */
+declare function childElems(elem: AbstractElem): readonly AbstractElem[];
+declare function identElemLog(identElem: DeclIdentElem | RefIdentElem, ...messages: any[]): void;
+//#endregion
 //#region src/Logging.d.ts
 /** base logger (can be overridden to a capturing logger for tests) */
 declare let log: (...data: any[]) => void;
@@ -1172,57 +1369,6 @@ declare function stdFn(name: string): boolean;
 /** return true if the name is for a built in enumerant */
 declare function stdEnumerant(name: string): boolean;
 //#endregion
-//#region src/TransformBindingStructs.d.ts
-declare function bindingStructsPlugin(): WeslJsPlugin;
-/**
- * Transform binding structures into binding variables by mutating the AST.
- *
- * First we find all the binding structs:
- *   . find all the structs in the module by filtering the moduleElem.contents
- *     . for each struct:
- *       . mark any structs with that contain @group or @binding annotations as 'binding structs' and save them in a list
- *       . (later) create reverse links from structs to struct members
- *       . (later) visit all the binding structs and traverse to referencing structs, marking the referencing structs as binding structs too
- * Generate synethic AST nodes for binding variables
- *
- * Find all references to binding struct members
- *   . find the componound idents by traversing moduleElem.contents
- *   . filter to find the compound idents that refer to 'binding structs'
- *     . go from each ident to its declaration,
- *     . declaration to typeRef reference
- *     . typeRef to type declaration
- *     . check type declaration to see if it's a binding struct
- *     . record the intermediate declaration (e.g. a fn param b:Bindings from 'fn(b:Bindings)' )
- * rewrite references to binding struct members as synthetic elements
- *
- * Remove the binding structs from the AST
- * Remove the intermediate fn param declarations from the AST
- * Add the new binding variables to the AST
- *
- * @return the binding structs and the mutated AST
- */
-declare function lowerBindingStructs(ast: TransformedAST): TransformedAST;
-declare function markEntryTypes(moduleElem: ModuleElem, bindingStructs: BindingStructElem[]): void;
-/** mutate the AST, marking StructElems as bindingStructs
- *  (if they contain ptrs with @group @binding annotations)
- * @return the binding structs
- */
-declare function markBindingStructs(moduleElem: ModuleElem): BindingStructElem[];
-/** convert each member of the binding struct into a synthetic global variable */
-declare function transformBindingStruct(s: StructElem, globalNames: Set<string>): SyntheticElem[];
-interface MemberRefToStruct extends StructTrace {
-  memberRef: SimpleMemberRef;
-}
-interface StructTrace {
-  struct: StructElem;
-  intermediates: DeclarationElem[];
-}
-/** find all simple member references in the module that refer to binding structs */
-declare function findRefsToBindingStructs(moduleElem: ModuleElem): MemberRefToStruct[];
-/** Mutate the member reference elem to instead contain synthetic elem text.
- * The new text is the mangled var name of the struct member that the memberRef refers to. */
-declare function transformBindingReference(memberRef: SimpleMemberRef, struct: StructElem): SyntheticElem;
-//#endregion
 //#region src/Util.d.ts
 declare function multiKeySet<A, B, V>(m: Map<A, Map<B, V>>, a: A, b: B, v: V): void;
 /** replace strings in a text according to a relacement map
@@ -1267,4 +1413,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, 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 };
+export { AbstractElem, AbstractElemBase, AliasElem, AssignElem, AssignOp, Attribute, AttributeElem, BatchModuleResolver, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BlockElem, BoundAndTransformed, BreakElem, BuiltinAttribute, BundleResolver, CallElem, CommentElem, ComponentExpression, ComponentMemberExpression, CompositeResolver, ConditionalAttribute, Conditions, ConstAssertElem, ConstElem, ContinueElem, ContinuingElem, DeclIdent, DeclIdentElem, DeclarationElem, DecrementElem, DiagnosticAttribute, DiagnosticDirective, DiagnosticRule, DirectiveElem, DirectiveVariant, DiscardElem, DoBlockElem, ElemKindMap, ElemWithAttributes, ElifAttribute, ElseAttribute, EmittableElem, EmptyElem, EnableDirective, ExpressionElem, ExtendedGPUValidationError, FnElem, FnParamElem, ForElem, ForInit, ForUpdate, FunctionCallExpression, GlobalDeclarationElem, GlobalVarElem, GrammarElem, HasAttributes, Ident, IfAttribute, IfElem, ImportCollection, ImportElem, ImportItem, ImportSegment, ImportStatement, IncrementElem, InterpolateAttribute, LetElem, LexicalScope, LinkConfig, LinkParams, LinkRegistryParams, LinkedWesl, LinkerTransform, Literal, LiveDecls, LoopElem, ManglerFn, ModuleElem, ModuleResolver, NameElem, OverrideElem, ParenthesizedExpression, ParseError, type ParseOptions, PartialScope, PhonyTarget, RecordResolver, RecordResolverOptions, RefIdent, RefIdentElem, RequiresDirective, ReturnElem, Scope, ScopeItem, Span, SrcMap, SrcMapBuilder, SrcMapEntry, SrcModule, SrcPosition, SrcWithPath, StableState, StandardAttribute, Statement, StructElem, StructMemberElem, SwitchClauseElem, SwitchElem, SyntheticElem, TerminalElem, TrackingResolver, TransformedAST, TranslateTimeExpressionElem, TypeRefElem, TypeTemplateParameter, TypedDeclElem, UnaryExpression, UnaryOperator, UnboundRef, UnknownExpressionElem, VarElem, VirtualLibContext, VirtualLibrary, VirtualLibraryFn, VirtualLibrarySet, WeslAST, WeslBundle, WeslDevice, type WeslExtensions, WeslGPUCompilationInfo, WeslGPUCompilationMessage, WeslJsPlugin, WeslParseContext, WeslParseError, WeslParseState, WeslProject, WeslStream, WhileElem, _linkSync, astToString, attributeToString, bindAndTransform, bindIdents, bindIdentsRecursive, childElems, childIdent, childScope, containsScope, debug, declsOfKind, discoverModules, emptyScope, errorHighlight, fileToModulePath, filterMap, filterValidElements, findAllRootDecls, findMap, findUnboundIdents, findUnboundRefs, findValidRootDecls, flatImports, freshResolver, groupBy, grouped, identElemLog, identToString, last, lengthPrefixMangle, link, linkRegistry, liveDeclsToString, log, makeLiveDecls, makeWeslDevice, mapForward, mapValues, 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, underscoreMangle, validation, visitAst, wgslStandardAttributes, withLoggerAsync };