@niivue/nvreact 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# @niivue/nvreact
+
+Lightweight React bindings for [Niivue](https://github.com/niivue/niivue) with multi-instance scene management, declarative hooks, and a standalone viewer component.
+
+## Install
+
+```bash
+npm install @niivue/nvreact @niivue/niivue react react-dom
+```
+
+## Quick start
+
+```tsx
+import { NvScene, NvSceneProvider, useScene } from "@niivue/nvreact";
+
+function App() {
+  const { scene, snapshot } = useScene();
+  return (
+    <NvSceneProvider scene={scene}>
+      <p>{snapshot.viewerCount} viewers</p>
+      <button onClick={() => scene.addViewer()}>Add</button>
+      <NvScene scene={scene} style={{ height: 600 }} />
+    </NvSceneProvider>
+  );
+}
+```
+
+## Standalone viewer
+
+`NvViewer` is a single-instance component with declarative volume management — pass a `volumes` array and it handles loading/diffing automatically.
+
+```tsx
+import { NvViewer } from "@niivue/nvreact";
+
+function App() {
+  return (
+    <NvViewer
+      volumes={[{ url: "https://example.com/brain.nii.gz", name: "brain" }]}
+      style={{ height: 600 }}
+      onImageLoaded={(vol) => console.log("loaded:", vol.name)}
+      onLocationChange={(data) => console.log("location:", data)}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### NvViewer props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `volumes` | `ImageFromUrlOptions[]` | Volumes to load (diffed automatically) |
+| `options` | `Partial<NVConfigOptions>` | Niivue config overrides |
+| `sliceType` | `number` | Slice type (default: `SLICE_TYPE.AXIAL`) |
+| `className` | `string` | CSS class for the container div |
+| `style` | `CSSProperties` | Inline styles for the container div |
+| `onLocationChange` | `(data) => void` | Crosshair location callback |
+| `onImageLoaded` | `(volume: NVImage) => void` | Volume loaded callback |
+| `onError` | `(error) => void` | Error callback |
+
+## Hooks
+
+### `useScene(controller?, layouts?, viewerDefaults?)`
+
+Creates (or wraps) an `NvSceneController` and subscribes to its snapshot via `useSyncExternalStore`.
+
+```tsx
+const { scene, snapshot } = useScene();
+```
+
+Pass an existing controller to wrap it instead of creating a new one:
+
+```tsx
+const controller = useMemo(() => new NvSceneController(defaultLayouts), []);
+const { scene, snapshot } = useScene(controller);
+```
+
+### `useNiivue(scene, index)`
+
+Returns the raw `Niivue` instance at the given viewer index, or `undefined` if the index is out of range.
+
+```tsx
+const nv = useNiivue(scene, 0);
+```
+
+### `useSceneEvent(scene, event, callback)`
+
+Subscribes to scene events with automatic cleanup. The callback ref is stable so it always calls the latest function.
+
+```tsx
+useSceneEvent(scene, "viewerCreated", (nv, index) => {
+  console.log(`viewer ${index} created`);
+});
+
+useSceneEvent(scene, "imageLoaded", (viewerIndex, volume) => {
+  console.log(`loaded ${volume.name} in viewer ${viewerIndex}`);
+});
+```
+
+#### Events
+
+| Event | Callback signature |
+|-------|-------------------|
+| `viewerCreated` | `(nv: Niivue, index: number) => void` |
+| `viewerRemoved` | `(index: number) => void` |
+| `locationChange` | `(viewerIndex: number, data: unknown) => void` |
+| `imageLoaded` | `(viewerIndex: number, volume: NVImage) => void` |
+| `error` | `(viewerIndex: number, error: unknown) => void` |
+| `volumeAdded` | `(viewerIndex: number, imageOptions, image: NVImage) => void` |
+| `volumeRemoved` | `(viewerIndex: number, url: string) => void` |
+
+## Context
+
+`NvSceneProvider` makes a scene controller available to any descendant via `useSceneContext()`.
+
+```tsx
+import { NvSceneProvider, useSceneContext } from "@niivue/nvreact";
+
+function Toolbar() {
+  const scene = useSceneContext();
+  return <button onClick={() => scene.addViewer()}>Add</button>;
+}
+
+function App() {
+  const { scene, snapshot } = useScene();
+  return (
+    <NvSceneProvider scene={scene}>
+      <Toolbar />
+      <NvScene scene={scene} />
+    </NvSceneProvider>
+  );
+}
+```
+
+## Scene controller
+
+### Viewer management
+
+```tsx
+scene.addViewer();
+scene.removeViewer(0);
+scene.canAddViewer(); // false when at layout capacity
+```
+
+### Layouts
+
+```tsx
+import { defaultLayouts } from "@niivue/nvreact";
+
+// Layout keys are rows x columns (e.g. "2x2", "1x2", "3x3")
+scene.setLayout("2x2");
+```
+
+### Per-viewer slice layouts
+
+```tsx
+import { defaultSliceLayouts } from "@niivue/nvreact";
+
+scene.setViewerSliceLayout(0, defaultSliceLayouts["axial-hero"].layout);
+scene.setViewerSliceLayout(0, null); // reset to default
+```
+
+### Broadcast interactions
+
+```tsx
+scene.setBroadcasting(true); // sync crosshair across all viewers
+```
+
+### Volume management
+
+```tsx
+await scene.loadVolume(0, { url: "https://example.com/brain.nii.gz", name: "brain" });
+await scene.loadVolumes(0, [
+  { url: "https://example.com/t1.nii.gz", name: "t1" },
+  { url: "https://example.com/overlay.nii.gz", name: "overlay" },
+]);
+scene.removeVolume(0, "https://example.com/brain.nii.gz");
+```
+
+## API reference
+
+### Components
+
+- **`NvScene`** — multi-viewer container bound to an `NvSceneController`
+- **`NvViewer`** — standalone single-instance viewer with declarative volumes
+
+### Hooks
+
+- **`useScene(controller?, layouts?, viewerDefaults?)`** — create/wrap a controller + subscribe to snapshots
+- **`useNiivue(scene, index)`** — access a raw `Niivue` instance by index
+- **`useSceneEvent(scene, event, callback)`** — subscribe to controller events
+
+### Context
+
+- **`NvSceneProvider`** — provides an `NvSceneController` via React context
+- **`useSceneContext()`** — consume the nearest `NvSceneProvider`
+
+### Controller
+
+- **`NvSceneController`** — manages multiple Niivue instances, layout, broadcasting, and volumes
+- **`NvSceneController#on(event, handler)`** / **`off(event, handler)`** — event subscription
+- **`NvSceneController#loadVolume(index, opts)`** / **`loadVolumes(index, opts[])`** — load volumes into a viewer
+- **`NvSceneController#removeVolume(index, url)`** — remove a volume by URL
+
+### Presets
+
+- **`defaultLayouts`** — grid layout presets (1x1, 1x2, 2x2, etc.)
+- **`defaultSliceLayouts`** — per-viewer slice layout presets
+- **`defaultViewerOptions`** — default Niivue config
+- **`defaultMouseConfig`** — default mouse interaction config
+
+## Build (local)
+
+```bash
+bun run build:package
+```
+
+## Publish
+
+```bash
+bun run build:package
+bun publish --access public
+```

package/dist/lib.js

@@ -0,0 +1,692 @@
+// src/nvscene.tsx
+import { useEffect, useRef } from "react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+var NvScene = ({
+  scene,
+  className,
+  style,
+  initialLayout = "1x1"
+}) => {
+  const containerRef = useRef(null);
+  useEffect(() => {
+    if (containerRef.current) {
+      scene.setContainerElement(containerRef.current);
+      if (scene.viewers.length === 0) {
+        scene.setLayout(initialLayout);
+      }
+    }
+    return () => {
+      scene.setContainerElement(null);
+    };
+  }, [scene, initialLayout]);
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el)
+      return;
+    const ro = new ResizeObserver(() => scene.updateLayout());
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [scene]);
+  return /* @__PURE__ */ jsxDEV("div", {
+    ref: containerRef,
+    className,
+    style
+  }, undefined, false, undefined, this);
+};
+// src/nvviewer.tsx
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+import {
+  Niivue as Niivue2,
+  SLICE_TYPE as SLICE_TYPE2
+} from "@niivue/niivue";
+
+// src/nvscene-controller.ts
+import {
+  DRAG_MODE,
+  Niivue,
+  SLICE_TYPE,
+  SHOW_RENDER
+} from "@niivue/niivue";
+
+// src/layouts.ts
+var layout1x1 = () => ({
+  top: "0",
+  left: "0",
+  width: "100%",
+  height: "100%"
+});
+var layout2x2 = (_containerElement, index) => {
+  const row = Math.floor(index / 2);
+  const col = index % 2;
+  return {
+    top: `${row * 50}%`,
+    left: `${col * 50}%`,
+    width: "50%",
+    height: "50%"
+  };
+};
+var layout1x2 = (_containerElement, index) => ({
+  top: "0",
+  left: `${index * 50}%`,
+  width: "50%",
+  height: "100%"
+});
+var layout2x1 = (_containerElement, index) => ({
+  top: `${index * 50}%`,
+  left: "0",
+  width: "100%",
+  height: "50%"
+});
+var layout1x3 = (_containerElement, index) => ({
+  top: "0",
+  left: `${index * 33.333}%`,
+  width: "33.333%",
+  height: "100%"
+});
+var layout3x1 = (_containerElement, index) => ({
+  top: `${index * 33.333}%`,
+  left: "0",
+  width: "100%",
+  height: "33.333%"
+});
+var layout3x3 = (_containerElement, index) => {
+  const row = Math.floor(index / 3);
+  const col = index % 3;
+  return {
+    top: `${row * 33.333}%`,
+    left: `${col * 33.333}%`,
+    width: "33.333%",
+    height: "33.333%"
+  };
+};
+var defaultLayouts = {
+  "1x1": {
+    slots: 1,
+    label: "1x1",
+    layoutFunction: layout1x1
+  },
+  "1x2": {
+    slots: 2,
+    label: "1x2",
+    layoutFunction: layout1x2
+  },
+  "2x1": {
+    slots: 2,
+    label: "2x1",
+    layoutFunction: layout2x1
+  },
+  "1x3": {
+    slots: 3,
+    label: "1x3",
+    layoutFunction: layout1x3
+  },
+  "3x1": {
+    slots: 3,
+    label: "3x1",
+    layoutFunction: layout3x1
+  },
+  "2x2": {
+    slots: 4,
+    label: "2x2",
+    layoutFunction: layout2x2
+  },
+  "3x3": {
+    slots: 9,
+    label: "3x3",
+    layoutFunction: layout3x3
+  }
+};
+
+// src/nvscene-controller.ts
+var defaultSliceLayout = [
+  { sliceType: SLICE_TYPE.AXIAL, position: [0, 0, 1, 0.8] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0, 0.8, 0.5, 0.2] },
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0.5, 0.8, 0.5, 0.2] }
+];
+var splitSliceLayout = [
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0, 0, 0.5, 1] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0.5, 0, 0.5, 0.5] },
+  { sliceType: SLICE_TYPE.AXIAL, position: [0.5, 0.5, 0.5, 0.5] }
+];
+var triSliceLayout = [
+  { sliceType: SLICE_TYPE.AXIAL, position: [0, 0, 0.333, 1] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0.333, 0, 0.333, 1] },
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0.666, 0, 0.334, 1] }
+];
+var stackedSliceLayout = [
+  { sliceType: SLICE_TYPE.AXIAL, position: [0, 0, 1, 0.333] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0, 0.333, 1, 0.333] },
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0, 0.666, 1, 0.334] }
+];
+var quadSliceLayout = [
+  { sliceType: SLICE_TYPE.AXIAL, position: [0, 0, 0.5, 0.5] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0.5, 0, 0.5, 0.5] },
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0, 0.5, 0.5, 0.5] },
+  { sliceType: SLICE_TYPE.RENDER, position: [0.5, 0.5, 0.5, 0.5] }
+];
+var heroRenderSliceLayout = [
+  { sliceType: SLICE_TYPE.RENDER, position: [0, 0, 1, 0.7] },
+  { sliceType: SLICE_TYPE.AXIAL, position: [0, 0.7, 0.333, 0.3] },
+  { sliceType: SLICE_TYPE.CORONAL, position: [0.333, 0.7, 0.333, 0.3] },
+  { sliceType: SLICE_TYPE.SAGITTAL, position: [0.666, 0.7, 0.334, 0.3] }
+];
+var defaultSliceLayouts = {
+  "axial-hero": {
+    label: "Axial Hero",
+    layout: defaultSliceLayout
+  },
+  "sag-left": {
+    label: "Sag Left Split",
+    layout: splitSliceLayout
+  },
+  "tri-h": {
+    label: "Tri Horizontal",
+    layout: triSliceLayout
+  },
+  "tri-v": {
+    label: "Tri Stacked",
+    layout: stackedSliceLayout
+  },
+  "quad-render": {
+    label: "Quad Render",
+    layout: quadSliceLayout
+  },
+  "render-hero": {
+    label: "Render Hero",
+    layout: heroRenderSliceLayout
+  }
+};
+var defaultViewerOptions = {
+  crosshairGap: 5
+};
+var defaultMouseConfig = {
+  leftButton: {
+    primary: DRAG_MODE.crosshair
+  },
+  rightButton: DRAG_MODE.pan,
+  centerButton: DRAG_MODE.slicer3D
+};
+
+class NvSceneController {
+  containerElement = null;
+  viewers = [];
+  currentLayout = "1x1";
+  slots;
+  layouts;
+  onViewerCreated;
+  listeners = new Set;
+  snapshotCache = null;
+  nextId = 0;
+  viewersById = new Map;
+  broadcasting = false;
+  broadcastOptions = { "2d": true, "3d": true };
+  viewerSliceLayouts = new Map;
+  viewerDefaults;
+  eventListeners = new Map;
+  loadingCounts = new Map;
+  viewerErrors = new Map;
+  constructor(layouts = defaultLayouts, viewerDefaults = {}) {
+    this.layouts = layouts;
+    this.slots = this.layouts[this.currentLayout]?.slots ?? 1;
+    this.viewerDefaults = viewerDefaults;
+  }
+  on(event, cb) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set);
+    }
+    this.eventListeners.get(event).add(cb);
+    return () => this.off(event, cb);
+  }
+  off(event, cb) {
+    this.eventListeners.get(event)?.delete(cb);
+  }
+  emit(event, ...args) {
+    const listeners = this.eventListeners.get(event);
+    if (!listeners)
+      return;
+    for (const cb of listeners) {
+      cb(...args);
+    }
+  }
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getSnapshot = () => {
+    if (!this.snapshotCache) {
+      const viewerStates = this.viewers.map((v) => ({
+        id: v.id,
+        loading: this.loadingCounts.get(v.id) ?? 0,
+        errors: this.viewerErrors.get(v.id) ?? []
+      }));
+      this.snapshotCache = {
+        currentLayout: this.currentLayout,
+        viewerCount: this.viewers.length,
+        slots: this.slots,
+        isBroadcasting: this.broadcasting,
+        isLoading: viewerStates.some((s) => s.loading > 0),
+        viewerStates
+      };
+    }
+    return this.snapshotCache;
+  };
+  notify() {
+    this.snapshotCache = null;
+    this.listeners.forEach((listener) => listener());
+  }
+  setContainerElement(element) {
+    this.containerElement = element;
+    if (element) {
+      this.updateLayout();
+    }
+  }
+  setLayout(layoutName) {
+    const layoutConfig = this.layouts[layoutName];
+    if (!layoutConfig)
+      return;
+    this.currentLayout = layoutName;
+    this.slots = layoutConfig.slots;
+    while (this.viewers.length > this.slots) {
+      this.removeViewer(this.viewers.length - 1, false);
+    }
+    if (this.viewers.length === 0 && this.containerElement) {
+      this.addViewer();
+    }
+    this.updateLayout();
+    this.notify();
+  }
+  updateLayout() {
+    if (!this.containerElement)
+      return;
+    const layoutConfig = this.layouts[this.currentLayout];
+    if (!layoutConfig)
+      return;
+    this.viewers.forEach((viewer, index) => {
+      const position = layoutConfig.layoutFunction(this.containerElement, index, this.viewers.length);
+      Object.assign(viewer.containerDiv.style, {
+        position: "absolute",
+        top: position.top,
+        left: position.left,
+        width: position.width,
+        height: position.height
+      });
+    });
+  }
+  canAddViewer() {
+    return this.viewers.length < this.slots;
+  }
+  getNiivue(index) {
+    return this.viewers[index]?.niivue;
+  }
+  getAllNiivue() {
+    return this.viewers.map((viewer) => viewer.niivue);
+  }
+  forEachNiivue(callback) {
+    this.viewers.forEach((viewer, i) => callback(viewer.niivue, i));
+  }
+  setBroadcasting(enabled, options) {
+    this.broadcasting = enabled;
+    if (options) {
+      this.broadcastOptions = { ...this.broadcastOptions, ...options };
+    }
+    if (enabled) {
+      this.viewers.forEach((viewer) => {
+        const others = this.viewers.filter((v) => v.id !== viewer.id).map((v) => v.niivue);
+        viewer.niivue.broadcastTo(others, this.broadcastOptions);
+      });
+    } else {
+      this.viewers.forEach((viewer) => {
+        viewer.niivue.broadcastTo([], this.broadcastOptions);
+      });
+    }
+    this.notify();
+  }
+  isBroadcasting() {
+    return this.broadcasting;
+  }
+  setViewerSliceLayout(index, layout) {
+    const viewer = this.viewers[index];
+    if (!viewer)
+      return;
+    this.viewerSliceLayouts.set(viewer.id, layout);
+    this.applySliceLayout(viewer.niivue, layout);
+    this.notify();
+  }
+  getViewerSliceLayout(index) {
+    const viewer = this.viewers[index];
+    if (!viewer)
+      return null;
+    return this.viewerSliceLayouts.get(viewer.id) ?? null;
+  }
+  applySliceLayout(nv, layout) {
+    if (layout) {
+      nv.setCustomLayout(layout);
+    } else {
+      nv.clearCustomLayout();
+      nv.setSliceType(SLICE_TYPE.AXIAL);
+      nv.opts.multiplanarShowRender = SHOW_RENDER.NEVER;
+    }
+  }
+  getNiivueById(id) {
+    return this.viewersById.get(id)?.niivue;
+  }
+  getViewerById(id) {
+    return this.viewersById.get(id);
+  }
+  async loadVolume(index, opts) {
+    const viewer = this.viewers[index];
+    if (!viewer)
+      throw new Error(`No viewer at index ${index}`);
+    this.incrementLoading(viewer.id);
+    try {
+      const image = await viewer.niivue.addVolumeFromUrl(opts);
+      this.emit("volumeAdded", index, opts, image);
+      return image;
+    } catch (err) {
+      this.addError(viewer.id, err);
+      this.emit("error", index, err);
+      throw err;
+    } finally {
+      this.decrementLoading(viewer.id);
+    }
+  }
+  async loadVolumes(index, opts) {
+    const results = [];
+    for (const o of opts) {
+      results.push(await this.loadVolume(index, o));
+    }
+    return results;
+  }
+  removeVolume(index, url) {
+    const viewer = this.viewers[index];
+    if (!viewer)
+      return;
+    const nv = viewer.niivue;
+    const vol = nv.volumes.find((v) => v.url === url || v.name === url);
+    if (vol) {
+      nv.removeVolume(vol);
+      this.emit("volumeRemoved", index, url);
+      this.notify();
+    }
+  }
+  incrementLoading(id) {
+    this.loadingCounts.set(id, (this.loadingCounts.get(id) ?? 0) + 1);
+    this.notify();
+  }
+  decrementLoading(id) {
+    const count = (this.loadingCounts.get(id) ?? 1) - 1;
+    this.loadingCounts.set(id, Math.max(0, count));
+    this.notify();
+  }
+  addError(id, error) {
+    const errors = this.viewerErrors.get(id) ?? [];
+    errors.push(error);
+    this.viewerErrors.set(id, errors);
+  }
+  addViewer(options) {
+    if (!this.containerElement) {
+      throw new Error("Container element not set");
+    }
+    if (!this.canAddViewer()) {
+      throw new Error(`Cannot add viewer: slot limit of ${this.slots} reached`);
+    }
+    const containerDiv = document.createElement("div");
+    containerDiv.className = "niivue-canvas-container";
+    const canvas = document.createElement("canvas");
+    canvas.className = "niivue-canvas";
+    containerDiv.appendChild(canvas);
+    this.containerElement.appendChild(containerDiv);
+    const mergedOptions = {
+      ...defaultViewerOptions,
+      ...this.viewerDefaults,
+      ...options
+    };
+    const niivue = new Niivue(mergedOptions);
+    niivue.setMouseEventConfig(defaultMouseConfig);
+    niivue.attachToCanvas(canvas);
+    const id = `nv-${this.nextId++}`;
+    this.viewerSliceLayouts.set(id, null);
+    this.loadingCounts.set(id, 0);
+    this.viewerErrors.set(id, []);
+    const viewer = {
+      id,
+      niivue,
+      canvasElement: canvas,
+      containerDiv
+    };
+    this.viewers.push(viewer);
+    this.viewersById.set(id, viewer);
+    this.updateLayout();
+    this.applySliceLayout(niivue, null);
+    const index = this.viewers.length - 1;
+    niivue.onLocationChange = (data) => {
+      this.emit("locationChange", index, data);
+    };
+    niivue.onImageLoaded = (vol) => {
+      this.emit("imageLoaded", index, vol);
+    };
+    if (this.broadcasting) {
+      this.setBroadcasting(true);
+    }
+    this.onViewerCreated?.(niivue, index);
+    this.emit("viewerCreated", niivue, index);
+    this.notify();
+    return viewer;
+  }
+  removeViewer(index, shouldNotify = true) {
+    if (index < 0 || index >= this.viewers.length)
+      return;
+    const viewer = this.viewers[index];
+    if (!viewer)
+      return;
+    this.viewersById.delete(viewer.id);
+    this.viewerSliceLayouts.delete(viewer.id);
+    this.loadingCounts.delete(viewer.id);
+    this.viewerErrors.delete(viewer.id);
+    this.disposeViewer(viewer);
+    viewer.containerDiv.remove();
+    this.viewers.splice(index, 1);
+    this.updateLayout();
+    if (this.broadcasting && this.viewers.length > 0) {
+      this.setBroadcasting(true);
+    }
+    this.emit("viewerRemoved", index);
+    if (shouldNotify) {
+      this.notify();
+    }
+  }
+  disposeViewer(viewer) {
+    const nv = viewer.niivue;
+    let gl = nv._gl;
+    if (gl) {
+      const ext = gl.getExtension("WEBGL_lose_context");
+      if (ext) {
+        ext.loseContext();
+      }
+      gl = null;
+    }
+    viewer.canvasElement.width = 0;
+    viewer.canvasElement.height = 0;
+  }
+  clearViewers() {
+    this.broadcasting = false;
+    this.viewers.forEach((viewer) => {
+      this.disposeViewer(viewer);
+      viewer.containerDiv.remove();
+    });
+    this.viewers = [];
+    this.viewersById.clear();
+    this.loadingCounts.clear();
+    this.viewerErrors.clear();
+    this.notify();
+  }
+  reset() {
+    this.clearViewers();
+    this.currentLayout = "1x1";
+    this.slots = this.layouts[this.currentLayout]?.slots ?? 1;
+    this.notify();
+  }
+}
+
+// src/nvviewer.tsx
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+var NvViewer = ({
+  volumes,
+  options,
+  sliceType = SLICE_TYPE2.AXIAL,
+  className,
+  style,
+  onLocationChange,
+  onImageLoaded,
+  onError
+}) => {
+  const containerRef = useRef2(null);
+  const nvRef = useRef2(null);
+  const loadedUrlsRef = useRef2(new Set);
+  const onLocationChangeRef = useRef2(onLocationChange);
+  onLocationChangeRef.current = onLocationChange;
+  const onImageLoadedRef = useRef2(onImageLoaded);
+  onImageLoadedRef.current = onImageLoaded;
+  const onErrorRef = useRef2(onError);
+  onErrorRef.current = onError;
+  useEffect2(() => {
+    const container = containerRef.current;
+    if (!container)
+      return;
+    const canvas = document.createElement("canvas");
+    canvas.className = "niivue-canvas";
+    canvas.style.position = "absolute";
+    canvas.style.top = "0";
+    canvas.style.left = "0";
+    canvas.style.width = "100%";
+    canvas.style.height = "100%";
+    container.appendChild(canvas);
+    const mergedOptions = {
+      ...defaultViewerOptions,
+      ...options
+    };
+    const nv = new Niivue2(mergedOptions);
+    nv.setMouseEventConfig(defaultMouseConfig);
+    nv.onLocationChange = (data) => {
+      onLocationChangeRef.current?.(data);
+    };
+    nv.onImageLoaded = (vol) => {
+      onImageLoadedRef.current?.(vol);
+    };
+    nv.attachToCanvas(canvas);
+    nv.setSliceType(sliceType);
+    nvRef.current = nv;
+    const ro = new ResizeObserver(() => {
+      nv.resizeListener();
+    });
+    ro.observe(container);
+    return () => {
+      ro.disconnect();
+      const gl = nv._gl;
+      if (gl) {
+        const ext = gl.getExtension("WEBGL_lose_context");
+        if (ext)
+          ext.loseContext();
+      }
+      canvas.width = 0;
+      canvas.height = 0;
+      canvas.remove();
+      nvRef.current = null;
+      loadedUrlsRef.current.clear();
+    };
+  }, []);
+  useEffect2(() => {
+    nvRef.current?.setSliceType(sliceType);
+  }, [sliceType]);
+  useEffect2(() => {
+    const nv = nvRef.current;
+    if (!nv)
+      return;
+    const desiredUrls = new Set((volumes ?? []).map((v) => v.url));
+    const currentUrls = loadedUrlsRef.current;
+    for (const url of currentUrls) {
+      if (!desiredUrls.has(url)) {
+        const vol = nv.volumes.find((v) => v.url === url || v.name === url);
+        if (vol)
+          nv.removeVolume(vol);
+        currentUrls.delete(url);
+      }
+    }
+    for (const opts of volumes ?? []) {
+      if (!currentUrls.has(opts.url)) {
+        currentUrls.add(opts.url);
+        nv.addVolumeFromUrl(opts).catch((err) => {
+          currentUrls.delete(opts.url);
+          onErrorRef.current?.(err);
+        });
+      }
+    }
+  }, [volumes]);
+  return /* @__PURE__ */ jsxDEV2("div", {
+    ref: containerRef,
+    className,
+    style: { position: "relative", ...style }
+  }, undefined, false, undefined, this);
+};
+// src/hooks.ts
+import { useEffect as useEffect3, useMemo, useSyncExternalStore, useRef as useRef3 } from "react";
+function useScene(controller, layouts, viewerDefaults) {
+  const scene = useMemo(() => controller ?? new NvSceneController(layouts, viewerDefaults), [controller]);
+  const snapshot = useSyncExternalStore(scene.subscribe, scene.getSnapshot, scene.getSnapshot);
+  return { scene, snapshot };
+}
+function useNiivue(scene, index) {
+  const snapshot = useSyncExternalStore(scene.subscribe, scene.getSnapshot, scene.getSnapshot);
+  return index < snapshot.viewerCount ? scene.getNiivue(index) : undefined;
+}
+function useSceneEvent(scene, event, callback) {
+  const callbackRef = useRef3(callback);
+  callbackRef.current = callback;
+  useEffect3(() => {
+    const handler = (...args) => {
+      callbackRef.current(...args);
+    };
+    return scene.on(event, handler);
+  }, [scene, event]);
+}
+// src/context.tsx
+import { createContext, useContext } from "react";
+import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+var NvSceneContext = createContext(null);
+function NvSceneProvider({
+  scene,
+  children
+}) {
+  return /* @__PURE__ */ jsxDEV3(NvSceneContext.Provider, {
+    value: scene,
+    children
+  }, undefined, false, undefined, this);
+}
+function useSceneContext() {
+  const scene = useContext(NvSceneContext);
+  if (!scene) {
+    throw new Error("useSceneContext must be used within an NvSceneProvider");
+  }
+  return scene;
+}
+export {
+  useSceneEvent,
+  useSceneContext,
+  useScene,
+  useNiivue,
+  triSliceLayout,
+  stackedSliceLayout,
+  splitSliceLayout,
+  quadSliceLayout,
+  heroRenderSliceLayout,
+  defaultViewerOptions,
+  defaultSliceLayouts,
+  defaultSliceLayout,
+  defaultMouseConfig,
+  defaultLayouts,
+  SLICE_TYPE,
+  NvViewer,
+  NvSceneProvider,
+  NvSceneController,
+  NvScene
+};

