freebrowse 2.5.0-next.1

package/dist-lib/types/hooks/use-magic-wand.d.ts

@@ -0,0 +1,15 @@
+import type { NiiVue, NVExtensionContext } from "@niivue/niivue";
+import type { DrawingOptions } from "../store/types.js";
+/**
+ * Flood from the drawing layer's *current* bitmap and apply the result. Used for
+ * the one-shot commit path (a click with no preceding hover preview). Exported
+ * for unit testing against a fake ctx. Guards on drawing/volume so a click before
+ * a layer/volume exists is a no-op.
+ */
+export declare function runMagicWand(ctx: NVExtensionContext, opts: DrawingOptions, seed: [number, number, number], sliceType: number): Promise<void>;
+/**
+ * Wires the wand engine to the niivue instance. One extension context per
+ * instance; params are read imperatively at event time (so changing them never
+ * re-subscribes).
+ */
+export declare function useMagicWand(nvRef: React.RefObject<NiiVue | null>): void;

package/dist-lib/types/hooks/use-mesh-layers.d.ts

@@ -0,0 +1,21 @@
+import NiiVue from "@niivue/niivue";
+/**
+ * Mesh scalar-overlay layer handlers. Command-only: handlers issue nv.* layer
+ * commands (addMeshLayer/removeMeshLayer/setMeshLayerProperty), which emit
+ * meshUpdated -> the event adapter bumps layerVersion. getLayers re-reads
+ * nv.meshes[i].layers at render, so the UI follows without imperative writes.
+ * Layers are addressed by (meshIndex, layerIndex) — niivue-mono meshes have no id.
+ */
+export declare function useMeshLayers(nvRef: React.RefObject<NiiVue | null>): {
+    layerFileInputRef: import("react").RefObject<HTMLInputElement | null>;
+    getLayers: () => import("@niivue/niivue").NVMeshLayer[];
+    addLayerFromFile: (file: File) => Promise<void>;
+    removeLayer: (layerIndex: number) => void;
+    handleLayerOpacityChange: (value: number) => void;
+    handleLayerCalMinChange: (value: number) => void;
+    handleLayerCalMaxChange: (value: number) => void;
+    handleLayerColormapChange: (colormap: string) => Promise<void>;
+    handleLayerUseNegativeCmapChange: (checked: boolean) => Promise<void>;
+    handleAddLayerFiles: () => void;
+    handleLayerFileChange: (e: React.ChangeEvent<HTMLInputElement>) => Promise<void>;
+};

package/dist-lib/types/hooks/use-save.d.ts

@@ -0,0 +1,12 @@
+import type { NvdFormat } from "../store/types.js";
+import type { NiiVue } from "@niivue/niivue";
+export declare function useSave(nvRef: React.RefObject<NiiVue | null>): {
+    handleSaveScene: (isDownload?: boolean) => Promise<void>;
+    handleConfirmSave: () => Promise<void>;
+    handleCancelSave: () => void;
+    handleVolumeUrlChange: (index: number, url: string) => void;
+    handleVolumeCheckboxChange: (index: number, enabled: boolean) => void;
+    handleDocumentLocationChange: (location: string) => void;
+    handleDocumentCheckboxChange: (enabled: boolean) => void;
+    handleDocumentFormatChange: (format: NvdFormat) => void;
+};

package/dist-lib/types/hooks/use-surfaces.d.ts

@@ -0,0 +1,16 @@
+import type { NiiVue } from "@niivue/niivue";
+/**
+ * Surface (mesh) handlers. Command-only: handlers issue nv.* commands and the
+ * derived `surfaces` list follows via the event adapter (which rebuilds it from
+ * nv.meshes on meshLoaded/meshRemoved/meshUpdated). Handlers never write the
+ * surfaces slice directly.
+ */
+export declare function useSurfaces(nvRef: React.RefObject<NiiVue | null>, debouncedGLUpdate: () => void): {
+    updateSurfaceDetails: () => void;
+    toggleSurfaceVisibility: (surfaceIndex: number) => void;
+    removeSurface: (surfaceIndex: number) => void;
+    handleRemoveSurfaceClick: (surfaceIndex: number) => void;
+    handleSurfaceOpacityChange: (newOpacity: number) => void;
+    handleSurfaceColorChange: (hexColor: string) => void;
+    handleMeshShaderChange: (shaderName: string) => void;
+};

