Redesign the VTK.wasm JavaScript API + docs overhaul

[jspanchu]

Summary

Replaces the scattered, confusingly-named loader/session API with a single, lean entry point and adds clean teardown. Also drops legacy (<9.5) support, regenerates the docs around the new API, and wires up an auto-generated API reference.

⚠️ Breaking change — see Migration below.

Motivation

The previous API had three pain points:

1. Namespace creation was scattered across createNamespace() (free function), VtkWASMLoader.createNamespace(), and VtkWASMLoader.createStandaloneSession() — no canonical path.
2. Confusing names — the JS RemoteSession class shadowed the C++ vtkRemoteSession it wrapped (exposed as .sceneManager), and load() meant three different things.
3. No clean teardown — C++ session objects were never deleted, and the remote path leaked a DOM container + canvas listeners.

What changed

Core API

• loadVtkWasmAsync(options) → cached VtkWasmRuntime, the single factory for sessions.
• runtime.createStandaloneSession() / runtime.createRemoteSession(); the C++ handle is private (#native), and session.vtk is the one way to the namespace.
• Uniform dispose() / [Symbol.dispose] on runtime and both sessions for real teardown (using works).
• RemoteSession now binds to user-provided canvases (bindCanvas) instead of a hard-coded internal selector, and never creates/removes canvas elements. A canvas element can be passed directly — when the build exposes specialHTMLTargets, the element is registered there, so it needs neither an id nor to be attached to the document (a CSS selector from the element id is the fallback). Render windows are bound lazily during update() once their state arrives, and specialHTMLTargets entries are cleaned up on unbindCanvas/dispose.
• create/destroy through a remote session's vtk proxy are now guarded — the C++ vtkRemoteSession has no such methods, so they warn and return undefined/false instead of throwing. A remote session can only control server-owned objects via getVtkObject.
• Legacy <9.5 support removed: sessionFactory, stateDecorators, and the dual-path branches in proxy/scriptLoader/remote are gone.

Naming — every promise-returning method/function under src/ is suffixed with Async; synchronous methods (e.g. VtkWasmRuntime.isAsync) are untouched. Docs and examples are updated to match.

flowchart TD
    ST["HTML script tag (global vtkWASM)"]
    BD["Bundler import"]
    AN["Annotation script tag"]
    ST --> LF["loadVtkWasmAsync(options)"]
    BD --> LF
    LF --> RT["VtkWasmRuntime — cached per url + config"]
    RT -->|createStandaloneSession| SS["StandaloneSession"]
    RT -->|createRemoteSession| RS["RemoteSession"]
    SS --> NS["session.vtk: create & render objects"]
    RS --> RW["bindNetwork + bindCanvas + update"]
    AN -.->|auto: loads + standalone session| NS
    NS --> DS["session.dispose()"]
    RW --> DS
    RT --> DR["runtime.dispose()"]

Loading

Packaging — exports collapse to . (index) + ./viewer; vite builds from src/index.js.

Docs

• New conceptual guides: Loading VTK.wasm (with the path diagram above), Standalone Session, Remote Session — each links into the generated reference rather than restating signatures.
• HTML Script Tag + Bundler Integration merged into Adding VTK.wasm to a Project; JS "Getting started" page removed; sidebar reordered.
• Auto-generated API reference from source JSDoc (TypeDoc + markdown/vitepress theme), wired into the nav/sidebar (expanded by default); mermaid enabled.
• README trimmed to onboarding essentials.

Migration

Before	After
new VtkWASMLoader(); await l.load(url, cfg, name)	await loadVtkWasmAsync({ url, ...cfg, wasmBaseName: name })
createNamespace(url, cfg)	(await loadVtkWasmAsync({ url, ...cfg })).createStandaloneSession().vtk
new RemoteSession(); await r.load(url, cfg)	(await loadVtkWasmAsync({ url, ...cfg })).createRemoteSession()
remote.sceneManager.xxx()	remote.vtk / remote methods (#native is private)
import … from "@kitware/vtk-wasm/vtk" / /remote	import { loadVtkWasmAsync } from "@kitware/vtk-wasm"
(none)	session.dispose(), runtime.dispose(), using

Promise-returning APIs were also renamed to carry an Async suffix:

Before	After
loadVtkWasm	loadVtkWasmAsync
createViewer	createViewerAsync
ExportViewer.load	ExportViewer.loadAsync
RemoteSession.update / setSize / fetchState / fetchHash / pushHash	updateAsync / setSizeAsync / fetchStateAsync / fetchHashAsync / pushHashAsync

Testing

• npm run build — ESM + both UMD bundles build clean.
• npm run lint — passes.
• npm run docs:build — builds with no dead links (only the pre-existing mermaid chunk-size advisory).

[jspanchu]

fyi @ansbbrooks your input will be much appreciated.

[ansbbrooks]

I love that this refactor takes advantage of the new using declaration.

However, can we add the Async prefix to all public API methods that return a Promise (or any then-able for that matter)? It makes a huge difference for me when gaining intuition about a method's behavior when there is an Async suffix. I instantly know the method should be awaited without having to do a deep dive into its source to see if it returns a Promise or not. I'm sure you have seen that before in other libraries and frameworks. For example, it's actually a policy in ASP.NET that all async methods must have the Async suffix--I think it would be a good idea to do that here while there is a redesign underway. https://github.com/dotnet/aspnetcore/wiki/Engineering-guidelines#async-method-patterns

By default all async methods must have the Async suffix. There are some exceptional circumstances where a method name from a previous framework will be grandfathered in.

In Trame for example, there are several methods that return Promises that you wouldn't know unless you imported the type or your IDE happened to notice it:

Trame.connect(): Promise<void> // would be nice if it were "connectAsync()"
WebsocketSession.close() : Promise<void> // would be nice if it were "closeAsync()"

In this PR:

loadVtkWasm(): Promise<VtkWasmRuntime> // should be "loadVtkWasmAsync()"
createViewer(): Promise<ExportViewer> // should be "createViewerAsync()"
createScriptURL(): Promise<string> // should be "createScriptURLAsync()"

[jspanchu]

I love that this refactor takes advantage of the new using declaration.

However, can we add the Async prefix to all public API methods that return a Promise (or any then-able for that matter)? It makes a huge difference for me when gaining intuition about a method's behavior when there is an Async suffix. I instantly know the method should be awaited without having to do a deep dive into its source to see if it returns a Promise or not. I'm sure you have seen that before in other libraries and frameworks. For example, it's actually a policy in ASP.NET that all methods must have the Async suffix--I think it would be a good idea to do that here while there is a redesign underway. https://github.com/dotnet/aspnetcore/wiki/Engineering-guidelines#async-method-patterns

By default all async methods must have the Async suffix. There are some exceptional circumstances where a method name from a previous framework will be grandfathered in.

In Trame for example, there are several methods that return Promises that you wouldn't know unless you imported the type or your IDE happened to notice it:

Trame.connect(): Promise<void> // would be nice if it were "connectAsync()"
WebsocketSession.close() : Promise<void> // would be nice if it were "closeAsync()"

In this PR:

loadVtkWasm(): Promise<VtkWasmRuntime> // should be "loadVtkWasmAsync()"
createViewer(): Promise<ExportViewer> // should be "createViewerAsync()"
createScriptURL(): Promise<string> // should be "createScriptURLAsync()"

sounds reasonable to me. i like this idea.

[jspanchu]

@ansbbrooks i pushed two more commits. one enables direct html canvas, second adds an "Async" suffix to promise returning methods.

@jourdain please review.

[jspanchu]

we can avoid this after https://gitlab.kitware.com/vtk/vtk/-/merge_requests/13345 is merged.

[jourdain]

shoud this.remoting.bindCanvas(rwId, canvas); and this.remoting.native.bindRenderWindow(rwId, target); be only one line?

[jourdain]

why don't we bind the target on the native side right now? Is it because the rw may not be available yet?