package/dist/types/context.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+import { NvSceneController } from "./nvscene-controller";
+export declare function NvSceneProvider({ scene, children, }: {
+    scene: NvSceneController;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useSceneContext(): NvSceneController;

package/dist/types/hooks.d.ts

@@ -0,0 +1,10 @@
+import type { NVConfigOptions } from "@niivue/niivue";
+import type { LayoutConfig } from "./layouts";
+import { NvSceneController } from "./nvscene-controller";
+import type { NvSceneEventMap } from "./types";
+export declare function useScene(controller?: NvSceneController, layouts?: Record<string, LayoutConfig>, viewerDefaults?: Partial<NVConfigOptions>): {
+    scene: NvSceneController;
+    snapshot: import("./nvscene-controller").NvSceneControllerSnapshot;
+};
+export declare function useNiivue(scene: NvSceneController, index: number): import("@niivue/niivue").Niivue | undefined;
+export declare function useSceneEvent<E extends keyof NvSceneEventMap>(scene: NvSceneController, event: E, callback: NvSceneEventMap[E]): void;

package/dist/types/layouts.d.ts

@@ -0,0 +1,20 @@
+export interface CanvasPosition {
+    top: string;
+    left: string;
+    width: string;
+    height: string;
+}
+export type LayoutFunction = (containerElement: HTMLElement, index: number, total: number) => CanvasPosition;
+export interface LayoutConfig {
+    slots: number;
+    label: string;
+    layoutFunction: LayoutFunction;
+}
+export declare const layout1x1: LayoutFunction;
+export declare const layout2x2: LayoutFunction;
+export declare const layout1x2: LayoutFunction;
+export declare const layout2x1: LayoutFunction;
+export declare const layout1x3: LayoutFunction;
+export declare const layout3x1: LayoutFunction;
+export declare const layout3x3: LayoutFunction;
+export declare const defaultLayouts: Record<string, LayoutConfig>;

package/dist/types/lib.d.ts

@@ -0,0 +1,9 @@
+export { NvScene } from "./nvscene";
+export { NvViewer } from "./nvviewer";
+export type { NvViewerProps } from "./nvviewer";
+export { NvSceneController, SLICE_TYPE, defaultSliceLayout, splitSliceLayout, triSliceLayout, stackedSliceLayout, quadSliceLayout, heroRenderSliceLayout, defaultSliceLayouts, defaultViewerOptions, defaultMouseConfig, } from "./nvscene-controller";
+export type { NvSceneControllerSnapshot, ViewerSlot, SliceLayoutTile, SliceLayoutConfig, BroadcastOptions, NiivueCallback, } from "./nvscene-controller";
+export { defaultLayouts } from "./layouts";
+export { useScene, useNiivue, useSceneEvent } from "./hooks";
+export { NvSceneProvider, useSceneContext } from "./context";
+export type { NvSceneEventMap, ViewerState, NVImage, ImageFromUrlOptions, NVConfigOptions, } from "./types";

package/dist/types/nvcontainer.d.ts

@@ -0,0 +1,10 @@
+import type { CSSProperties } from "react";
+import { NvSceneController } from "./nvscene-controller";
+interface NiivueControllerProps {
+    scene: NvSceneController;
+    className?: string;
+    style?: CSSProperties;
+    initialLayout?: string;
+}
+export declare const NvScene: ({ scene, className, style, initialLayout, }: NiivueControllerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/nvscene-controller.d.ts

@@ -0,0 +1,129 @@
+import { DRAG_MODE, Niivue, SLICE_TYPE, type NVConfigOptions, type NVImage } from "@niivue/niivue";
+import type { LayoutConfig } from "./layouts";
+import type { NvSceneEventMap, ViewerState, ImageFromUrlOptions } from "./types";
+export { SLICE_TYPE };
+export type NiivueCallback = (nv: Niivue, index: number) => void;
+export interface ViewerSlot {
+    id: string;
+    niivue: Niivue;
+    canvasElement: HTMLCanvasElement;
+    containerDiv: HTMLDivElement;
+}
+export interface NvSceneControllerSnapshot {
+    currentLayout: string;
+    viewerCount: number;
+    slots: number;
+    isBroadcasting: boolean;
+    isLoading: boolean;
+    viewerStates: ViewerState[];
+}
+export interface BroadcastOptions {
+    "2d": boolean;
+    "3d": boolean;
+}
+export interface SliceLayoutTile {
+    sliceType: number;
+    position: [number, number, number, number];
+}
+export interface SliceLayoutConfig {
+    label: string;
+    layout: SliceLayoutTile[];
+}
+/**
+ * Default slice layout: Axial as hero (80% height), coronal and sagittal below (20% height each, side by side)
+ */
+export declare const defaultSliceLayout: SliceLayoutTile[];
+/**
+ * Split view: sagittal left, coronal/axial stacked on the right.
+ */
+export declare const splitSliceLayout: SliceLayoutTile[];
+/**
+ * Tri-fan: three equal horizontal panels.
+ */
+export declare const triSliceLayout: SliceLayoutTile[];
+/**
+ * Stacked: three equal vertical stacks.
+ */
+export declare const stackedSliceLayout: SliceLayoutTile[];
+/**
+ * Quad: axial/coronal/sagittal with a render tile.
+ */
+export declare const quadSliceLayout: SliceLayoutTile[];
+/**
+ * Hero render with three small orthogonal slices below.
+ */
+export declare const heroRenderSliceLayout: SliceLayoutTile[];
+export declare const defaultSliceLayouts: Record<string, SliceLayoutConfig>;
+type Listener = () => void;
+export declare const defaultViewerOptions: Partial<NVConfigOptions>;
+export declare const defaultMouseConfig: {
+    leftButton: {
+        primary: DRAG_MODE;
+    };
+    rightButton: DRAG_MODE;
+    centerButton: DRAG_MODE;
+};
+/**
+ * An NvSceneController is a declarative representation of what we want to render with Niivue.
+ *
+ * A scene can contain multiple Niivue instances. Each Niivue instance has its own
+ * canvas element for the WebGL2 context. All canvas elements are wrapped in container
+ * divs that are children of the main scene container element.
+ *
+ * Canvas elements are added/removed on-demand based on the scene definition.
+ *
+ * The scene layout controls the position of each canvas via layout functions that
+ * return absolute positioning styles. The scene container is responsive and maintains
+ * the requested layout proportionally.
+ */
+export declare class NvSceneController {
+    containerElement: HTMLElement | null;
+    viewers: ViewerSlot[];
+    currentLayout: string;
+    slots: number;
+    layouts: Record<string, LayoutConfig>;
+    onViewerCreated?: NiivueCallback;
+    private listeners;
+    private snapshotCache;
+    private nextId;
+    private viewersById;
+    private broadcasting;
+    private broadcastOptions;
+    private viewerSliceLayouts;
+    private viewerDefaults;
+    private eventListeners;
+    private loadingCounts;
+    private viewerErrors;
+    constructor(layouts?: Record<string, LayoutConfig>, viewerDefaults?: Partial<NVConfigOptions>);
+    on<E extends keyof NvSceneEventMap>(event: E, cb: NvSceneEventMap[E]): () => void;
+    off<E extends keyof NvSceneEventMap>(event: E, cb: NvSceneEventMap[E]): void;
+    private emit;
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => NvSceneControllerSnapshot;
+    private notify;
+    setContainerElement(element: HTMLElement | null): void;
+    setLayout(layoutName: string): void;
+    updateLayout(): void;
+    canAddViewer(): boolean;
+    getNiivue(index: number): Niivue | undefined;
+    getAllNiivue(): Niivue[];
+    forEachNiivue(callback: NiivueCallback): void;
+    setBroadcasting(enabled: boolean, options?: Partial<BroadcastOptions>): void;
+    isBroadcasting(): boolean;
+    setViewerSliceLayout(index: number, layout: SliceLayoutTile[] | null): void;
+    getViewerSliceLayout(index: number): SliceLayoutTile[] | null;
+    private applySliceLayout;
+    getNiivueById(id: string): Niivue | undefined;
+    getViewerById(id: string): ViewerSlot | undefined;
+    loadVolume(index: number, opts: ImageFromUrlOptions): Promise<NVImage>;
+    loadVolumes(index: number, opts: ImageFromUrlOptions[]): Promise<NVImage[]>;
+    removeVolume(index: number, url: string): void;
+    private incrementLoading;
+    private decrementLoading;
+    private addError;
+    addViewer(options?: Partial<NVConfigOptions>): ViewerSlot;
+    removeViewer(index: number, shouldNotify?: boolean): void;
+    private disposeViewer;
+    clearViewers(): void;
+    reset(): void;
+}

package/dist/types/nvscene.d.ts

@@ -0,0 +1,10 @@
+import type { CSSProperties } from "react";
+import { NvSceneController } from "./nvscene-controller";
+interface NiivueControllerProps {
+    scene: NvSceneController;
+    className?: string;
+    style?: CSSProperties;
+    initialLayout?: string;
+}
+export declare const NvScene: ({ scene, className, style, initialLayout, }: NiivueControllerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/nvviewer.d.ts

@@ -0,0 +1,14 @@
+import type { CSSProperties } from "react";
+import { type NVConfigOptions, type NVImage } from "@niivue/niivue";
+import type { ImageFromUrlOptions } from "./types";
+export interface NvViewerProps {
+    volumes?: ImageFromUrlOptions[];
+    options?: Partial<NVConfigOptions>;
+    sliceType?: number;
+    className?: string;
+    style?: CSSProperties;
+    onLocationChange?: (data: unknown) => void;
+    onImageLoaded?: (volume: NVImage) => void;
+    onError?: (error: unknown) => void;
+}
+export declare const NvViewer: ({ volumes, options, sliceType, className, style, onLocationChange, onImageLoaded, onError, }: NvViewerProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/types.d.ts

@@ -0,0 +1,18 @@
+import type { Niivue, NVImage, NVConfigOptions } from "@niivue/niivue";
+export type { NVImage, NVConfigOptions };
+/** Extract the ImageFromUrlOptions type from Niivue's addVolumeFromUrl method */
+export type ImageFromUrlOptions = Parameters<Niivue["addVolumeFromUrl"]>[0];
+export interface NvSceneEventMap {
+    viewerCreated: (nv: Niivue, index: number) => void;
+    viewerRemoved: (index: number) => void;
+    locationChange: (viewerIndex: number, data: unknown) => void;
+    imageLoaded: (viewerIndex: number, volume: NVImage) => void;
+    error: (viewerIndex: number, error: unknown) => void;
+    volumeAdded: (viewerIndex: number, imageOptions: ImageFromUrlOptions, image: NVImage) => void;
+    volumeRemoved: (viewerIndex: number, url: string) => void;
+}
+export interface ViewerState {
+    id: string;
+    loading: number;
+    errors: unknown[];
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@niivue/nvreact",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/lib.js",
+  "module": "./dist/lib.js",
+  "types": "./dist/types/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/lib.d.ts",
+      "import": "./dist/lib.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "build": "bun build ./src/index.html --outdir=dist --sourcemap --target=browser --minify --define:process.env.NODE_ENV='\"production\"' --env='BUN_PUBLIC_*'",
+    "start": "NODE_ENV=production bun src/index.ts",
+    "build:lib": "bun build ./src/lib.ts --outdir=dist --target=browser --format=esm --external react --external react-dom --external @niivue/niivue",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:package": "bun run build:lib && bun run build:types",
+    "pack:local": "bun run build:package && bun pm pack",
+    "example:setup": "bun run pack:local && cd example-app && rm -rf node_modules bun.lock && bun install",
+    "example:dev": "bun run example:setup && cd example-app && bun dev"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@niivue/niivue": "0.67.1-dev.2",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "@niivue/niivue": "0.67.1-dev.2",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "^19",
+    "react-dom": "^19",
+    "typescript": "^5.9.3"
+  }
+}