@mailwoman/react 10.0.0 → 10.2.0

package/lib/runtime/useReleaseRuntime.ts

@@ -2,172 +2,182 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `useReleaseRuntime` — the headless load-orchestration hook shared by every mailwoman browser surface (the
- *   inline doc-embeds via `RuntimeEmbed`, and the geocoder). It owns the version-selection state
- *   machine, the per-version load SEQUENCING, cancellation, and the ready / loading / error state — but
- *   NOTHING model- or map-specific. The actual asset fetchers (the ONNX classifier factory, the httpvfs
- *   WOF opener, the FST fetch, the releases.json fetch) are INJECTED by the host as async functions, so
- *   this module imports only React: no `onnxruntime-web`, no `sql.js-httpvfs`, no `maplibre-gl`, no
- *   `fetch`-specific plumbing. That keeps it node-import-safe and root-exportable from
- *   `@mailwoman/react` — the exact interface `PipelineRuntime` established, generalized to the loader itself.
- *
- *   The hook is generic over `TAssets` (the opaque bundle the host's `loadAssets` returns — classifier,
- *   FST, WOF lookup, calibrator, …) and `TRelease` (the host's release-manifest entry). The package
- *   never inspects either; it just holds, reveals, and re-loads them across version/backend switches.
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 
 /**
- * The minimal contract a release-manifest entry must satisfy. Hosts extend this with their own fields.
+ * The minimal fields of a release-manifest entry.
+ * Hosts can add their own fields.
  */
 export interface ReleaseBase {
-	/**
-	 * The version tag this entry describes (matched against `selectedVersion`).
-	 */
 	version: string
+
 	/**
-	 * Optional display label a version picker shows; falls back to `version`.
+	 * The version picker's display label, falling back to `version`.
 	 */
 	label?: string
 }
 
 /**
- * The releases manifest the host fetches — the default version plus the selectable release entries.
+ * The releases manifest that the host fetches.
  */
 export interface ReleaseManifest<TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * The version selected on first load (before the user picks another).
+	 * The version that the hook selects when the manifest first loads.
 	 */
 	defaultVersion: string
-	/**
-	 * Every selectable release.
-	 */
+
 	releases: TRelease[]
 }
 
 /**
- * The progress channel handed to the host's `loadAssets`. The host reports load progress + the resolved backend + the
- * staged step labels/index THROUGH these setters (all no-op once the load is superseded/aborted), while the hook owns
- * the terminal state (revealing the assets + clearing progress on success, surfacing the error on failure).
+ * The abort signal and progress setters that the hook passes to a host's `loadAssets`.
+ *
+ * The setters stop affecting state after abort or supersession.
+ * The hook sets the final ready or error state.
  */
 export interface AssetsLoadContext {
 	/**
-	 * Aborts when this load is superseded (version/backend switch) or the provider unmounts.
+	 * The signal aborts when a version switch supersedes this load or when the component unmounts.
 	 */
 	signal: AbortSignal
+
 	/**
-	 * Whether the host should force the CPU/WASM backend (opt out of WebGPU) for this load.
-	 */
-	forceWASM: boolean
-	/**
-	 * Set the human-readable progress line (e.g. `Loading v7 model (~28 MB)…`).
+	 * Sets the progress line, such as `Loading v7 model (~28 MB)…`.
 	 */
 	setProgress: (progress: string) => void
-	/**
-	 * Set the staged-loader step labels (e.g. `["Loading classifier", "Loading FST gazetteer"]`).
-	 */
+
 	setStepLabels: (labels: string[]) => void
+
 	/**
-	 * Advance the staged-loader step index (0-based).
+	 * Sets the zero-based index of the current loader step.
 	 */
 	setStepIndex: (index: number) => void
+
 	/**
-	 * Report the backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`).
+	 * Reports the neural runtime's backend and model size, such as `wasm (27 MB int8)`.
 	 */
 	setBackend: (backend: string) => void
+
+	/**
+	 * Reports the fraction of the current download received so far, in [0, 1], or `null`
+	 * when no download is in progress or the response declares no length.
+	 *
+	 * The step index cannot show it because the model is fetched before the first step begins.
+	 */
+	setByteFraction: (fraction: number | null) => void
 }
 
 /**
- * The injected loaders the hook orchestrates. Nothing here is model- or map-aware — the host owns all that.
+ * The host's manifest loader, asset loader and optional asset disposer for {@link useReleaseRuntime}.
  */
 export interface ReleaseRuntimeConfig<TAssets, TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * Fetch + normalize the releases manifest. Returns `null` when no manifest is available (the surface then shows
-	 * nothing selectable). Rejecting surfaces `errorMessage`. Runs once on mount.
+	 * Fetches the releases manifest once on mount.
+	 *
+	 * It returns `null` when the manifest is unavailable.
+	 * The hook reports a rejection through `errorMessage`.
 	 */
 	loadManifest: (signal: AbortSignal) => Promise<ReleaseManifest<TRelease> | null>