package/dist-lib/types/hooks/use-viewer-options.d.ts

@@ -0,0 +1,42 @@
+import { type NiiVue } from "@niivue/niivue";
+import type { DragMode } from "../components/drag-mode-selector.js";
+import type { ViewMode } from "../store/types.js";
+/**
+ * Viewer-option handlers. Event-driven model: handlers issue commands to the
+ * niivue instance (`nv.*`) and the Zustand store follows via the event adapter
+ * (registerNiiVueEvents / createStoreSyncTarget) — handlers do NOT write the
+ * store themselves. The single exception is crosshairWidth/crosshairVisible,
+ * which is store-owned UI state (niivue has only one crosshairWidth where 0
+ * means hidden, so it can't remember the width while hidden).
+ *
+ * One-time init on mount, chosen by `init` (only the viewer component that owns
+ * the mount passes it; other consumers of the handlers leave it at "none"):
+ *   - `"apply"` (the app, which built the instance): push the store's viewer
+ *     defaults onto the instance once (`applyViewerOptions`).
+ *   - `"sync"`  (a host-owned instance): never touch the instance's settings;
+ *     seed the store FROM it instead (`syncViewerOptionsFromNiiVue`), so the
+ *     UI reflects what the host configured.
+ *   - `"none"`  (default): handlers only.
+ */
+export type ViewerOptionsInit = "apply" | "sync" | "none";
+export declare function useViewerOptions(nvRef: React.RefObject<NiiVue | null>, init?: ViewerOptionsInit): {
+    viewerOptions: import("../store/types.js").ViewerOptions;
+    setViewerOptions: (options: import("../store/types.js").ViewerOptions | ((prev: import("../store/types.js").ViewerOptions) => import("../store/types.js").ViewerOptions)) => void;
+    applyViewerOptions: () => void;
+    syncViewerOptionsFromNiiVue: () => void;
+    debouncedGLUpdate: () => void;
+    handleViewMode: (mode: ViewMode) => void;
+    handleDragModeChange: (mode: DragMode) => void;
+    handleCrosshairWidthChange: (value: number) => void;
+    handleCrosshairGapChange: (value: number) => void;
+    handleInterpolateVoxelsChange: (checked: boolean) => void;
+    handleCrosshairVisibleChange: (visible: boolean) => void;
+    handleCrosshairColorChange: (color: string) => void;
+    handleRulerWidthChange: (value: number) => void;
+    handleRulerVisibleChange: (visible: boolean) => void;
+    handleOverlayOutlineWidthChange: (value: number) => void;
+    handleColorbarChange: (checked: boolean) => void;
+    handleRadiologicalChange: (checked: boolean) => void;
+    handleSagittalNoseLeftChange: (checked: boolean) => void;
+    resetViewAndContrast: () => void;
+};

package/dist-lib/types/hooks/use-volumes.d.ts

@@ -0,0 +1,39 @@
+import type { NiiVue } from "@niivue/niivue";
+/**
+ * Built-in colormaps that are categorical/label maps (as opposed to continuous
+ * gradients). When one of these is selected, FreeBrowse applies it as a label
+ * colormap (setColormapLabel) so the volume renders as discrete regions.
+ * niivue-mono does not tag colormaps as label-vs-continuous, so this list is
+ * curated here; matched case-insensitively against nv.colormaps. Only palettes
+ * we've made opaque (alpha 255) are included — random/nih still ship alpha 64
+ * and would wash out, so they're excluded pending the Phase-7 systemic fix.
+ */
+export declare const LABEL_COLORMAPS: Set<string>;
+/**
+ * After a document loads, attach the label LUT to every volume whose
+ * `colormap` names a categorical palette but that carries no `colormapLabel`.
+ *
+ * niivue-mono applies a document's `colormap` as a continuous gradient
+ * (niivue/mono#69), so a migrated legacy scene -- `aseg` with `Freesurfer`,
+ * say -- would render as a smooth ramp. A document the app itself saved after
+ * a dropdown change already embeds `colormapLabel` and is left alone. Same
+ * dual call as `handleColormapChange`.
+ */
+export declare function applyLabelColormapsAfterLoad(nv: NiiVue): Promise<void>;
+export declare function useVolumes(nvRef: React.RefObject<NiiVue | null>, debouncedGLUpdate: () => void, removeSurface: (surfaceIndex: number) => void): {
+    getVolumes: () => import("@niivue/niivue").NVImage[];
+    toggleImageVisibility: (id: string) => void;
+    handleOpacityChange: (newOpacity: number) => void;
+    handleFrameChange: (newFrame: number) => void;
+    handleContrastMinChange: (newContrastMin: number) => void;
+    handleContrastMaxChange: (newContrastMax: number) => void;
+    handleColormapChange: (event: React.ChangeEvent<HTMLSelectElement>) => void;
+    handleMoveVolumeUp: () => void;
+    handleMoveVolumeDown: () => void;
+    removeVolume: (imageIndex: number) => void;
+    handleRemoveVolumeClick: (imageIndex: number) => void;
+    handleEditVolume: (imageIndex: number) => Promise<void>;
+    canEditVolume: (imageIndex: number) => boolean;
+    handleConfirmRemove: () => void;
+    handleCancelRemove: () => void;
+};

