wesl 0.6.9 → 0.6.15

package/dist/index.d.ts

@@ -0,0 +1,977 @@
+import { AppState, ParseError, Span, SrcMap, Stream, TypedToken } from "mini-parse";
+
+//#region src/LiveDeclarations.d.ts
+/** decls currently visible in this scope */
+interface LiveDecls {
+  /** decls currently visible in this scope */
+  decls: Map<string, DeclIdent>;
+  /** live decls in the parent scope. null for the modue root scope */
+  parent?: LiveDecls | null;
+}
+//#endregion
+//#region src/FlattenTreeImport.d.ts
+interface FlatImport {
+  importPath: string[];
+  modulePath: string[];
+}
+//#endregion
+//#region src/WESLCollect.d.ts
+type OpenElem<T extends ContainerElem = ContainerElem> = Pick<T, "kind" | "contents">;
+//#endregion
+//#region src/ParseWESL.d.ts
+/** result of a parse for one wesl module (e.g. one .wesl file)
+ *
+ * The parser constructs the AST constructed into three sections
+ * for convenient access by the binding stage.
+ *  - import statements
+ *  - language elements (fn, struct, etc)
+ *  - scopes
+ *
+ */
+interface WeslAST {
+  /** source text for this module */
+  srcModule: SrcModule;
+  /** root module element */
+  moduleElem: ModuleElem;
+  /** root scope for this module */
+  rootScope: Scope;
+  /** imports found in this module */
+  imports: ImportStatement[];
+  /** module level const_assert statements */
+  moduleAsserts?: ConstAssertElem[];
+}
+/** an extended version of the AST */
+interface BindingAST extends WeslAST {
+  _flatImports?: FlatImport[];
+}
+/** stable and unstable state used during parsing */
+interface WeslParseState extends AppState<WeslParseContext, StableState> {
+  context: WeslParseContext;
+  stable: StableState;
+}
+/** stable values used or accumulated during parsing */
+type StableState = WeslAST;
+/** unstable values used during parse collection */
+interface WeslParseContext {
+  scope: Scope;
+  openElems: OpenElem[];
+}
+/**
+ * An error when parsing WESL fails. Designed to be human-readable.
+ */
+declare class WeslParseError extends Error {
+  span: Span;
+  src: SrcModule;
+  constructor(opts: {
+    cause: ParseError;
+    src: SrcModule;
+  });
+}
+/** Parse a WESL file. Throws on error. */
+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. */
+declare function flatImports(ast: BindingAST, conditions?: Conditions): FlatImport[];
+//#endregion
+//#region src/Scope.d.ts
+interface SrcModule {
+  /** module path "rand_pkg::sub::foo", or "package::main" */
+  modulePath: string;
+  /** file path to the module for user error reporting e.g "rand_pkg:sub/foo.wesl", or "./sub/foo.wesl" */
+  debugFilePath: string;
+  /** original src for module */
+  src: string;
+}
+/** a src declaration or reference to an ident */
+type Ident = DeclIdent | RefIdent;
+/** LATER change this to a Map, so that `toString` isn't accidentally a condition */
+type Conditions = Record<string, boolean>;
+interface IdentBase {
+  originalName: string;
+  id?: number;
+}
+interface RefIdent extends IdentBase {
+  kind: "ref";
+  refersTo?: Ident;
+  std?: true;
+  ast: WeslAST;
+  refIdentElem: RefIdentElem;
+}
+interface DeclIdent extends IdentBase {
+  kind: "decl";
+  /** name in the output code */
+  mangledName?: string;
+  /** link to AST so that we can traverse scopes and know what elems to emit */
+  declElem?: DeclarationElem;
+  /** scope in which this declaration is found */
+  containingScope: Scope;
+  /** scope for the references within this declaration
+   * (only needed for global decls.)
+   * if this decl is included in the link, dependentScope holds other refIdents that should be included too */
+  dependentScope?: Scope;
+  /** true if this is a global declaration (e.g. not a local variable) */
+  isGlobal: boolean;
+  /** To figure out which module this declaration is from. */
+  srcModule: SrcModule;
+}
+/** tree of ident references, organized by lexical scope and partialScope . */
+type Scope = LexicalScope | PartialScope;
+/** A wgsl scope */
+interface LexicalScope extends ScopeBase {
+  kind: "scope";
+  /**
+   * Efficient access to declarations in this scope.
+   * constructed on demand, for module root scopes only */
+  _scopeDecls?: LiveDecls;
+  /** Cached list of valid root declarations after conditional filtering.
+   * Populated on first access for module root scopes. */
+  _validRootDecls?: DeclIdent[];
+}
+/** A synthetic partial scope to contain @if conditioned idents.
+ * PartialScope idents are considered to be in the wgsl lexical scope of their parent.  */
+interface PartialScope extends ScopeBase {
+  kind: "partial";
+}
+/** common scope elements  */
+interface ScopeBase {
+  /** id for debugging */
+  id: number;
+  /** null for root scope in a module */
+  parent: Scope | null;
+  contents: (Ident | Scope)[];
+  /** Conditional attribute (@if or @else) for this scope */
+  condAttribute?: IfAttribute | ElifAttribute | ElseAttribute;
+}
+/** Combine two scope siblings.
+ * The first scope is mutated to append the contents of the second.  */
+declare function mergeScope(a: Scope, b: Scope | undefined): void;
+/** reset scope and ident debugging ids */
+declare function resetScopeIds(): void;
+declare function nextIdentId(): number;
+/** make a new Scope object */
+declare function emptyScope(parent: Scope | null, kind?: Scope["kind"]): Omit<Scope, "condAttribute">;
+/** For debugging,
+ * @return true if a scope is in the rootScope tree somewhere */
+declare function containsScope(rootScope: Scope, scope: Scope): boolean;
+/** @returns true if the provided element of a Scope
+ *    is itself a Scope (and not an Ident) */
+declare function childScope(child: Scope | Ident): child is Scope;
+/** @returns true if the provided element of a Scope
+ *    is an Ident (and not a child Scope) */
+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.
+ *
+ * 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.
+ */
+type AbstractElem = GrammarElem | SyntheticElem;
+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;
+/** 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 TerminalElem = DirectiveElem | DeclIdentElem | NameElem | RefIdentElem | TextElem | ImportElem;
+type GlobalDeclarationElem = AliasElem | ConstElem | FnElem | GlobalVarElem | OverrideElem | StructElem;
+type DeclarationElem = GlobalDeclarationElem | FnParamElem | VarElem;
+type ElemWithAttributes = Extract<AbstractElem, HasAttributes>;
+interface AbstractElemBase {
+  kind: AbstractElem["kind"];
+  start: number;
+  end: number;
+}
+interface ElemWithContentsBase extends AbstractElemBase {
+  contents: AbstractElem[];
+}
+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)'
+ */
+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
+ */
+interface NameElem extends AbstractElemBase {
+  kind: "name";
+  name: string;
+}
+/** an identifier that 'refers to' a declaration (aka a symbol reference) */
+interface RefIdentElem extends AbstractElemBase {
+  kind: RefIdent["kind"];
+  ident: RefIdent;
+  srcModule: SrcModule;
+}
+/** a declaration identifier (aka a symbol declaration) */
+interface DeclIdentElem extends AbstractElemBase {
+  kind: DeclIdent["kind"];
+  ident: DeclIdent;
+  srcModule: SrcModule;
+}
+/** Holds an import statement, and has a span */
+interface ImportElem extends AbstractElemBase, HasAttributes {
+  kind: "import";
+  imports: ImportStatement;
+}
+/**
+ * An import statement, which is tree shaped.
+ * `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}`
+ */
+interface ImportSegment {
+  kind: "import-segment";
+  name: string;
+}
+/**
+ * A primitive segment in an import statement.
+ * `foo`
+ */
+interface ImportCollection {
+  kind: "import-collection";
+  subtrees: ImportStatement[];
+}
+/**
+ * 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 */
+interface SyntheticElem {
+  kind: "synthetic";
+  text: string;
+}
+/** a declaration identifer with a possible type */
+interface TypedDeclElem extends ElemWithContentsBase {
+  kind: "typeDecl";
+  decl: DeclIdentElem;
+  typeRef?: TypeRefElem;
+  typeScope?: Scope;
+}
+/** an alias statement */
+interface AliasElem extends ElemWithContentsBase, HasAttributes {
+  kind: "alias";
+  name: DeclIdentElem;
+  typeRef: TypeRefElem;
+}
+/** an attribute like '@compute' or '@binding(0)' */
+interface AttributeElem extends ElemWithContentsBase {
+  kind: "attribute";
+  attribute: Attribute;
+}
+type Attribute = StandardAttribute | InterpolateAttribute | BuiltinAttribute | DiagnosticAttribute | IfAttribute | ElifAttribute | ElseAttribute;
+interface StandardAttribute {
+  kind: "@attribute";
+  name: string;
+  params?: UnknownExpressionElem[];
+}
+interface InterpolateAttribute {
+  kind: "@interpolate";
+  params: NameElem[];
+}
+interface BuiltinAttribute {
+  kind: "@builtin";
+  param: NameElem;
+}
+interface DiagnosticAttribute {
+  kind: "@diagnostic";
+  severity: NameElem;
+  rule: [NameElem, NameElem | null];
+}
+interface IfAttribute {
+  kind: "@if";
+  param: TranslateTimeExpressionElem;
+}
+interface ElifAttribute {
+  kind: "@elif";
+  param: TranslateTimeExpressionElem;
+}
+interface ElseAttribute {
+  kind: "@else";
+}
+/** a const_assert statement */
+interface ConstAssertElem extends ElemWithContentsBase, HasAttributes {
+  kind: "assert";
+}
+/** a const declaration */
+interface ConstElem extends ElemWithContentsBase, HasAttributes {
+  kind: "const";
+  name: TypedDeclElem;
+}
+/** an expression w/o special handling, used inside attribute parameters */
+interface UnknownExpressionElem extends ElemWithContentsBase {
+  kind: "expression";
+}
+/** 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 {
+  kind: "literal";
+  value: string;
+  span: Span;
+}
+/** `words`s inside `@if` */
+interface TranslateTimeFeature {
+  kind: "translate-time-feature";
+  name: string;
+  span: Span;
+}
+/** (expr) */
+interface ParenthesizedExpression {
+  kind: "parenthesized-expression";
+  expression: ExpressionElem;
+}
+/** `foo[expr]` */
+interface ComponentExpression {
+  kind: "component-expression";
+  base: ExpressionElem;
+  access: ExpressionElem;
+}
+/** `foo.member` */
+interface ComponentMemberExpression {
+  kind: "component-member-expression";
+  base: ExpressionElem;
+  access: NameElem;
+}
+/** `+foo` */
+interface UnaryExpression {
+  kind: "unary-expression";
+  operator: UnaryOperator;
+  expression: ExpressionElem;
+}
+/** `foo + bar` */
+interface BinaryExpression {
+  kind: "binary-expression";
+  operator: BinaryOperator;
+  left: ExpressionElem;
+  right: ExpressionElem;
+}
+/** `foo(arg, arg)` */
+interface FunctionCallExpression {
+  kind: "call-expression";
+  function: RefIdentElem;
+  arguments: ExpressionElem[];
+}
+interface UnaryOperator {
+  value: "!" | "&" | "*" | "-" | "~";
+  span: Span;
+}
+interface BinaryOperator {
+  value: ("||" | "&&" | "+" | "-" | "*" | "/" | "%" | "==") | ("!=" | "<" | "<=" | ">" | ">=" | "|" | "&" | "^") | ("<<" | ">>");
+  span: Span;
+}
+type DirectiveVariant = DiagnosticDirective | EnableDirective | RequiresDirective;
+interface DirectiveElem extends AbstractElemBase, HasAttributes {
+  kind: "directive";
+  directive: DirectiveVariant;
+}
+interface DiagnosticDirective {
+  kind: "diagnostic";
+  severity: NameElem;
+  rule: [NameElem, NameElem | null];
+}
+interface EnableDirective {
+  kind: "enable";
+  extensions: NameElem[];
+}
+interface RequiresDirective {
+  kind: "requires";
+  extensions: NameElem[];
+}
+/** a function declaration */
+interface FnElem extends ElemWithContentsBase, HasAttributes {
+  kind: "fn";
+  name: DeclIdentElem;
+  params: FnParamElem[];
+  body: StatementElem;
+  returnAttributes?: AttributeElem[];
+  returnType?: TypeRefElem;
+}
+/** a global variable declaration (at the root level) */
+interface GlobalVarElem extends ElemWithContentsBase, HasAttributes {
+  kind: "gvar";
+  name: TypedDeclElem;
+}
+/** an entire file */
+interface ModuleElem extends ElemWithContentsBase {
+  kind: "module";
+}
+/** an override declaration */
+interface OverrideElem extends ElemWithContentsBase, HasAttributes {
+  kind: "override";
+  name: TypedDeclElem;
+}
+/** 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) */
+interface SimpleMemberRef extends ElemWithContentsBase {
+  kind: "memberRef";
+  name: RefIdentElem;
+  member: NameElem;
+  extraComponents?: StuffElem;
+}
+/** a struct declaration */
+interface StructElem extends ElemWithContentsBase, HasAttributes {
+  kind: "struct";
+  name: DeclIdentElem;
+  members: StructMemberElem[];
+  bindingStruct?: true;
+}
+/** generic container of other elements */
+interface StuffElem extends ElemWithContentsBase {
+  kind: "stuff";
+}
+/** a struct declaration that's been marked as a bindingStruct */
+interface BindingStructElem extends StructElem {
+  bindingStruct: true;
+  entryFn?: FnElem;
+}
+/** 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>'   */
+interface TypeRefElem extends ElemWithContentsBase {
+  kind: "type";
+  name: RefIdent;
+  templateParams?: TypeTemplateParameter[];
+}
+/** a variable declaration */
+interface VarElem extends ElemWithContentsBase, HasAttributes {
+  kind: "var";
+  name: TypedDeclElem;
+}
+interface LetElem extends ElemWithContentsBase, HasAttributes {
+  kind: "let";
+  name: TypedDeclElem;
+}
+interface StatementElem extends ElemWithContentsBase, HasAttributes {
+  kind: "statement";
+}
+interface SwitchClauseElem extends ElemWithContentsBase, HasAttributes {
+  kind: "switch-clause";
+}
+//#endregion
+//#region src/WeslDevice.d.ts
+/**
+ * A {@link GPUDevice} with extensions for WESL. Created with {@link makeWeslDevice}.
+ * Used to make error reporting point at the orignal WESL sources.
+ */
+interface WeslDevice extends GPUDevice {
+  /**
+   * Attaches an error to the current error scope (created by {@link GPUDevice.pushErrorScope}).
+   * If there is no error scope, it reports the error as a `'uncapturederror'`
+   */
+  injectError(type: GPUErrorFilter, error: Promise<GPUError | null>): void;
+}
+/**
+ * Creates {@link WeslDevice} for usage with WESL.
+ * Does not impact your existing code, wherever a {@link GPUDevice} can be used,
+ * a {@link WeslDevice} is also valid.
+ *
+ * WESL uses a {@link WeslDevice} to display errors referencing the WESL source
+ * instead of referencing the generated WGSL code.
+ */
+declare function requestWeslDevice(adapter: GPUAdapter | null, descriptor?: GPUDeviceDescriptor): Promise<WeslDevice>;
+/**
+ * Mutates a {@link GPUDevice} for usage with WESL.
+ * Does not impact your existing code, wherever a {@link GPUDevice} can be used,
+ * a {@link WeslDevice} is also valid.
+ *
+ * WESL uses a {@link WeslDevice} to display errors referencing the WESL source
+ * instead of referencing the generated WGSL code.
+ */
+declare function makeWeslDevice(device: GPUDevice): WeslDevice;
+//#endregion
+//#region src/LinkedWesl.d.ts
+/** Results of shader compilation. Has {@link WeslGPUCompilationMessage}
+ * which are aware of the WESL module that an error was thrown from. */
+interface WeslGPUCompilationInfo extends GPUCompilationInfo {
+  messages: WeslGPUCompilationMessage[];
+}
+interface WeslGPUCompilationMessage extends GPUCompilationMessage {
+  module: {
+    url: string;
+    text?: string;
+  };
+}
+/**
+ * A {@link GPUValidationError} with an inner error (for a stack trace).
+ * Can also point at a WESL source file.
+ */
+interface ExtendedGPUValidationError extends GPUValidationError {
+  cause?: Error;
+  compilationInfo?: WeslGPUCompilationInfo;
+}
+/**
+ * Multiple WESL files that have been linked together to produce WGSL code.
+ *
+ * Call {@link LinkedWesl.createShaderModule} on a {@link WeslDevice}
+ * to make the error reporting aware of the WESL code.
+ */
+declare class LinkedWesl {
+  sourceMap: SrcMap;
+  constructor(sourceMap: SrcMap);
+  /**
+   * Creates a {@link GPUShaderModule}.
+   * When errors occur, they will point at the original WESL source code.
+   *
+   * The compilation info {@link GPUShaderModule.getCompilationInfo}
+   * can be remapped with {@link mapGPUCompilationInfo}
+   * @param device GPUDevice. Preferably a {@link WeslDevice} for better error reporting.
+   * @param descriptor - Description of the {@link GPUShaderModule} to create.
+   */
+  createShaderModule(device: GPUDevice | WeslDevice, descriptor?: Omit<GPUShaderModuleDescriptor, "code">): GPUShaderModule;
+  /**
+   * Use {@link LinkedWesl.createShaderModule} for a
+   * better error reporting experience.
+   */
+  get dest(): string;
+  /** Turns raw compilation info into compilation info
+   * that points at the WESL sources. */
+  mapGPUCompilationInfo(compilationInfo: GPUCompilationInfo): WeslGPUCompilationInfo;
+  private mapGPUCompilationMessage;
+}
+//#endregion
+//#region src/Mangler.d.ts
+/**
+ * A function for constructing a unique identifier name for a global declaration.
+ * Global names must be unique in the linked wgsl.
+ *
+ * Three manglers are currently available:
+ * . minimalMangle preserves original source names where possible
+ * . underscoreMangle constructs long but predictable names for every declaration
+ * . lengthPrefixMangle constructs long but predictable names for every declaration
+ */
+type ManglerFn = (/** global declaration that needs a name */
+decl: DeclIdent, /** module that contains the declaration */
+srcModule: SrcModule, /** name at use site (possibly import as renamed from declaration) */
+proposedName: string, /** current set of mangled root level names for the linked result (read only) */
+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)
+ */
+declare function underscoreMangle(decl: DeclIdent, srcModule: SrcModule): string;
+/**
+ * Construct a globally unique name based on the declaration
+ */
+declare function lengthPrefixMangle(decl: DeclIdent, srcModule: SrcModule): string;
+/**
+ * ManglerFn to construct a globally unique name
+ * using the requested name plus a uniquing number suffix if necessary
+ */
+declare function minimalMangle(_d: DeclIdent, _s: SrcModule, proposedName: string, globalNames: Set<string>): string;
+/**
+ * Construct a globally unique name by using the requested name if possible
+ * and appending a number suffix necessary
+ */
+declare function minimallyMangledName(proposedName: string, globalNames: Set<string>): string;
+//#endregion
+//#region src/ParsedRegistry.d.ts
+interface ParsedRegistry {
+  modules: Record<string, WeslAST>;
+}
+declare function parsedRegistry(): ParsedRegistry;
+/** for debug */
+declare function registryToString(registry: ParsedRegistry): string;
+/** Look up a module with a flexible selector.
+ *    :: separated module path,   package::util
+ *    / separated file path       ./util.wesl (or ./util)
+ *          - note: a file path should not include a weslRoot prefix, e.g. not ./shaders/util.wesl
+ *    simpleName                  util
+ */
+declare function selectModule(parsed: ParsedRegistry, selectPath: string, packageName?: string): WeslAST | undefined;
+/**
+ * @param srcFiles    map of source strings by file path
+ *                    key is '/' separated relative path (relative to srcRoot, not absolute file path )
+ *                    value is wesl source string
+ * @param registry    add parsed modules to this registry
+ * @param packageName name of package
+ */
+declare function parseIntoRegistry(srcFiles: Record<string, string>, registry: ParsedRegistry, packageName?: string, debugWeslRoot?: string): void;
+declare function parseLibsIntoRegistry(libs: WeslBundle[], registry: ParsedRegistry): void;
+//#endregion
+//#region src/WeslBundle.d.ts
+interface WeslBundle {
+  /** name of the package, e.g. random_wgsl */
+  name: string;
+  /** wesl edition of the code e.g. unstable_2025_1 */
+  edition: string;
+  /** map of wesl/wgsl modules:
+   *    keys are file paths, relative to package root (e.g. "./lib.wgsl")
+   *    values are wgsl/wesl code strings
+   */
+  modules: Record<string, string>;
+  /** packages referenced by this package */
+  dependencies?: WeslBundle[];
+}
+//#endregion
+//#region src/Linker.d.ts
+type LinkerTransform = (boundAST: TransformedAST) => TransformedAST;
+interface WeslJsPlugin {
+  transform?: LinkerTransform;
+}
+interface TransformedAST extends Pick<WeslAST, "srcModule" | "moduleElem"> {
+  globalNames: Set<string>;
+  notableElems: Record<string, AbstractElem[]>;
+}
+interface LinkConfig {
+  plugins?: WeslJsPlugin[];
+}
+interface LinkParams {
+  /** record of file paths and wesl text for modules.
+   *   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.
+   */
+  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)
+   */
+  rootModuleName?: string;
+  /** For debug logging. Will be prepended to file paths. */
+  debugWeslRoot?: string;
+  /** runtime conditions for conditional compiling with @if and friends */
+  conditions?: Conditions;
+  /** libraries available for the link */
+  libs?: WeslBundle[];
+  /** generate wesl from code at runtime */
+  virtualLibs?: Record<string, VirtualLibraryFn>;
+  /** plugins and other configuration to use while linking */
+  config?: LinkConfig;
+  /** Host (ts/js) provided wgsl constants.
+   * Users can import the values from wesl code via the `constants' virtual library:
+   *  `import constants::num_lights;` */
+  constants?: Record<string, string | number>;
+  /** function to construct globally unique wgsl identifiers */
+  mangler?: ManglerFn;
+}
+/** Generate a virtual WESL module based on a set of conditions. */
+type VirtualLibraryFn = (conditions: Conditions) => string;
+/**
+ * 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
+ * referenced from other modules (in local files or libraries).
+ *
+ * Unreferenced (dead) code outside the root module is not included in the output WGSL.
+ * Additionally the caller can specify conditions for to control conditional compilation.
+ * Only code that is valid with the current conditions is included in the output.
+ */
+declare function link(params: LinkParams): Promise<LinkedWesl>;
+/** linker api for benchmarking */
+declare function _linkSync(params: LinkParams): LinkedWesl;
+interface LinkRegistryParams extends Pick<LinkParams, "rootModuleName" | "conditions" | "virtualLibs" | "config" | "constants" | "mangler"> {
+  registry: ParsedRegistry;
+}
+/** Link wesl from a registry of already parsed modules.
+ *
+ * This entry point is intended for users who want to link multiple times
+ * from the same sources. (e.g. linking with different conditions
+ * each time, or perhaps to produce multiple wgsl shaders
+ * that share some sources.)
+ */
+declare function linkRegistry(params: LinkRegistryParams): SrcMap;
+interface BoundAndTransformed {
+  transformedAst: TransformedAST;
+  newDecls: DeclIdent[];
+  newStatements: EmittableElem[];
+}
+/** bind identifers and apply any transform plugins */
+declare function bindAndTransform(params: LinkRegistryParams): BoundAndTransformed;
+//#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 */
+interface BindResults {
+  /** root level names (including names mangled due to conflict with earlier names) */
+  globalNames: Set<string>;
+  /** global declarations that were referenced (these will need to be emitted in the link) */
+  decls: DeclIdent[];
+  /** additional global statements to include in linked results
+   * (e.g. for adding module level const_assert statements) */
+  newStatements: EmittableElem[];
+  /** if accumulateUnbound is true, collection of unbound module paths */
+  unbound?: string[][];
+}
+/** an element that can be directly emitted into the linked result */
+interface EmittableElem {
+  srcModule: SrcModule;
+  elem: AbstractElem;
+}
+/** virtual package, generated by code generation function. */
+interface VirtualLibrary {
+  /** function to generate the module */
+  fn: VirtualLibraryFn;
+  /** parsed AST for the module (constructed lazily) */
+  ast?: WeslAST;
+}
+/** key is virtual module name */
+type VirtualLibrarySet = Record<string, VirtualLibrary>;
+interface BindIdentsParams extends Pick<LinkRegistryParams, "registry" | "conditions" | "mangler"> {
+  rootAst: WeslAST;
+  virtuals?: VirtualLibrarySet;
+  /** if false, throw on unbound identifiers. If true, accumulate unbound identifiers into
+   * a BindResults.unbound.  */
+  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)
+ */
+declare function bindIdents(params: BindIdentsParams): BindResults;
+/** bind local references in library sources to reveal references to external packages */
+declare function findUnboundIdents(registry: ParsedRegistry): string[][];
+/**
+ * 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
+ */
+declare function findValidRootDecls(rootScope: Scope, conditions: Conditions): DeclIdent[];
+/** 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;
+//#endregion
+//#region src/debug/ASTtoString.d.ts
+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 */
+declare function scopeToString(scope: Scope, indent?: number, shortIdents?: boolean): string;
+/** A debug print of the scope tree with identifiers in long form in nested brackets */
+declare function scopeToStringLong(scope: Scope): string;
+declare function identToString(ident?: Ident): string;
+//#endregion
+//#region src/PathUtil.d.ts
+/** simplistic path manipulation utilities */
+/** return path with ./ and foo/.. elements removed */
+declare function normalize(path: string): string;
+/** return path w/o a suffix.
+ * e.g. /foo/bar.wgsl => /foo/bar */
+declare function noSuffix(path: string): string;
+//#endregion
+//#region src/parse/WeslStream.d.ts
+type WeslTokenKind = "word" | "keyword" | "number" | "symbol";
+type WeslToken<Kind extends WeslTokenKind = WeslTokenKind> = TypedToken<Kind>;
+/** A stream that produces WESL tokens, skipping over comments and white space */
+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;
+  private skipToEol;
+  private skipBlockComment;
+  /**
+   * Only matches the `<` token if it is a template
+   * Precondition: An ident was parsed right before this.
+   * Runs the [template list discovery algorithm](https://www.w3.org/TR/WGSL/#template-list-discovery).
+   */
+  nextTemplateStartToken(): (WeslToken & {
+    kind: "symbol";
+  }) | null;
+  nextTemplateEndToken(): (WeslToken & {
+    kind: "symbol";
+  }) | null;
+  isTemplateStart(afterToken: number): boolean;
+  /**
+   * Call this after consuming an opening bracket.
+   * Skips until a closing bracket. This also consumes the closing bracket.
+   */
+  skipBracketsTo(closingBracket: string): void;
+}
+//#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
+ * replaced strings must be 'tokens', surrounded by spaces or punctuation
+ */
+declare function replaceWords(text: string, replace: Record<string, string>): string;
+/** return an array partitioned into possibly overlapping groups */
+declare function grouped<T>(a: T[], size: number, stride?: number): T[][];
+/** group an array into subarrays by a key function */
+declare function groupBy<T, K>(a: T[], key: (t: T) => K): Map<K, T[]>;
+/** partition an array into two parts by a discriminator function */
+declare function partition<T>(a: T[], partFn: (t: T) => boolean): [T[], T[]];
+/** run an carrying function over every element in an array,
+ * i.e. an inclusive prefix scan */
+declare function scan<T, U>(array: T[], fn: (a: T, b: U) => U, zero: U): U[];
+/** return a new record by replacing values in 'a' with 'b' as a map.
+ * values in 'a' that are not in 'b' are unchanged.
+ * e.g. {a: "b", x: 9}, {b: 1} yields {a: 1, x: 9}
+ */
+declare function mapForward(a: Record<string, string>, b: Record<string, any>): Record<string, any>;
+/** return the last element of an array or undefined */
+declare function last<T>(a: T[]): T | undefined;
+/**
+ * Overlap two arrays, returning the tail of b if a is a prefix of b.
+ * Otherwise, return undefined.
+ */
+declare function overlapTail<T>(a: T[], b: T[]): T[] | undefined;
+/** filter an array, returning the truthy results of the filter function */
+declare function filterMap<T, U>(arr: T[], fn: (t: T) => U | undefined): U[];
+/** filters an array, returns the first truthy result of the filter function */
+declare function findMap<T, U>(arr: T[], fn: (t: T) => U | undefined): U | undefined;
+/** Run a function over the values in a Record
+ * @return a new Record with mapped values.  */
+declare function mapValues<T, U>(obj: Record<string, T>, fn: (v: T) => U): Record<string, U>;
+/**
+ * Maps an character position in a string to a 1-indexed line number, and 1-indexed column.
+ */
+declare function offsetToLineNumber(offset: number, text: string): [lineNum: number, linePos: number];
+/** Highlights an error.
+ *
+ * Returns a string with the line, and a string with the ^^^^ carets
+ */
+declare function errorHighlight(source: string, span: Span): [string, string];
+//#endregion
+export { AbstractElem, AbstractElemBase, AliasElem, Attribute, AttributeElem, BinaryExpression, BinaryOperator, BindIdentsParams, BindResults, BindingAST, BindingStructElem, BoundAndTransformed, BuiltinAttribute, ComponentExpression, ComponentMemberExpression, 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, ManglerFn, ModuleElem, NameElem, OverrideElem, ParenthesizedExpression, ParsedRegistry, PartialScope, 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, bindingStructsPlugin, blankWeslParseState, childIdent, childScope, containsScope, debugContentsToString, emptyScope, errorHighlight, filterMap, findMap, findRefsToBindingStructs, findUnboundIdents, findValidRootDecls, flatImports, groupBy, grouped, identToString, isGlobal, last, lengthPrefixMangle, link, linkRegistry, lowerBindingStructs, makeWeslDevice, mapForward, mapValues, markBindingStructs, markEntryTypes, mergeScope, minimalMangle, minimallyMangledName, multiKeySet, nextIdentId, noSuffix, normalize, offsetToLineNumber, overlapTail, parseIntoRegistry, parseLibsIntoRegistry, parseSrcModule, parsedRegistry, partition, publicDecl, registryToString, replaceWords, requestWeslDevice, resetScopeIds, scan, scopeToString, scopeToStringLong, selectModule, syntheticWeslParseState, transformBindingReference, transformBindingStruct, underscoreMangle };