wgsl.run

Diagnostics, hover, go-to-definition, references, rename, scope-aware completions, signature help, outline, folding, quick fixes, canonical formatting, semantic highlighting — plus a CPU-interpreter kernel debugger, an optimization advisor, an ML-kernel analyzer, and WGSL→MSL translation. Every semantic decision flows from a wasm-compiled libwgsl frontend — the same spec-conformant pipeline that ships as a C library.

v2.0 status

Design — wasm first, TS minimum

Conventional WGSL extensions ship a TextMate grammar (regex-driven) for instant offline coloring, then layer LSP semantic tokens on top. This extension deliberately omits the regex grammar — every coloured byte, every completion, every quick fix comes from the wasm frontend.

• one source of truth for what every identifier means;
• the engine that produces diagnostics also produces highlights, completions, and quick fixes, so they can never disagree;
• what you see in the editor is exactly what wgsl_check reports to any C / wasm consumer downstream.

language-configuration.json is the only declarative metadata (bracket pairs, comment markers) — purely editing UX. No grammar.

Architecture

        (wasm bundle)                (official JS binding)
   wgsl_compiler.{js,wasm}   +   wasm/wgsl.js  (ABI-table offsets)
            │
            ▼  WGSL facade (src/client.ts)
            │    core: check/diag/hover/def/tokens/format/interp/…
            │    extras: sessions, symbols, refs, rename, folding,
            │            completions, signature help, code actions,
            │            wgslconfig.toml project API
            ▼
   DocumentCompiler  ── for each .wgsl document:
            │            1. resolve preamble (wgslconfig.toml or _shared.wgsl)
            │            2. split on `// --- KERNEL: <name> ---`
            │            3. build N synthetic sources:
            │                 preamble ++ file_preamble ++ section_body
            │            4. one wgsl_session per section →
            │               incremental re-check on every edit
            │            5. cache by (uri, version)
            ▼
   { split, results[] }  →  providers (all coordinates remapped
                             synth ↔ original through TextIndex,
                             UTF-8 bytes ↔ UTF-16 code units)

Kernel-split + preamble injection

Multi-kernel .wgsl files (the WebGPU ML pattern: one resource set per // --- KERNEL: <name> --- section, helper preamble at the top, shared utilities in a sibling file) are recognised automatically. Each section compiles as its own module — exactly how the runtime engine dispatches them — so cross-kernel n redeclarations and preamble helpers resolve without false positives.

Preamble resolution

1. wgslconfig.toml (recommended) — discovered by walking up from the document's directory; matched by the C-side wgsl_project_match.

   [preamble]
   files = [
       "_enables.wgsl",   # enable subgroups; enable f16;
       "_shared.wgsl",    # helpers used by every kernel
   ]
   auto_inject_into = ["*.wgsl"]
   

2. Legacy _shared.wgsl — a sibling _shared.wgsl, if present, is prepended when no config matches.

Preamble diagnostics surface in the preamble file itself, never on dependents. Saving a preamble re-checks every open .wgsl document.

Capabilities matrix

Commands

Settings

Build

# once: build the wasm bundle in the sibling libwgsl checkout
make -C ../libwgsl wasm

npm run compile    # copies wasm + official binding, then tsc
npm run package    # vsce package

Limitations

• Cold-start flash: no colour for ~50 ms while the wasm bundle initialises.
• Formatting refuses lossy runs: the formatter is parse→print, so on syntactically-broken sources it would silently drop the broken decls. The extension token-compares input and output and applies nothing unless the format is lossless — format-on-save can never eat half-typed code.
• Renaming a preamble decl from a dependent file is refused to avoid silently missing other dependents — rename in the preamble file itself.
• MSL output is best-effort: the structured MSL diagnostics API is not yet exported to wasm, so unsupported constructs yield an empty translation rather than a detailed reason.
• Interpreter caps: 2M scheduler steps, 256 lanes, 4096 values per buffer in reports — traces beyond that are truncated and flagged.

License

MIT.