wesl 0.7.26 → 0.7.28

package/src/parse/ParseStatement.ts

@@ -1,14 +1,11 @@
 import type {
   AttributeElem,
-  BlockStatement,
-  ContinuingElem,
-  ElifAttribute,
-  ElseAttribute,
-  IfAttribute,
-  StatementElem,
+  BlockElem,
+  ElemKindMap,
+  HasAttributes,
+  Statement,
 } from "../AbstractElems.ts";
 import { findMap } from "../Util.ts";
-import { beginElem, finishElem } from "./ContentsHelpers.ts";
 import { parseAttributeList } from "./ParseAttribute.ts";
 import { parseIfStatement, parseSwitchStatement } from "./ParseControlFlow.ts";
 import { parseConstAssert } from "./ParseGlobalVar.ts";
@@ -22,16 +19,15 @@ import {
 import { parseSimpleStatement } from "./ParseSimpleStatement.ts";
 import {
   attachAttributes,
+  attrsOrUndef,
+  conditionalAttribute,
   expect,
   hasConditionalAttribute,
-  isConditionalAttribute,
   throwParseError,
 } from "./ParseUtil.ts";
 import { parseConstDecl } from "./ParseValueDeclaration.ts";
 import type { ParsingContext } from "./ParsingContext.ts";
 
-type CondAttr = IfAttribute | ElifAttribute | ElseAttribute;
-
 interface CompoundOptions {
   loopBody?: boolean;
   noScope?: boolean; // for function bodies (scope shared with params)
@@ -39,11 +35,11 @@ interface CompoundOptions {
 
 // Experimental: declarations in conditional blocks visible in outer scope.
 // e.g. @if(X) { let y = 1; } makes y visible outside the block.
-// see https://github.com/wgsl-tooling-wg/wesl-spec/issues/158
+// see https://github.com/webgpu-tools/wesl-spec/issues/158
 const conditionalBlockFeature = true;
 
 /** Function bodies share scope with parameters (per WGSL spec). */
-export function parseFunctionBody(ctx: ParsingContext): StatementElem | null {
+export function parseFunctionBody(ctx: ParsingContext): BlockElem | null {
   return parseCompoundStatement(ctx, undefined, { noScope: true });
 }
 
@@ -55,22 +51,20 @@ export function parseCompoundStatement(
   ctx: ParsingContext,
   attributes?: AttributeElem[],
   options?: CompoundOptions,
-): StatementElem | null {
+): BlockElem | null {
   const brace = ctx.stream.matchText("{");
   if (!brace) return null;
 
   const startPos = getStartWithAttributes(attributes, brace.span[0]);
 
-  beginElem(ctx, "statement", attributes);
-
   const skipScope =
     options?.noScope ||
     (conditionalBlockFeature && hasConditionalAttr(attributes));
   if (!skipScope) ctx.pushScope();
-  parseBlockStatements(ctx, options?.loopBody);
+  const body = parseBlockStatements(ctx, options?.loopBody);
   if (!skipScope) ctx.popScope();
 
-  return finishBlockStatement(startPos, ctx, attributes);
+  return finishStatement("block", startPos, ctx, { body }, attributes);
 }
 
 /** Grammar: attribute* compound_statement (for control flow bodies) */
@@ -78,11 +72,10 @@ export function expectCompound(
   ctx: ParsingContext,
   errorMsg: string,
   loopBody?: boolean,
-): StatementElem {
+): BlockElem {
   const attrs = parseAttributeList(ctx);
-  const attrsOrUndef = attrs.length > 0 ? attrs : undefined;
   const options = loopBody ? { loopBody } : undefined;
-  const block = parseCompoundStatement(ctx, attrsOrUndef, options);
+  const block = parseCompoundStatement(ctx, attrsOrUndef(attrs), options);
   if (!block) throwParseError(ctx.stream, errorMsg);
   return block;
 }
@@ -95,40 +88,30 @@ export function getStartWithAttributes(
   return attributes?.[0]?.start ?? keywordPos;
 }
 
-/** Match keyword and begin statement element. Returns start position or null. */
+/** Match keyword and return the statement's start position (or null if no match). */
 export function beginStatement(
   ctx: ParsingContext,
   keyword: string,
   attributes?: AttributeElem[],
-  kind: "statement" | "continuing" = "statement",
 ): number | null {
-  const keywordPos = ctx.stream.checkpoint();
-  if (!ctx.stream.matchText(keyword)) return null;
-  const startPos = getStartWithAttributes(attributes, keywordPos);
-  beginElem(ctx, kind, attributes);
-  return startPos;
+  const token = ctx.stream.matchText(keyword);
+  if (!token) return null;
+  // Start at the keyword token, not any leading comment, so a preceding comment
+  // falls in the gap before the statement and attaches as leading.
+  return getStartWithAttributes(attributes, token.span[0]);
 }
 
-/** Finish block statement element: close contents, attach attributes. */
-export function finishBlockStatement(
-  start: number,
-  ctx: ParsingContext,
-  attributes?: AttributeElem[],
-): StatementElem;
-export function finishBlockStatement(
-  start: number,
-  ctx: ParsingContext,
-  attributes: AttributeElem[] | undefined,
-  kind: "continuing",
-): ContinuingElem;
-export function finishBlockStatement(
+/** Build a statement element from its typed fields and attach its attributes. */
+export function finishStatement<K extends keyof ElemKindMap>(
+  kind: K,
   start: number,
   ctx: ParsingContext,
+  params: Omit<ElemKindMap[K], "kind" | "start" | "end">,
   attributes?: AttributeElem[],
-  kind: "statement" | "continuing" = "statement",
-): BlockStatement {
-  const elem = finishElem(kind, start, ctx, {});
-  attachAttributes(elem, attributes);
+): ElemKindMap[K] {
+  const end = ctx.stream.checkpoint();
+  const elem = { kind, start, end, ...params } as ElemKindMap[K];
+  attachAttributes(elem as HasAttributes, attributes);
   return elem;
 }
 
@@ -137,18 +120,23 @@ function hasConditionalAttr(attributes?: AttributeElem[]): boolean {
 }
 
 /** Grammar: statement* '}' (after '{' consumed). Loop bodies may end with continuing. */
-function parseBlockStatements(ctx: ParsingContext, loopBody?: boolean): void {
+function parseBlockStatements(
+  ctx: ParsingContext,
+  loopBody?: boolean,
+): Statement[] {
   const { stream } = ctx;
+  const body: Statement[] = [];
   while (true) {
     if (stream.matchText("}")) break;
     const stmt = parseStatement(ctx);
     if (!stmt) throwParseError(stream, "Expected statement or '}'");
-    ctx.addElem(stmt);
+    body.push(stmt);
     if (loopBody && stmt.kind === "continuing") {
       expect(stream, "}", "continuing block");
       break;
     }
   }
+  return body;
 }
 
 /**
@@ -159,7 +147,7 @@ function parseBlockStatements(ctx: ParsingContext, loopBody?: boolean): void {
  *   | 'discard' ';' | variable_updating_statement ';' | compound_statement
  *   | const_assert_statement ';'
  */
-function parseStatement(ctx: ParsingContext): BlockStatement | null {
+function parseStatement(ctx: ParsingContext): Statement | null {
   const { stream } = ctx;
   const startPos = stream.checkpoint();
   const attributes = parseAttributeList(ctx);
@@ -174,7 +162,6 @@ function parseStatement(ctx: ParsingContext): BlockStatement | null {
     attributes.length > 0 && hasConditionalAttribute(attributes);
   if (hasConditional) ctx.pushScope("partial");
 
-  const attrsOrUndef = attributes.length > 0 ? attributes : undefined;
   const parsers = [
     parseLocalVarDecl,
     parseLetDecl,
@@ -189,27 +176,13 @@ function parseStatement(ctx: ParsingContext): BlockStatement | null {
     parseContinuingStatement,
     parseSimpleStatement,
   ];
-  const stmt = findMap(parsers, p => p(ctx, attrsOrUndef));
-  if (!stmt) return null;
-
-  finalizeConditional(ctx, hasConditional, attributes);
-  return stmt as BlockStatement;
-}
+  const stmt = findMap(parsers, p => p(ctx, attrsOrUndef(attributes)));
 
-function finalizeConditional(
-  ctx: ParsingContext,
-  hasConditional: boolean,
-  attributes: AttributeElem[],
-): void {
+  // Always pop the partial scope we pushed, even on the no-match path, so the
+  // scope stack stays balanced; only a matched statement gets the condition.
   if (hasConditional) {
     const partialScope = ctx.popScope();
-    partialScope.condAttribute = getConditionalAttribute(attributes);
+    if (stmt) partialScope.condAttribute = conditionalAttribute(attributes);
   }
-}
-
-function getConditionalAttribute(
-  attributes: AttributeElem[],
-): CondAttr | undefined {
-  const found = attributes.find(a => isConditionalAttribute(a.attribute));
-  return found?.attribute as CondAttr | undefined;
+  return stmt ? (stmt as Statement) : null;
 }

package/src/parse/ParseStruct.ts

@@ -3,12 +3,11 @@ import type {
   StructElem,
   StructMemberElem,
 } from "../AbstractElems.ts";
-import { beginElem, finishElem } from "./ContentsHelpers.ts";
 import { parseAttributeList } from "./ParseAttribute.ts";
-import { getStartWithAttributes } from "./ParseStatement.ts";
+import { finishStatement, getStartWithAttributes } from "./ParseStatement.ts";
 import { parseSimpleTypeRef } from "./ParseType.ts";
 import {
-  attachAttributes,
+  attrsOrUndef,
   createDeclIdentElem,
   expect,
   expectWord,
@@ -37,53 +36,40 @@ export function parseStructDecl(
   const identElem = createDeclIdentElem(ctx, nameToken, true);
   ctx.saveIdent(identElem.ident);
 
-  beginElem(ctx, "struct", attributes);
-  ctx.addElem(identElem);
   expect(stream, "{", "struct name");
 
   ctx.pushScope();
-  const members = parseStructMembers(ctx);
+  const members = parseCommaList(ctx, parseStructMember);
   identElem.ident.dependentScope = ctx.currentScope();
   ctx.popScope();
 
   expect(stream, "}", "struct member");
 
-  const elem = finishElem("struct", start, ctx, { name: identElem, members });
-  attachAttributes(elem, attributes);
+  const params = { name: identElem, members };
+  const elem = finishStatement("struct", start, ctx, params, attributes);
   linkDeclIdentElem(identElem, elem);
   return elem;
 }
 
-/** Grammar: struct_body_decl : '{' struct_member (',' struct_member)* ','? '}' */
-function parseStructMembers(ctx: ParsingContext): StructMemberElem[] {
-  const members = parseCommaList(ctx, parseStructMember);
-  for (const member of members) ctx.addElem(member);
-  return members;
-}
-
 /** Grammar: struct_member : attribute* member_ident ':' type_specifier */
 function parseStructMember(ctx: ParsingContext): StructMemberElem | null {
   const { stream } = ctx;
   const checkpoint = stream.checkpoint();
-  const attributes = parseAttributeList(ctx);
+  const attrs = parseAttributeList(ctx);
 
   const nameToken = stream.matchKind("word");
   if (!nameToken) {
     stream.reset(checkpoint);
     return null;
   }
+  const attributes = attrsOrUndef(attrs);
 
   const start = getStartWithAttributes(attributes, nameToken.span[0]);
-  beginElem(ctx, "member", attributes.length ? attributes : undefined);
   const name = makeNameElem(nameToken);
-  ctx.addElem(name);
   expect(stream, ":", "struct member name");
 
   const typeRef = parseSimpleTypeRef(ctx);
   if (!typeRef) throwParseError(stream, "Expected type after ':'");
-  ctx.addElem(typeRef);
 
-  const elem = finishElem("member", start, ctx, { name, typeRef });
-  attachAttributes(elem, attributes.length ? attributes : undefined);
-  return elem;
+  return finishStatement("member", start, ctx, { name, typeRef }, attributes);
 }

package/src/parse/ParseType.ts

@@ -1,5 +1,4 @@
 import type { TypeRefElem, TypeTemplateParameter } from "../AbstractElems.ts";
-import { beginElem, finishElem } from "./ContentsHelpers.ts";
 import { parseExpression } from "./ParseExpression.ts";
 import { parseModulePath } from "./ParseIdent.ts";
 import { makeRefIdentElem, throwParseError } from "./ParseUtil.ts";
@@ -18,17 +17,15 @@ export function parseSimpleTypeRef(ctx: ParsingContext): TypeRefElem | null {
   const { parts, start, end: nameEnd } = path;
   const refIdent = ctx.createRefIdent(parts.join("::"));
 
-  beginElem(ctx, "type");
-
-  const refIdentElem = makeRefIdentElem(ctx, refIdent, start, nameEnd);
+  makeRefIdentElem(ctx, refIdent, start, nameEnd);
   ctx.saveIdent(refIdent);
-  ctx.addElem(refIdentElem);
 
   const templateParams = ctx.stream.nextTemplateStartToken()
     ? parseTemplateParams(ctx)
     : undefined;
 
-  return finishElem("type", start, ctx, { name: refIdent, templateParams });
+  const end = ctx.stream.checkpoint();
+  return { kind: "type", name: refIdent, templateParams, start, end };
 }
 
 /** Parse comma-separated template parameters until closing '>'. */
@@ -37,16 +34,15 @@ export function parseTemplateParams(
 ): TypeTemplateParameter[] {
   const { stream } = ctx;
 
-  // Handle empty template <>
-  if (consumeTemplateEnd(stream)) return [];
+  if (consumeTemplateEnd(stream)) {
+    throwParseError(stream, "Empty template parameter list '<>'");
+  }
 
-  // Parse comma-separated params
-  const params: TypeTemplateParameter[] = [parseTemplateParam(ctx)];
+  const params = [parseTemplateParam(ctx)];
   while (stream.matchText(",")) {
     params.push(parseTemplateParam(ctx));
   }
 
-  // Must end with >
   if (!consumeTemplateEnd(stream))
     throwParseError(stream, "Expected '>' or ',' after template parameter");
 
@@ -66,6 +62,7 @@ function parseTemplateParam(ctx: ParsingContext): TypeTemplateParameter {
   // parseExpression handles template_elaborated_ident via parsePrimaryExpr
   // inTemplate prevents '>' from being parsed as comparison operator
   const expr = parseExpression(ctx, { inTemplate: true });
-  if (expr) return expr;
-  throwParseError(ctx.stream, "Expected expression in template parameters");
+  if (!expr)
+    throwParseError(ctx.stream, "Expected expression in template parameters");
+  return expr;
 }

package/src/parse/ParseUtil.ts

@@ -1,6 +1,7 @@
 import type {
   Attribute,
   AttributeElem,
+  ConditionalAttribute,
   DeclarationElem,
   DeclIdentElem,
   ExpressionElem,
@@ -11,12 +12,10 @@ import type {
 import { ParseError } from "../ParseError.ts";
 import type { RefIdent } from "../Scope.ts";
 import type { Stream, Token } from "../Stream.ts";
-import { parseExpression } from "./ParseExpression.ts";
+import { type ExpressionOpts, parseExpression } from "./ParseExpression.ts";
 import type { ParsingContext } from "./ParsingContext.ts";
 import type { WeslStream, WeslToken } from "./WeslStream.ts";
 
-// --- Stream/token expectations ---
-
 /** Match text and throw ParseError if not found. */
 export function expect(
   stream: WeslStream,
@@ -47,17 +46,24 @@ export function expectWord(
   return token as WeslToken<"word">;
 }
 
-/** Parse expression and throw ParseError if not found. */
+/** Parse a required expression, throwing if absent. */
 export function expectExpression(
   ctx: ParsingContext,
   errorMsg = "Expected expression",
 ): ExpressionElem {
   const expr = parseExpression(ctx);
   if (!expr) throwParseError(ctx.stream, errorMsg);
-  if (ctx.options.preserveExpressions) ctx.addElem(expr);
   return expr;
 }
 
+/** Parse an optional expression. */
+export function parseContentExpression(
+  ctx: ParsingContext,
+  opts?: ExpressionOpts,
+): ExpressionElem | null {
+  return parseExpression(ctx, opts);
+}
+
 /** Throw a ParseError at the current/next token position. */
 export function throwParseError(stream: Stream<Token>, message: string): never {
   const weslStream = stream as WeslStream;
@@ -68,8 +74,6 @@ export function throwParseError(stream: Stream<Token>, message: string): never {
   throw new ParseError(message, span);
 }
 
-// --- List parsing ---
-
 /** Parse comma-separated items. Caller handles delimiters. */
 export function parseCommaList<T>(
   ctx: ParsingContext,
@@ -93,8 +97,6 @@ export function* parseMany<T>(
   for (let elem = parse(ctx); elem; elem = parse(ctx)) yield elem;
 }
 
-// --- Element creation ---
-
 /** Create a NameElem from a word token. */
 export function makeNameElem(token: WeslToken<"word">): NameElem {
   const [start, end] = token.span;
@@ -136,8 +138,7 @@ export function makeRefIdentElem(
   return elem;
 }
 
-// --- Attribute utilities ---
-
+/** @return true if the attribute is a conditional (@if, @elif, @else) */
 export function isConditionalAttribute(attr: Attribute): boolean {
   const { kind } = attr;
   return kind === "@if" || kind === "@elif" || kind === "@else";
@@ -148,6 +149,14 @@ export function hasConditionalAttribute(attributes: AttributeElem[]): boolean {
   return attributes.some(attr => isConditionalAttribute(attr.attribute));
 }
 
+/** The first conditional (@if, @elif, @else) attribute in the list, if any. */
+export function conditionalAttribute(
+  attributes: AttributeElem[],
+): ConditionalAttribute | undefined {
+  const found = attributes.find(a => isConditionalAttribute(a.attribute));
+  return found?.attribute as ConditionalAttribute | undefined;
+}
+
 /** Attach non-empty attributes array to element. */
 export function attachAttributes<T extends { attributes?: AttributeElem[] }>(
   elem: T,
@@ -156,7 +165,12 @@ export function attachAttributes<T extends { attributes?: AttributeElem[] }>(
   if (attributes?.length) elem.attributes = attributes;
 }
 
-// --- Declaration linking ---
+/** Normalize an empty attribute list to undefined (the elem's "no attributes"). */
+export function attrsOrUndef(
+  attrs: AttributeElem[],
+): AttributeElem[] | undefined {
+  return attrs.length ? attrs : undefined;
+}
 
 /** Link a DeclIdentElem's ident to its parent declaration. */
 export function linkDeclIdentElem(

package/src/parse/ParseValueDeclaration.ts

@@ -2,16 +2,15 @@ import type {
   AttributeElem,
   ConstElem,
   ElemKindMap,
+  ExpressionElem,
   OverrideElem,
   TypedDeclElem,
   TypeRefElem,
 } from "../AbstractElems.ts";
 import type { Scope } from "../Scope.ts";
-import { beginElem, finishContents } from "./ContentsHelpers.ts";
-import { getStartWithAttributes } from "./ParseStatement.ts";
+import { finishStatement, getStartWithAttributes } from "./ParseStatement.ts";
 import { parseSimpleTypeRef } from "./ParseType.ts";
 import {
-  attachAttributes,
   createDeclIdentElem,
   expect,
   expectExpression,
@@ -27,7 +26,7 @@ export function parseConstDecl(
   ctx: ParsingContext,
   attributes?: AttributeElem[],
 ): ConstElem | null {
-  return parseValueDecl(ctx, "const", true, isModuleScope(ctx), attributes);
+  return parseValueDecl(ctx, "const", true, ctx.isModuleScope(), attributes);
 }
 
 /** Grammar: 'override' optionally_typed_ident ( '=' expression )? */
@@ -47,16 +46,13 @@ export function parseTypedDecl(
   if (!nameToken) return null;
   const start = nameToken.span[0];
 
-  beginElem(ctx, "typeDecl");
   const decl = createDeclIdentElem(ctx, nameToken, isGlobal);
-  ctx.addElem(decl);
   ctx.saveIdent(decl.ident);
 
   const { typeRef, typeScope } = parseOptionalType(ctx);
 
   const end = ctx.stream.checkpoint();
-  const contents = finishContents(ctx, start, end);
-  return { kind: "typeDecl", decl, typeRef, typeScope, start, end, contents };
+  return { kind: "typeDecl", decl, typeRef, typeScope, start, end };
 }
 
 /** Shared parser for const/override declarations. */
@@ -73,44 +69,36 @@ function parseValueDecl<K extends ValueDeclKind>(
 
   const startPos = getStartWithAttributes(attributes, token.span[0]);
   ctx.pushScope("partial");
-  beginElem(ctx, keyword, attributes);
 
   const typedDecl = parseTypedDecl(ctx, isGlobal);
   if (!typedDecl)
     throwParseError(stream, `Expected identifier after '${keyword}'`);
-  ctx.addElem(typedDecl);
 
+  let init: ExpressionElem | undefined;
   if (requiresInit) {
     expect(stream, "=", `${keyword} identifier`);
-    expectExpression(ctx);
+    init = expectExpression(ctx);
   } else if (stream.matchText("=")) {
-    expectExpression(ctx);
+    init = expectExpression(ctx);
   }
 
   expect(stream, ";", `${keyword} declaration`);
 
-  const endPos = stream.checkpoint();
-  const contents = finishContents(ctx, startPos, endPos);
   typedDecl.decl.ident.dependentScope = ctx.currentScope();
   ctx.popScope();
 
-  const elem: ConstElem | OverrideElem = {
-    kind: keyword,
-    name: typedDecl,
-    start: startPos,
-    end: endPos,
-    contents,
-  };
-  attachAttributes(elem, attributes);
+  // const/override share these fields; cast keyword to the union so the params
+  // type-check against the concrete elems rather than the opaque generic K.
+  const fields = { name: typedDecl, init };
+  const elem = finishStatement(
+    keyword as ValueDeclKind,
+    startPos,
+    ctx,
+    fields,
+    attributes,
+  ) as ElemKindMap[K];
   linkDeclIdent(typedDecl, elem);
-  return elem as ElemKindMap[K];
-}
-
-/** @return true if ctx is at module level (not inside fn/block) */
-function isModuleScope(ctx: ParsingContext): boolean {
-  let scope = ctx.currentScope();
-  while (scope.kind === "partial" && scope.parent) scope = scope.parent;
-  return scope.parent === null;
+  return elem;
 }
 
 /** Parse optional ': type' annotation, managing scope for type references. */
@@ -123,7 +111,6 @@ function parseOptionalType(ctx: ParsingContext): {
   ctx.pushScope();
   const typeRef = parseSimpleTypeRef(ctx);
   if (!typeRef) throwParseError(ctx.stream, "Expected type after ':'");
-  ctx.addElem(typeRef);
   const typeScope = ctx.currentScope();
   ctx.popScope();
   return { typeRef, typeScope };

package/src/parse/ParseWesl.ts

@@ -4,8 +4,8 @@ import type { WeslAST, WeslParseState } from "../ParseWESL.ts";
 import { WeslParseError } from "../ParseWESL.ts";
 import type { SrcModule } from "../Scope.ts";
 import { emptyScope } from "../Scope.ts";
-import { beginElem, finishContents } from "./ContentsHelpers.ts";
-import { parseModule } from "./ParseModule.ts";
+import { attachComments } from "./AttachComments.ts";
+import { checkDoBlockNames, parseModule } from "./ParseModule.ts";
 import { type ParseOptions, ParsingContext } from "./ParsingContext.ts";
 import { WeslStream } from "./WeslStream.ts";
 
@@ -16,10 +16,10 @@ export function parseWesl(
 ): WeslAST {
   const { ctx, state } = createParseState(srcModule, options);
   try {
-    beginElem(ctx, "module");
     parseModule(ctx);
-    const moduleElem = state.stable.moduleElem;
-    moduleElem.contents = finishContents(ctx, 0, moduleElem.end);
+    const { moduleElem } = state.stable;
+    attachComments(ctx, moduleElem);
+    checkDoBlockNames(moduleElem);
     return state.stable;
   } catch (e) {
     if (e instanceof ParseError) {
@@ -35,23 +35,20 @@ export function parseWesl(
 /** Initialize parse state: token stream, root scope, and module element. */
 function createParseState(
   srcModule: SrcModule,
-  options?: ParseOptions,
-): {
-  ctx: ParsingContext;
-  state: WeslParseState;
-} {
+  parseOptions?: ParseOptions,
+): { ctx: ParsingContext; state: WeslParseState } {
   const stream = new WeslStream(srcModule.src);
   const rootScope = emptyScope(null);
   const moduleElem: ModuleElem = {
     kind: "module",
-    contents: [],
+    decls: [],
     start: 0,
     end: srcModule.src.length,
   };
   const state: WeslParseState = {
-    context: { scope: rootScope, openElems: [] },
-    stable: { srcModule, moduleElem, rootScope, imports: [] },
+    context: { scope: rootScope },
+    stable: { srcModule, moduleElem, rootScope, imports: [], parseOptions },
   };
-  const ctx = new ParsingContext(stream, state, options);
+  const ctx = new ParsingContext(stream, state, parseOptions);
   return { ctx, state };
 }

package/src/parse/ParsingContext.ts

@@ -11,10 +11,15 @@ import {
 } from "../Scope.ts";
 import type { WeslStream } from "./WeslStream.ts";
 
+/** Opt-in toggles for not-yet-spec'd WESL/WGSL features (for prototyping). */
+export interface WeslExtensions {
+  /** Parse `do name(...) { ... }` blocks. */
+  doBlocks?: boolean;
+}
+
 export interface ParseOptions {
-  /** Store expression AST nodes in statement contents (for tooling/validation). */
-  // LATER we'll always store expressions in the AST, (but this partial support is for wgsl-edit validation)
-  preserveExpressions?: boolean;
+  /** Enable parsing of experimental, not-yet-spec'd syntax extensions. */
+  weslExtensions?: WeslExtensions;
 }
 
 /** Context for parsers to build AST and manage scopes. */
@@ -45,12 +50,9 @@ export class ParsingContext {
     return this.state.context.scope;
   }
 
-  addElem(elem: AbstractElem): void {
-    const { openElems } = this.state.context;
-    if (openElems.length > 0) {
-      const open = openElems[openElems.length - 1];
-      open.contents.push(elem);
-    }
+  /** Append a top-level declaration to the module, in source order. */
+  addModuleDecl(elem: AbstractElem): void {
+    this.state.stable.moduleElem.decls.push(elem);
   }
 
   pushScope(kind: Scope["kind"] = "scope"): void {