package/dist-lib/types/lib/confirmations.d.ts

@@ -0,0 +1,4 @@
+export declare function requestImagingUploadConfirmation(): Promise<boolean>;
+export declare function resolveImagingUploadConfirmation(ok: boolean): void;
+export declare function requestSessionDeleteConfirmation(): Promise<boolean>;
+export declare function resolveSessionDeleteConfirmation(ok: boolean): void;

package/dist-lib/types/lib/default-niivue-options.d.ts

@@ -0,0 +1,16 @@
+import { NiiVue, type NiiVueOptions } from "@niivue/niivue";
+/**
+ * The options FreeBrowse constructs its NiiVue instance with. Shared by the
+ * app entry (`main.tsx`) and the library (`createFreeBrowseInstance`) so both
+ * produce identical instances. No `backend` option: niivue picks WebGPU when
+ * `navigator.gpu` exists and falls back to WebGL2 otherwise.
+ */
+export declare const DEFAULT_NIIVUE_OPTIONS: Partial<NiiVueOptions>;
+/** Overrides the QA route applies on top of the defaults. */
+export declare const QA_VIEWER_NIIVUE_OPTIONS: Partial<NiiVueOptions>;
+/**
+ * Build a NiiVue instance the way FreeBrowse does. A host that wants FreeBrowse
+ * to own the instance calls this (or lets `mountFreeBrowse` call it); a host
+ * that already has an instance passes its own instead.
+ */
+export declare function createFreeBrowseInstance(overrides?: Partial<NiiVueOptions>): NiiVue;

