A VS Code extension for the Blade language: live diagnostics, type hovers, navigation, deduction-aware code actions, Ionide-style type lenses, and an interpreter-backed REPL with inline results.
| Feature | Surface | Keybinding / trigger |
|---|---|---|
| Fast check (parse + typecheck + deduce) | squiggles, hovers, lenses refresh | automatic while typing (~300 ms debounce, via blade ide serve) |
| Full check (+ monomorphization → concrete types) | hover/lens type upgrades | automatic on save / open / ~2 s idle; manual Ctrl+Alt+Enter (Blade: Check Current File) |
| Go to definition | editor | F12 / Ctrl+Click |
| Peek definition | editor | Alt+F12 |
| Find all references | references view | Shift+F12 |
| Rename symbol | in-file rename | F2 |
| Document outline / breadcrumbs | outline view | Ctrl+Shift+O |
| Quick fix: pin deduced comm/anticomm, annotate deduced rank | lightbulb | Ctrl+. |
Signature lens (functions; arrays as Idx<N> -> T) |
above-line lens | always on (settings toggles) |
Deduction lens (deduced comm(a, b) · storage — pin) |
above-line lens, clickable | click applies the pin |
| Type/keyword/builtin/provider hovers | hover | mouse hover |
| Signature help | parameter hints | ( and , while typing a call |
| Completions (bindings, builtins, deduction pins) | IntelliSense | Ctrl+Space |
| Send selection/line to REPL (inline result) | REPL + inline decoration | Alt+Enter |
| Send file to REPL | REPL terminal | Alt+Shift+Enter |
Notebooks (.bladenb): run cell / run all |
notebook UI | Shift+Enter and the standard notebook keys |
New notebook / open .blade as notebook |
notebook editor | command palette |
| Restart notebook kernel (reset session) | notebook toolbar | command palette |
| Run file (full compile + run) | ▶ editor title button | — |
| Show generated C++ | side-by-side editor | command palette |
| Start / Reset REPL session | REPL terminal | command palette |
| Plots (contours, images) from REPL/notebook output | "Blade Plots" panel beside the editor | automatic when evaluated code emits a display frame; Blade: Plot Demo renders a sample |
| Charts drawn in the notebook cell (not a text summary) | cell output, via the bundled plotly notebook renderer | automatic for any plotly or plot-stream output |
Live plot streaming (plot.stream) |
cell output animates while the cell runs; panel chart extends in place | automatic while a long cell emits stream frames |
All navigation features land on VS Code's standard keys — no custom chords to learn beyond the three REPL/check bindings.
A built Blade compiler. The extension auto-detects the most recently built of bin/Release / bin/Debug in the standard repo location, or Blade on PATH; override with blade.compilerPath.
- Compiler discovery order: the
blade.compilerPathsetting, then theBLADE_EXEenvironment variable, then the newest-built ofbin/Release/bin/Debugin the standard repo location, thenBladeon PATH.BLADE_EXEis new to the extension itself as of this release — previously only the standalone test scripts (npm run test:serveetc.) honored it;blade.compilerPathstill wins when set, but leaving it empty and settingBLADE_EXEnow works too. - Compilers with the
ide servesubcommand get as-you-type checking through a persistent process (two tiers: a fast parse+typecheck+deduce pass while you type, and a full pass through monomorphization on save/idle that upgrades polymorphic value types to their concrete instantiations). - Older compilers fall back automatically for
.bladefiles:ide check --jsonon save/open, or plain-text diagnostics for compilers without the JSON subcommand. - Notebooks are the exception — there is no fallback. Running cells needs
ide serve'seval/resetSession, and in-cell checking (diagnostics, hovers, completions, lenses) needs itscheckCellscommand, which assembles the cells into one session source compiler-side. On a compiler without them, cells report the missing support when run and simply go unchecked while you type;.bladefiles in the same window are unaffected.
.bladenb files open as native VS Code notebooks. The format is plain Blade text with // %% cell markers (// %% [markdown] for prose cells), so the same file still runs under blade run and diffs cleanly in git. Cells evaluate with exact REPL semantics — an accumulating session, rebind-in-place, typed value echoes (xs = [1.0, 2.0, 3.0] : Array<Float64 like Idx<3>>), interpreter-first evaluation with a g++ fallback badge — on a dedicated ide serve process, so a slow cell never blocks typing-time checking. Cells also get the full IDE feature set: diagnostics, session-aware hovers and completions (names from earlier cells resolve), and type lenses. "Restart Kernel" resets the session; interrupting kills the evaluator and transparently replays the session on the next run.
Evaluated code that produces a plot ships it to the extension as a display frame — a {mime, data} payload carried alongside stdout on the REPL and ide serve channels (wire format). Frames render in a "Blade Plots" webview docked beside the editor: plot history with prev/next, export, and a plotly/GR backend toggle. plotly.js is bundled in the extension, so the panel works offline. Blade: Plot Demo pushes a sample contour through the same path without needing compiler support.
Backends. plotly is the interactive default (hover, zoom, pan), rendered in the webview. GR is a static renderer for large grids and publication output: clicking GR sends the plot's spec to the warm ide serve process, which renders a PNG through the gr-render helper and sends it back attached to the same plot — so toggling is instant in both directions once each render is cached. GR renders export as PNG, SVG, or PDF; plotly renders export as PNG or SVG. The GR button stays disabled, with the reason in its tooltip, until a GR installation resolves — npm run fetch-vendor provides one, or point blade.grPath at your own (see Vendor dependencies).
Plots come from the compiler's plot stdlib module. Options are tagged by quantity rather than by position, so they can be given in any order — and axis labels can be read straight off the data's units:
import units.SI
import plot
import display as d
let t: Array<Float64<second> like Idx<4>> = [0.0, 1.0, 2.0, 3.0]
let v: Array<Float64<meter> like Idx<4>> = [0.0, 2.5, 6.0, 9.5]
let _ = plot.line(t, v, "drift": title, d.unit_label(t): xlabel, d.unit_label(v): ylabel)plot provides contourf, contour, heatmap, line, and scatter; option slots are levels, cmap, title, xlabel, ylabel, and backend, plus maxdim on the three grid factories — each with a default, so plot.contourf(x, y, z) alone is valid.
Live streams. plot.stream(name, x, y, e: epoch, …) ships a chunk of a named series instead of a finished figure — mime application/vnd.blade.plotstream.v1+json, meta.id = the channel name. A cell that runs for minutes (a training loop) can therefore draw as it goes: during an ide serve eval each chunk arrives as an out-of-band display event, the extension merges it into that channel's accumulated series, and both surfaces repaint — the executing cell's own output at ~2 Hz, and the Blade Plots panel through one coalesced update per 100 ms, extending the live trace rather than re-plotting it. epoch marks show up as dotted vertical rules with e<n> labels, so one x-axis can span a whole run; past ~20 000 points the drawn trace is strided (the accumulated data is kept whole). Stream output is deliberately transient — it animates while the cell runs and is replaced by the cell's real outputs when the run ends, so the chart that persists is the ordinary figure the program emits at the end (plot.line(…)). Replays are handled by the merge itself: a Blade session re-runs every accumulated snippet, so an earlier cell's stream re-arrives under the same stable id on every later eval, and a chunk that restarts a channel from its first x (or an epoch that goes backwards) resets that channel's accumulator instead of appending a second copy of the run.
In-cell rendering. The extension contributes a notebook renderer (renderer/plotly-renderer.ts) for both the plotly mime and the stream mime, so charts draw inside the cell instead of degrading to the [application/vnd.plotly.v1+json — title] text summary. It loads the same bundled media/plotly.min.js the panel uses, addressed relative to the renderer module itself — no CDN, no second copy of plotly, and nothing that the notebook webview's offline CSP does not already allow.
Two slots exist for the backends. maxdim (default 512) caps how many samples per axis a grid serializes: a raw 2000² grid would be ~74 MB of figure JSON, past the frame size limit and far past display resolution, so bigger grids are resampled before they go on the wire. backend asks the panel to show this plot with a particular backend — the frame is still plotly JSON either way, so a viewer without GR simply ignores the request, and your own toggling always wins.
| Setting | Default | Effect |
|---|---|---|
blade.compilerPath |
"" (auto-detect) |
Path to Blade.exe |
blade.liveChecking |
true |
As-you-type fast checks (requires ide serve) |
blade.fastCheckDebounceMs |
300 |
Typing debounce before a fast check |
blade.fullCheckIdleMs |
2000 |
Idle time before a full-tier check |
blade.checkOnSave / blade.checkOnOpen |
true |
Full check on save / open |
blade.runTimeoutSeconds |
180 |
Timeout for Blade run (first runs invoke g++) |
blade.notebookEvalTimeoutSeconds |
1800 |
Timeout per notebook cell eval (cells can run for minutes, e.g. training) |
blade.inlineReplResults |
true |
Inline green/red REPL results at the evaluated line |
blade.signatureLens.functions |
true |
Abstract signature lens above functions |
blade.signatureLens.arrays |
true |
Index-arrow lens above array bindings (Idx<N> -> Float64) |
blade.deductionLens |
true |
Deduced comm/anticomm + storage lens with one-click pin |
One runtime dependency: @blade-lang/ide-protocol (the shared NDJSON client, wire-protocol codecs, and generated language-surface data the Blade compiler repo publishes) — vendored as a committed tarball under vendor/, no npm registry involved. The extension itself is written in strict TypeScript: src/, scripts/, and renderer/ compile with tsc (one tsconfig.json, module: NodeNext) into out/, which is what VS Code loads — out/src/extension.js as the CommonJS extension host entry, out/renderer/plotly-renderer.js as the ES-module notebook renderer (renderer/package.json carries the "type": "module" marker and is copied alongside). out/ is not committed; npm run build (or npm run watch while editing) regenerates it, and vsce package runs it through vscode:prepublish.
npm install # extracts vendor/blade-lang-ide-protocol-<version>.tgz into node_modules; installs typescript + @types
npm test # builds (tsc is the syntax/type gate), then runs the hermetic suitenpm run typecheck is tsc --noEmit on its own. The hermetic suite covers grammar/table/surface consistency, provider tests against a vscode mock, the plots panel, the notebook controller, and the renderer. Live suites need a built compiler (BLADE_EXE env var or the standard build locations): npm run test:serve (ide-serve protocol), npm run test:repl (REPL protocol), npm run test:nav (navigation providers against real compiler payloads), npm run test:nb (notebook eval session semantics).
scripts/renderer-test.ts drives the compiled renderer/plotly-renderer.ts against a stub DOM: the contribution manifest, both mime paths, both plotly load paths (classic <script> and the import() fallback), the repaint/dispose lifecycle, and every visible fallback. What it cannot see is the real webview — whether VS Code picks this renderer for the cell at all, and whether the notebook output webview will actually serve media/plotly.min.js. That needs one two-minute session:
-
Launch the extension. F5 (Extension Development Host) from this repo, or install the
.vsixand reload the window. Open the Blade repo as the workspace folder so notebook data paths (examples/data/aspirin.zarr) resolve. -
A figure in a cell.
Blade: New Notebook, one cell:import plot let t = [0.0, 1.0, 2.0, 3.0] let v = [0.0, 2.5, 6.0, 9.5] let p = plot.line(t, v, "renderer smoke test": title)
Run it. Expect an interactive chart drawn in the cell — hover gives a tooltip, drag zooms — not the one-line
[application/vnd.plotly.v1+json — renderer smoke test]text summary. -
Live streams. Open
examples/aspirin_moment_jet.bladenb, run the first code cell (imports +z.load), then the three training cells. Expect the Blade Plots panel to open on the first chunk and each of the three channels (jet_pos,jet_k2,jet_k24) to extend its trace while its arm trains, with the executing cell's own chart repainting alongside at ~2 Hz. Each cell's stream output is replaced by that arm's persistentplot.linefigure when the run ends. -
Check the console. Developer: Toggle Developer Tools with the notebook focused — the output webview logs there. Expect nothing from the renderer.
Three symptoms, and what each implicates:
| Symptom | Implicates |
|---|---|
The cell shows the [application/vnd.plotly.v1+json — …] text summary |
The renderer was never picked. contributes.notebookRenderers did not load (check the Extension Host log), or renderer/ did not make it into the .vsix. Both mime types must be listed — a stream that summarises while finished figures draw means only one of the two is contributed. |
The cell shows pretty-printed JSON or a could not render block, with a console error naming the plotly URL |
The renderer ran; the plotly asset was not served. If the URL ends in /media/plotly.min.js and 404s, the webview's resource root does not reach media/. If it is not a vscode-resource/vscode-cdn URL at all (a blob: prefix, say), then import.meta.url is not the served module URL and the ../media/… base is wrong — a different fix. Either way the failure is remembered for the life of the webview, so reload the window before retesting. |
| The figure draws, but the stream never animates (the chart appears only when the cell finishes) | Not the renderer — the sink/event path. Chunks are not reaching the display bus: confirm the cell ran through ide serve rather than the g++ fallback, and check whether the Blade Plots panel is static too. If the panel animates and the cell does not, the per-execution display.subscribe in src/notebook.ts is the suspect. |
After a change lands in ../Blade/protocol (new compiler surface, a client bugfix), re-vendor it from a sibling Blade checkout:
npm run vendor:protocolThis re-packs ../Blade/protocol into vendor/blade-lang-ide-protocol-<version>.tgz and reinstalls. Commit the refreshed tarball together with the matching version bump in package.json's dependencies entry (kept lockstep with the compiler's compilerVersion).
Two upstream graphics packages back the plots panel. Neither is an npm package —
they are prebuilt artifacts pinned in deps.json and fetched by a
script, so "zero dependencies" above still holds.
| Package | Version | Lands at | In git? |
|---|---|---|---|
| plotly.js | 3.7.0 | media/plotly.min.js (4.85 MB) |
yes, committed |
| GR | 0.73.26 | vendor/gr/ (~30 MB headless subset) |
no, gitignored |
npm run fetch-vendor # fetch whatever is missing
npm run fetch-vendor -- --check # verify presence + hashes, no network
npm run fetch-vendor -- --force # re-fetch and re-extract regardlessplotly is the live backend and is committed on purpose: VS Code webviews have
no network access, so the panel loads it from disk and it has to ship inside the
.vsix. fetch-vendor normally just verifies its sha256 and does nothing.
GR is the static-PNG backend for large grids, still stubbed in the UI. It is
gitignored because it is large and re-fetchable, so a fresh clone has
to run npm run fetch-vendor before the GR path can work. The script picks the
release asset matching ${process.platform}-${process.arch}, reuses an
already-downloaded tarball when its hash matches, and normalizes the archive's
top-level directory away so the result always lands at exactly vendor/gr/.
Extraction is pruned to the headless render subset pinned in deps.json
(keep): ~30 MB instead of the 147 MB full tree, verified to render
byte-identical PNGs (see docs/gr-graphics-plan.md §7). Pass --full (with
--force to re-extract an existing tree) when you want the whole thing —
gksqt.exe for interactive debugging, videoplugin.dll for animation work.
Only the Windows asset's hash is pinned today; the other platforms are recorded
as null, and the script prints the hash it computed on first fetch so it can be
pasted into deps.json.
GR runtime note: GRDIR must point at vendor/gr and $GRDIR/bin must be on
PATH — the Qt/GKS shared libraries live there. The extension's serve process
will set both itself when the GR backend lands; nothing needs to be added to your
shell profile.
npm test only type-checks the fetcher (it is compiled with the rest). It deliberately does not run
--check, which would fail on any clone that has not fetched GR.