+
 	/**
-	 * Load the full asset bundle for one release — the classifier, FST, WOF lookup, calibrator, whatever the host needs.
-	 * Runs on every version or `forceWASM` change. Report progress via `ctx`; return the bundle. Rejecting surfaces
-	 * `errorMessage`. Bail early when `ctx.signal.aborted` — the hook discards a superseded result regardless.
+	 * Loads the asset bundle for one release and reports progress through `ctx`.
+	 *
+	 * The hook calls it on every version change.
+	 * It reports a rejection through `errorMessage`.
+	 *
+	 * It disposes a result that resolves after `ctx.signal` aborts.
 	 */
 	loadAssets: (release: TRelease, ctx: AssetsLoadContext) => Promise<TAssets>
+
 	/**
-	 * The progress line shown before the manifest arrives. @default "Loading releases…"
+	 * Releases resources the garbage collector does not own, such as an ONNX
+	 * session's WASM heap or a GPU buffer.
+	 *
+	 * The hook calls it when replacing a bundle.
+	 * It also calls it if a bundle resolves after abort or when unmounting.
+	 *
+	 * Without this function, each reload leaves the model resident.
+	 */
+	disposeAssets?: (assets: TAssets) => void | Promise<void>
+
+	/**
+	 * The progress line shown before the manifest arrives.
+	 *
+	 * @defaultValue `"Loading releases…"`
 	 */
 	initialProgress?: string
 }
 
 /**
- * The state `useReleaseRuntime` produces — the load-orchestration state a surface renders + re-projects.
+ * The release-loading state that {@link useReleaseRuntime} returns.
  *
- * This is the LOADER STATE, deliberately distinct from {@link GeocoderRuntime} (the injected runtime contract
- * `<Geocoder>` consumes). A host builds a {@link GeocoderRuntime} by pairing this loader state (assets + backend +
- * version) with the map surface (style, overlays, bias, parse) — see the map subpath's `GeocoderRuntime`.
+ * A host pairs it with its map surface to build a `GeocoderRuntime`.
  */
 export interface ReleaseLoaderState<TAssets, TRelease extends ReleaseBase = ReleaseBase> {
 	/**
-	 * The releases manifest, once fetched.
+	 * The releases manifest, `null` until it loads or when none is available.
 	 */
 	manifest: ReleaseManifest<TRelease> | null
+
 	/**
-	 * The currently-selected version, or `null` before the manifest resolves.
+	 * The selected version, `null` before the manifest loads.
 	 */
 	selectedVersion: string | null
+
 	/**
-	 * The release entry matching `selectedVersion` (convenience over `manifest.releases.find`).
+	 * The manifest entry that matches `selectedVersion`, or `null` when none matches.
 	 */
 	selectedRelease: TRelease | null
+
 	/**
-	 * The loaded asset bundle for the selected version, or `null` while (re)loading.
+	 * The asset bundle for the selected version, `null` while it loads.
 	 */
 	assets: TAssets | null
-	/**
-	 * Whether the asset bundle is loaded and ready to use.
-	 */
+
 	ready: boolean
+
 	/**
-	 * Human-readable load progress (`""` when idle/ready).
+	 * The load progress line, empty once loading finishes or fails.
 	 */
 	loadingProgress: string
+
 	/**
-	 * Staged-loader step index (0-based; `-1` before the first step).
+	 * The zero-based loader step index, `-1` before the first step.
 	 */
 	loadingStepIndex: number
+
+	loadingStepLabels: string[]
+
 	/**
-	 * Staged-loader step labels.
+	 * The fraction of the current download received so far, in [0, 1], or `null`
+	 * when no download is in progress or the length is unknown.
 	 */
-	loadingStepLabels: string[]
+	loadingByteFraction: number | null
+
 	/**
-	 * A load error (manifest or asset), distinct from any per-parse error a consumer tracks separately.
+	 * A manifest or asset load error, separate from any parse error a consumer tracks.
 	 */
 	errorMessage: string | null
+
 	/**
-	 * The backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`), or `""` before it's known.
+	 * The neural runtime's backend and model size, such as `wasm (27 MB int8)`;
+	 * it is `""` before the model loads.
 	 */
 	activeBackend: string
+
 	/**
-	 * Whether the CPU/WASM backend is currently forced.
-	 */
-	forceWASM: boolean
-	/**
-	 * Switch to a different version (clears any error, then reloads the asset bundle).
+	 * Switches to another version, clearing any error and reloading the asset bundle.
 	 */
 	selectVersion: (version: string) => void
-	/**
-	 * Force (or unforce) the CPU/WASM backend — reloads the asset bundle.
-	 */
-	setForceWASM: (forceWASM: boolean) => void
 }
 
 /**
- * Drive the shared version → asset-bundle load state machine over a host-injected loader.
+ * Loads the release manifest on mount and the selected release's assets whenever the version changes.
  *
- * Sequence: on mount `loadManifest` runs and its `defaultVersion` becomes the selection; each version (or `forceWASM`)
- * change reloads the bundle via `loadAssets`, the previous load aborted first. The assets are revealed ATOMICALLY when
- * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers wait on `ready`.
+ * Each reload aborts the previous load and disposes the old assets.
+ * `ready` becomes true after the new assets load.
  */
 export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = ReleaseBase>(
 	config: ReleaseRuntimeConfig<TAssets, TRelease>
@@ -182,25 +192,23 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 	const [loadingStepLabels, setLoadingStepLabels] = useState<string[]>([])
 	const [errorMessage, setErrorMessage] = useState<string | null>(null)
 	const [activeBackend, setActiveBackend] = useState<string>("")
-	const [forceWASM, setForceWASMState] = useState(false)
+	const [loadingByteFraction, setLoadingByteFraction] = useState<number | null>(null)
 
-	// Latest-ref the injected loaders: a host that re-creates them each render (an inline arrow) must NOT retrigger the
-	// load effects, which key ONLY on version/backend. The effects read `.current` at run time.
 	const loadManifestRef = useRef(config.loadManifest)
 	const loadAssetsRef = useRef(config.loadAssets)
+	const disposeAssetsRef = useRef(config.disposeAssets)
+
+	const liveAssetsRef = useRef<TAssets | null>(null)
 
-	// Latest manifest for the version-load effect, so it can resolve the release WITHOUT depending on `manifest`
-	// identity — which would double-fire the load the instant the manifest first arrives (the selection transition
-	// null → defaultVersion already fires it once).
 	const manifestRef = useRef<ReleaseManifest<TRelease> | null>(null)
 
 	useEffect(() => {
 		loadManifestRef.current = config.loadManifest
 		loadAssetsRef.current = config.loadAssets
+		disposeAssetsRef.current = config.disposeAssets
 		manifestRef.current = manifest
-	}, [config.loadAssets, config.loadManifest, manifest])
+	}, [config.disposeAssets, config.loadAssets, config.loadManifest, manifest])
 