package/dist-lib/types/lib/deployment-config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Runtime configuration for one FreeBrowse instance (app or embedded library).
+ *
+ * These are *deployment* (operator/host-controlled) settings, distinct from
+ * per-user preferences, and must never be sourced from user-writable storage.
+ *
+ * Defaults come from Vite env vars so the app behaves exactly as before
+ * (`VITE_SERVERLESS`, `VITE_DISABLE_DOWNLOAD`); an embedding host overrides
+ * them at runtime through `configureFreeBrowse` (or the `mountFreeBrowse`
+ * options), since a published package has one build and no env.
+ *
+ * Consumers read through `deploymentConfig` (getters, always current) and the
+ * `dataUrl` / `aiUrl` helpers rather than caching values at import time.
+ */
+export interface FreeBrowseBackend {
+    /** Base URL of the `/data` file API (listings, `.nvd` + `.nii` uploads). */
+    dataUrl: string;
+    /** Base URL of the `/ai` session API. */
+    aiUrl: string;
+}
+export interface FreeBrowseConfig {
+    /**
+     * Backend endpoints, or `null` for a backend-less ("serverless") viewer: no
+     * Save-to-server, no Data/NVD tabs, no AI capability probe.
+     */
+    backend: FreeBrowseBackend | null;
+    /**
+     * Lock down client-side data export for secure deployments: disables the
+     * Download button and no-ops niivue's save-to-disk methods. Not a guarantee
+     * against a determined/malicious user — it stops well-intentioned exports.
+     */
+    downloadDisabled: boolean;
+    /** localStorage key for user preferences, or `false` to keep them in memory. */
+    persist: string | false;
+    /** Read `?nvd=` / `?vol=` from the page URL on startup (app: yes; library: no). */
+    readUrlParams: boolean;
+    /** Publish the instance as `window.freebrowse.nv` (app: yes; library: no). */
+    exposeGlobal: boolean;
+}
+export declare const DEFAULT_BACKEND: FreeBrowseBackend;
+export declare const DEFAULT_PERSIST_KEY = "freebrowse-user-settings";
+/** Override part of the configuration; returns the effective config. */
+export declare function configureFreeBrowse(partial: Partial<FreeBrowseConfig>): Readonly<FreeBrowseConfig>;
+/** Back to the env-derived defaults (tests). */
+export declare function resetFreeBrowseConfig(): void;
+/** The effective configuration (live view; do not mutate). */
+export declare function getFreeBrowseConfig(): Readonly<FreeBrowseConfig>;
+/**
+ * The two flags most of the UI keys off. Getters, so a value read inside a
+ * render or effect is always the configured one.
+ */
+export declare const deploymentConfig: {
+    /** No backend configured (file:// builds, or an embedding host without one). */
+    readonly serverless: boolean;
+    readonly downloadDisabled: boolean;
+};
+/** `dataUrl("nvd")` → `<backend.dataUrl>/nvd`. Throws when no backend is configured. */
+export declare function dataUrl(path?: string): string;
+/** `aiUrl("session/list")` → `<backend.aiUrl>/session/list`. Throws when no backend. */
+export declare function aiUrl(path?: string): string;
+/**
+ * Strip the configured data base from a URL, returning the path relative to
+ * the data root (`"/data/x/y.nii.gz"` → `"x/y.nii.gz"`), or null if the URL is
+ * not under it. Accepts the bare relative spelling too (`"data/x"`).
+ */
+export declare function relativeToDataRoot(url: string): string | null;

package/dist-lib/types/lib/niivue-helpers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Map from view mode name to NiiVue slice type and render settings.
+ */
+export declare const sliceTypeMap: {
+    [type: string]: {
+        sliceType: number;
+        showRender: number;
+    };
+};
+/**
+ * Convert an RGBA [0-255] tuple to a hex color string (ignoring alpha).
+ */
+export declare function rgba255ToHex(rgba255: [number, number, number, number]): string;
+/**
+ * Convert a Uint8Array to a base64 string efficiently for large arrays.
+ */
+export declare function uint8ArrayToBase64(uint8Array: Uint8Array): string;
+/**
+ * Gzip a byte array with the browser-native `CompressionStream('gzip')`.
+ *
+ * niivue-mono's `saveVolume` returns raw (uncompressed) bytes only for an empty
+ * filename — a `.gz` filename triggers a browser download instead of returning
+ * bytes. So the AI upload path exports raw bytes via `saveVolume({filename:''})`
+ * and gzips them here (matching old FreeBrowse's `saveToUint8Array(name.gz)`),
+ * with no extra dependency.
+ */
+export declare function gzipUint8Array(bytes: Uint8Array): Promise<Uint8Array>;

