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

• loadVtkWasm(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 canvas ids (bindCanvas) instead of a hard-coded internal selector, and never creates/removes canvas elements.
• Legacy <9.5 support removed: sessionFactory, stateDecorators, and the dual-path branches in proxy/scriptLoader/remote are gone.

flowchart TD
    ST["HTML script tag (global vtkWASM)"]
    BD["Bundler import"]
    AN["Annotation script tag"]
    ST --> LF["loadVtkWasm(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 loadVtkWasm({ url, ...cfg, wasmBaseName: name })
createNamespace(url, cfg)	(await loadVtkWasm({ url, ...cfg })).createStandaloneSession().vtk
new RemoteSession(); await r.load(url, cfg)	(await loadVtkWasm({ url, ...cfg })).createRemoteSession()
remote.sceneManager.xxx()	remote.vtk / remote methods (#native is private)
import … from "@kitware/vtk-wasm/vtk" / /remote	import { loadVtkWasm } from "@kitware/vtk-wasm"
(none)	session.dispose(), runtime.dispose(), using

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).