-	// Mount: fetch the manifest, then select the default version.
 	useEffect(() => {
 		const controller = new AbortController()
 
@@ -223,7 +231,6 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		return () => controller.abort()
 	}, [])
 
-	// Load the per-version asset bundle when the version (or the backend force) changes.
 	useEffect(() => {
 		if (!selectedVersion) return
 
@@ -242,25 +249,41 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 
 		void (async () => {
 			try {
+				const outgoing = liveAssetsRef.current
+
+				liveAssetsRef.current = null
+
+				if (outgoing) {
+					await disposeAssetsRef.current?.(outgoing)
+				}
+
 				setAssets(null)
 				setLoadingStepIndex(-1)
 				setLoadingStepLabels([])
 				setActiveBackend("")
+				setLoadingByteFraction(null)
 
 				const ctx: AssetsLoadContext = {
 					signal,
-					forceWASM,
 					setProgress: (progress) => guard(() => setLoadingProgress(progress)),
 					setStepLabels: (labels) => guard(() => setLoadingStepLabels(labels)),
 					setStepIndex: (index) => guard(() => setLoadingStepIndex(index)),
 					setBackend: (backend) => guard(() => setActiveBackend(backend)),
+					setByteFraction: (fraction) => guard(() => setLoadingByteFraction(fraction)),
 				}
 
 				const loaded = await loadAssetsRef.current(release, ctx)
 
-				if (signal.aborted) return
+				if (signal.aborted) {
+					await disposeAssetsRef.current?.(loaded)
+
+					return
+				}
+
+				liveAssetsRef.current = loaded
 				setAssets(loaded)
 				setLoadingProgress("")
+				setLoadingByteFraction(null)
 			} catch (error) {
 				if (signal.aborted) return
 				setErrorMessage(error instanceof Error ? error.message : String(error))
@@ -269,15 +292,25 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		})()
 
 		return () => controller.abort()
-	}, [selectedVersion, forceWASM])
+	}, [selectedVersion])
+
+	useEffect(() => {
+		return () => {
+			const live = liveAssetsRef.current
+
+			liveAssetsRef.current = null
+
+			if (live) {
+				void disposeAssetsRef.current?.(live)
+			}
+		}
+	}, [])
 
 	const selectVersion = useCallback((version: string) => {
 		setSelectedVersion(version)
 		setErrorMessage(null)
 	}, [])
 
-	const setForceWASM = useCallback((next: boolean) => setForceWASMState(next), [])
-
 	const selectedRelease = useMemo(
 		() => manifest?.releases.find((r) => r.version === selectedVersion) ?? null,
 		[manifest, selectedVersion]
@@ -292,10 +325,9 @@ export function useReleaseRuntime<TAssets, TRelease extends ReleaseBase = Releas
 		loadingProgress,
 		loadingStepIndex,
 		loadingStepLabels,
+		loadingByteFraction,
 		errorMessage,
 		activeBackend,
-		forceWASM,
 		selectVersion,
-		setForceWASM,
 	}
 }