package/dist-lib/types/lib/nvd-volume-urls.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Point each volume entry at the backend path it is being uploaded to, for the
+ * "save to server" flow.
+ *
+ * The document is serialized with `linkData: true`, so a volume that already has
+ * a fetchable url carries no bytes. This rewrites that url to the *destination*
+ * — which `linkData` cannot do, because it keys off where a volume was loaded
+ * from (`shouldLinkVolume` in niivue's `documentLinkData.ts`), not where it is
+ * going. FreeBrowse's save dialog collects a path for a file being uploaded in
+ * the same submit, which does not exist yet and is not `volume.url`.
+ *
+ * Any residual embedded data is dropped: a `blob:`/`data:` url fails niivue's
+ * `isLinkableUrl`, so those volumes embed as a fallback.
+ *
+ * A `null` entry means the user gave no destination for that volume, so its
+ * bytes are KEPT and the document still round-trips. (The previous
+ * `stripEmbeddedData` deleted them regardless, producing an entry that pointed
+ * at nothing.)
+ *
+ * Meshes are deliberately untouched: niivue's mesh URL-restore path does not
+ * reapply scalar-overlay layers or tract options, so a linked mesh loses that
+ * state silently.
+ *
+ * Mutates and returns `doc`.
+ */
+export declare function retargetVolumeUrls(doc: Record<string, unknown>, volumeUrls: (string | null)[]): Record<string, unknown>;

package/dist-lib/types/lib/random-session-name.d.ts

@@ -0,0 +1 @@
+export declare function randomSessionName(): string;

package/dist-lib/types/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist-lib/types/lib.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `freebrowse` — framework-agnostic entry. React is bundled; the host only
+ * needs `@niivue/niivue` (peer) and `import "freebrowse/style.css"`.
+ *
+ *   import { NiiVue } from "@niivue/niivue";
+ *   import { mountFreeBrowse } from "freebrowse";
+ *   import "freebrowse/style.css";
+ *   const nv = new NiiVue();
+ *   const fb = mountFreeBrowse(document.getElementById("viewer"), { nv });
+ *   await nv.addVolume({ url: "..." });   // the FreeBrowse UI follows
+ *   fb.destroy();
+ */
+export { mountFreeBrowse } from "./mount.js";
+export type { MountOptions, FreeBrowseHandle } from "./mount.js";
+export { createFreeBrowseInstance, DEFAULT_NIIVUE_OPTIONS, } from "./lib/default-niivue-options.js";
+export { configureFreeBrowse, getFreeBrowseConfig, type FreeBrowseBackend, type FreeBrowseConfig, } from "./lib/deployment-config.js";

package/dist-lib/types/mount.d.ts

@@ -0,0 +1,49 @@
+import type { NiiVue } from "@niivue/niivue";
+import { type FreeBrowseBackend } from "./lib/deployment-config.js";
+export interface MountOptions {
+    /**
+     * The NiiVue instance to show. When given, the host owns it: FreeBrowse
+     * seeds its UI from the instance's current settings and never pushes its
+     * own defaults onto it. When omitted, FreeBrowse creates one with
+     * `createFreeBrowseInstance()` and applies its defaults.
+     */
+    nv?: NiiVue;
+    /**
+     * Backend endpoints for Save-to-server, the Data/NVD tabs and AI sessions.
+     * Omitted (or `null`): no backend — those features are hidden.
+     */
+    backend?: FreeBrowseBackend | null;
+    /** localStorage key for user preferences (default `freebrowse-user-settings`), or `false` to keep them in memory. */
+    persist?: string | false;
+    /** Read `?nvd=` / `?vol=` from the host page URL on startup. Default false. */
+    readUrlParams?: boolean;
+    /** Also publish the instance as `window.freebrowse.nv`. Default false. */
+    exposeGlobal?: boolean;
+    /** Disable the Download button and niivue's save-to-disk methods. Default false. */
+    downloadDisabled?: boolean;
+    /**
+     * Allow loading by drag-and-drop (niivue's canvas drop and FreeBrowse's
+     * drop zone). `false` also skips the drop zone and shows the canvas from
+     * the start, for hosts that load data themselves. Default true.
+     */
+    dragDrop?: boolean;
+    /** Show the sidebar initially (the header button still toggles it). Default true. */
+    sidebar?: boolean;
+    /** Show the footer (coordinate readout) initially. Default true. */
+    footer?: boolean;
+}
+export interface FreeBrowseHandle {
+    /** The instance FreeBrowse is showing (the one passed in, or the one it created). */
+    nv: NiiVue;
+    /** Unmount the UI and detach FreeBrowse's event listeners from the instance. */
+    destroy(): void;
+}
+/**
+ * Mount the FreeBrowse UI into `container` and return a handle.
+ *
+ * One mount at a time: FreeBrowse's UI state is a single store, so a second
+ * concurrent mount throws. Call `destroy()` on the previous handle first.
+ *
+ * Styles are not injected — import `freebrowse/style.css` once in the host.
+ */
+export declare function mountFreeBrowse(container: HTMLElement, options?: MountOptions): FreeBrowseHandle;

package/dist-lib/types/react.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `freebrowse/react` — for hosts that already render React 19: the component
+ * itself (React and ReactDOM are peer dependencies on this entry, not bundled).
+ * Configure once with `configureFreeBrowse` before the first render, and import
+ * `freebrowse/style.css` in the host.
+ */
+export { default as FreeBrowse } from "./components/freebrowse.js";
+export type { FreeBrowseProps } from "./components/freebrowse.js";
+export { configureFreeBrowse, getFreeBrowseConfig, type FreeBrowseBackend, type FreeBrowseConfig, } from "./lib/deployment-config.js";
+export { createFreeBrowseInstance, DEFAULT_NIIVUE_OPTIONS, } from "./lib/default-niivue-options.js";

package/dist-lib/types/store/ai-slice.d.ts

@@ -0,0 +1,25 @@
+import type { StateCreator } from "zustand";
+export type AiSessionSummary = {
+    session_id: string;
+    session_name: string;
+    created_at: string;
+    volume_path: string | null;
+    volume_path_root: "data" | "session" | null;
+    annotation_path: string | null;
+    result_path: string | null;
+    last_inference_ml_id: string | null;
+    last_inference_at: string | null;
+};
+export type AiActiveSession = {
+    session_id: string;
+    session_name: string;
+};
+export interface AiSlice {
+    aiEnabled: boolean | null;
+    aiSessions: AiSessionSummary[];
+    aiActiveSession: AiActiveSession | null;
+    setAiEnabled: (enabled: boolean | null) => void;
+    setAiSessions: (sessions: AiSessionSummary[]) => void;
+    setAiActiveSession: (session: AiActiveSession | null) => void;
+}
+export declare const createAiSlice: StateCreator<AiSlice>;

package/dist-lib/types/store/drawing-slice.d.ts

@@ -0,0 +1,7 @@
+import type { StateCreator } from "zustand";
+import type { DrawingOptions } from "./types";
+export interface DrawingSlice {
+    drawingOptions: DrawingOptions;
+    setDrawingOptions: (options: DrawingOptions | ((prev: DrawingOptions) => DrawingOptions)) => void;
+}
+export declare const createDrawingSlice: StateCreator<DrawingSlice>;

package/dist-lib/types/store/index.d.ts

@@ -0,0 +1,21 @@
+import { type VolumeSlice } from "./volume-slice";
+import { type SurfaceSlice } from "./surface-slice";
+import { type DrawingSlice } from "./drawing-slice";
+import { type ViewerSlice } from "./viewer-slice";
+import { type SaveSlice } from "./save-slice";
+import { type LocationSlice } from "./location-slice";
+import { type AiSlice } from "./ai-slice";
+export type FreeBrowseStore = VolumeSlice & SurfaceSlice & DrawingSlice & ViewerSlice & SaveSlice & LocationSlice & AiSlice;
+export declare const useFreeBrowseStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<FreeBrowseStore>, "persist" | "setState"> & {
+    setState(partial: FreeBrowseStore | Partial<FreeBrowseStore> | ((state: FreeBrowseStore) => FreeBrowseStore | Partial<FreeBrowseStore>), replace?: false | undefined): unknown;
+    setState(state: FreeBrowseStore | ((state: FreeBrowseStore) => FreeBrowseStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<FreeBrowseStore, unknown, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: FreeBrowseStore) => void) => () => void;
+        onFinishHydration: (fn: (state: FreeBrowseStore) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<FreeBrowseStore, unknown, unknown>>;
+    };
+}>;

package/dist-lib/types/store/location-slice.d.ts

@@ -0,0 +1,7 @@
+import type { StateCreator } from "zustand";
+import type { LocationData } from "./types";
+export interface LocationSlice {
+    locationData: LocationData | null;
+    setLocationData: (data: LocationData | null) => void;
+}
+export declare const createLocationSlice: StateCreator<LocationSlice>;

package/dist-lib/types/store/niivue-store-sync.d.ts

@@ -0,0 +1,41 @@
+import type { ViewerOptions } from "./types.js";
+import type { NiiVueEventSource, NiiVueSyncTarget } from "./niivue-sync";
+/**
+ * Concrete NiiVueSyncTarget backed by the FreeBrowse Zustand store.
+ *
+ * This is the adapter that makes the store a *derived view* of niivue state:
+ * `registerNiiVueEvents(nv, createStoreSyncTarget(nv))` routes every relevant
+ * niivue event into the store, translating niivue-mono property names/values
+ * into FreeBrowse's store shape. Because both FreeBrowse's own command wrappers
+ * and external callers (e.g. `window.freebrowse.nv`) drive niivue through the
+ * same events, the UI follows either path identically.
+ *
+ * The volume/surface UI reads live `nv.volumes`/`nv.meshes` and re-renders on a
+ * version-counter bump, so those events bump the counter rather than mirroring
+ * a list into the store. Viewer options and location are mirrored into store
+ * slices.
+ */
+/** niivue reader surface this adapter needs beyond the event target. */
+export type NiiVueReader = NiiVueEventSource & {
+    sliceType: number;
+    showRender: number;
+    crosshairWidth?: number;
+    crosshairGap?: number;
+    crosshairColor?: number[];
+    rulerWidth?: number;
+    isRulerVisible?: boolean;
+    volumeIsNearestInterpolation?: boolean;
+    volumeOutlineWidth?: number;
+    isColorbarVisible?: boolean;
+    isRadiological?: boolean;
+    secondaryDragMode?: number;
+};
+/**
+ * Read the instance's current settings as a viewerOptions patch — the
+ * nv -> store direction, for seeding the store from an instance the host
+ * built (so FreeBrowse never pushes its own defaults onto it). Only settings
+ * the instance actually reports (not undefined) are included, so a partial
+ * reader (or the test mock) leaves the rest of the store alone.
+ */
+export declare function readViewerFromNiiVue(nv: NiiVueReader): Partial<ViewerOptions>;
+export declare function createStoreSyncTarget(nv: NiiVueReader): NiiVueSyncTarget;

package/dist-lib/types/store/niivue-sync.d.ts

@@ -0,0 +1,57 @@
+/**
+ * registerNiiVueEvents — the single event-driven sync bridge between a
+ * niivue-mono `NiiVue` instance and FreeBrowse's UI state.
+ *
+ * niivue-mono's controller extends `EventTarget` and emits a `CustomEvent` for
+ * every state mutation that goes through its API (setters + methods). By making
+ * FreeBrowse's store a *derived view* updated only from these events, both
+ * FreeBrowse's own command wrappers and external code (a developer holding
+ * `window.freebrowse.nv`) drive the UI through the identical path.
+ *
+ * Dedupe strategy: every flat scalar setter emits a generic
+ * `change {property, value}`, and a handful ALSO emit a specific event
+ * (`sliceTypeChange`, `azimuthElevationChange`, `drawingEnabled`,
+ * `penValueChanged`). We subscribe to `change` as the single source of truth for
+ * scalars and deliberately ignore those scalar-mirror events, so each scalar is
+ * handled exactly once. Specific events are used ONLY where `change` carries no
+ * equivalent: structural volume/mesh changes, drawing actions, location, etc.
+ *
+ * Phase 0: this is the dispatcher skeleton + its {@link NiiVueSyncTarget}
+ * contract, verified against the event-emitting mock. The concrete adapter that
+ * maps these intent callbacks onto the Zustand store (with niivue->store name
+ * and value translation) is added as hooks convert in Phase 2+.
+ */
+/** Minimal shape of a niivue instance this bridge needs. */
+export interface NiiVueEventSource extends EventTarget {
+    volumes: unknown[];
+    meshes: unknown[];
+}
+/**
+ * Intent-level sink for niivue state changes. Phase 2+ provides a concrete
+ * implementation backed by the Zustand store; tests provide spies.
+ */
+export interface NiiVueSyncTarget {
+    /** A flat viewer/scene scalar changed (niivue property name + new value). */
+    onViewerOptionChange(property: string, value: unknown): void;
+    /** A drawing-related scalar changed (pen value, opacity, colormap, ...). */
+    onDrawingOptionChange(property: string, value: unknown): void;
+    /** The volume list changed (add / remove / reorder / update) — re-read `volumes`. */
+    onVolumesChanged(volumes: unknown[]): void;
+    /** A single volume's properties changed, with the exact applied subset. */
+    onVolumeUpdated(index: number, changes: Record<string, unknown>): void;
+    /** The mesh list or a mesh/layer changed — re-read `meshes`. */
+    onSurfacesChanged(meshes: unknown[]): void;
+    /** Drawing state changed; `action` is create/close/undo/stroke/load/update. */
+    onDrawingChanged(action: string): void;
+    /** Crosshair moved (interaction or a location-emitting method). */
+    onLocationChange(location: unknown): void;
+    /** A document finished loading (volumes/meshes/scene already applied). */
+    onDocumentLoaded(): void;
+    /** A colormap was registered by name. */
+    onColormapAdded(name: string): void;
+}
+/**
+ * Subscribe `target` to all relevant events on `nv`. Returns a teardown that
+ * removes every listener (call it on unmount / instance replacement).
+ */
+export declare function registerNiiVueEvents(nv: NiiVueEventSource, target: NiiVueSyncTarget): () => void;

package/dist-lib/types/store/save-slice.d.ts

@@ -0,0 +1,9 @@
+import type { StateCreator } from "zustand";
+import type { SaveState } from "./types";
+export interface SaveSlice {
+    saveDialogOpen: boolean;
+    saveState: SaveState;
+    setSaveDialogOpen: (open: boolean) => void;
+    setSaveState: (state: SaveState | ((prev: SaveState) => SaveState)) => void;
+}
+export declare const createSaveSlice: StateCreator<SaveSlice>;

package/dist-lib/types/store/surface-slice.d.ts

@@ -0,0 +1,15 @@
+import type { StateCreator } from "zustand";
+import type { SurfaceDetails } from "./types";
+export interface SurfaceSlice {
+    surfaces: SurfaceDetails[];
+    currentSurfaceIndex: number | null;
+    surfaceToRemove: number | null;
+    selectedLayerIndex: number | null;
+    layerVersion: number;
+    setSurfaces: (surfaces: SurfaceDetails[] | ((prev: SurfaceDetails[]) => SurfaceDetails[])) => void;
+    setCurrentSurfaceIndex: (index: number | null) => void;
+    setSurfaceToRemove: (index: number | null) => void;
+    setSelectedLayerIndex: (index: number | null) => void;
+    incrementLayerVersion: () => void;
+}
+export declare const createSurfaceSlice: StateCreator<SurfaceSlice>;

package/dist-lib/types/store/types.d.ts

@@ -0,0 +1,69 @@
+import type { SerializeOptions } from "@niivue/niivue";
+import type { DragMode } from "../components/drag-mode-selector.js";
+export type SurfaceDetails = {
+    id: string;
+    name: string;
+    visible: boolean;
+    opacity: number;
+    rgba255: [number, number, number, number];
+    shaderType: string;
+};
+export type ViewMode = "axial" | "coronal" | "sagittal" | "ACS" | "ACSR" | "render";
+export type ViewerOptions = {
+    viewMode: ViewMode;
+    crosshairWidth: number;
+    crosshairGap: number;
+    crosshairVisible: boolean;
+    crosshairColor: [number, number, number, number];
+    rulerWidth: number;
+    rulerVisible: boolean;
+    interpolateVoxels: boolean;
+    dragMode: DragMode;
+    overlayOutlineWidth: number;
+    isColorbar: boolean;
+    isRadiologicalConvention: boolean;
+    sagittalNoseLeft: boolean;
+};
+export type DrawingOptions = {
+    enabled: boolean;
+    mode: "none" | "pen" | "wand";
+    penValue: number;
+    penFill: boolean;
+    penErases: boolean;
+    opacity: number;
+    colormap: string;
+    magicWand2dOnly: boolean;
+    magicWandMaxDistanceMM: number;
+    magicWandThresholdPercent: number;
+    filename: string;
+};
+export type LocationData = {
+    mm: [number, number, number];
+    voxels: Array<{
+        name: string;
+        voxel: [number, number, number];
+        value: number;
+    }>;
+};
+export type SaveVolumeState = {
+    enabled: boolean;
+    isExternal: boolean;
+    url: string;
+};
+/**
+ * On-disk niivue Document encoding chosen at save time. Derived from niivue's
+ * own option type so a future upstream format is a compile error at the save
+ * dialog rather than a silent divergence.
+ */
+export type NvdFormat = NonNullable<SerializeOptions["format"]>;
+export type SaveState = {
+    isDownloadMode: boolean;
+    document: {
+        enabled: boolean;
+        location: string;
+        /** Both are native niivue encodings: JSON is portable and diffable,
+         * CBOR is the compact binary default. */
+        format: NvdFormat;
+    };
+    volumes: SaveVolumeState[];
+};