copper3d 3.4.9 → 3.5.0

package/dist/bundle.esm.js

@@ -50086,6 +50086,7 @@ var Stats$1 = Stats;
 class baseRenderer {
     constructor(container, options) {
         var _a, _b, _c, _d, _e;
+        this.running = true;
         this.visualCtrls = [];
         this.container = container;
         this.options = options;
@@ -50186,6 +50187,25 @@ class baseRenderer {
     setClearColor(clearColor = 0x000000, alpha = 0) {
         this.renderer.setClearColor(clearColor, alpha);
     }
+    // Stop the render loop (cancels the requestAnimationFrame chain).
+    stop() {
+        this.running = false;
+    }
+    // Full teardown: stop the loop, free the GPU resources, release the WebGL context
+    // (browsers cap live contexts ~16), and remove the canvas. Call on page unmount.
+    dispose() {
+        var _a, _b;
+        this.running = false;
+        try {
+            (_a = this.pmremGenerator) === null || _a === void 0 ? void 0 : _a.dispose();
+            this.renderer.dispose();
+            this.renderer.forceContextLoss();
+        }
+        catch (e) {
+            /* ignore */
+        }
+        (_b = this.renderer.domElement) === null || _b === void 0 ? void 0 : _b.remove();
+    }
     addGui() {
         var _a, _b, _c;
         const gui = (this.gui = new GUI$1({
@@ -59351,7 +59371,6 @@ class copperRenderer extends baseRenderer {
         this.delta = 0;
         this.interval = 1 / this.fps;
         this.preRenderCallbackFunctions = [];
-        this.running = true;
         this.animate = (time) => {
             var _a, _b, _c;
             if (!this.running)
@@ -59382,10 +59401,6 @@ class copperRenderer extends baseRenderer {
             }
         };
     }
-    // Stop the render loop (call on teardown to release the RAF and let GC reclaim).
-    stop() {
-        this.running = false;
-    }
     getSceneByName(name) {
         return this.sceneMap[name];
     }
@@ -59910,6 +59925,7 @@ class copperMSceneRenderer {
             alpha: true,
             antialias: true,
         });
+        this.running = true;
         this.renderSceneInfo = (sceneInfo) => {
             const elem = sceneInfo.container;
             // get the viewpoint relative position of this element
@@ -59948,6 +59964,8 @@ class copperMSceneRenderer {
             }
         };
         this.animate = () => {
+            if (!this.running)
+                return;
             const clearColor = new Color$1("#000");
             this.renderer.setScissorTest(false);
             this.renderer.setClearColor(clearColor, 0);
@@ -60013,6 +60031,25 @@ class copperMSceneRenderer {
             }, undefined, reject);
         });
     }
+    stop() {
+        this.running = false;
+    }
+    // Full teardown: stop the loop, free GPU resources, release the WebGL context, and
+    // remove the canvas. Call on page unmount to avoid context exhaustion / leaks.
+    dispose() {
+        var _a, _b;
+        this.running = false;
+        try {
+            (_a = this.pmremGenerator) === null || _a === void 0 ? void 0 : _a.dispose();
+            this.renderer.dispose();
+            this.renderer.forceContextLoss();
+        }
+        catch (e) {
+            /* ignore */
+        }
+        (_b = this.canvas) === null || _b === void 0 ? void 0 : _b.remove();
+        this.elems.forEach((el) => el.remove());
+    }
 }
 
 /******************************************************************************
@@ -70432,6 +70469,36 @@ const CHANNEL_HEX_COLORS = {
     7: '#f97316',
     8: '#8b5cf6', // Violet
 };
+/**
+ * AI-Assist channel palette. Identical to the default palette EXCEPT:
+ *  - channel 1 = cyan (the AI-Assist accent #5ec8ff), so the 2D AI overlay aligns
+ *    with the cyan ai_generated GLB in the 3D panel;
+ *  - channel 6 takes the emerald that channel 1 vacated, so cyan isn't duplicated.
+ * Applied ONLY to the AI scratch layer (set per-volume in AiAssistTool.enter) —
+ * the global palette above is untouched, so the clinician mask stays emerald.
+ */
+const AI_MASK_CHANNEL_COLORS = {
+    0: { r: 0, g: 0, b: 0, a: 0 },
+    1: { r: 94, g: 200, b: 255, a: 255 },
+    2: { r: 244, g: 63, b: 94, a: 255 },
+    3: { r: 59, g: 130, b: 246, a: 255 },
+    4: { r: 251, g: 191, b: 36, a: 255 },
+    5: { r: 217, g: 70, b: 239, a: 255 },
+    6: { r: 16, g: 185, b: 129, a: 255 },
+    7: { r: 249, g: 115, b: 22, a: 255 },
+    8: { r: 139, g: 92, b: 246, a: 255 }, // Violet
+};
+const AI_CHANNEL_HEX_COLORS = {
+    0: '#000000',
+    1: '#5ec8ff',
+    2: '#f43f5e',
+    3: '#3b82f6',
+    4: '#fbbf24',
+    5: '#d946ef',
+    6: '#10b981',
+    7: '#f97316',
+    8: '#8b5cf6', // Violet
+};
 // ── Color Conversion Utilities ──────────────────────────────────────────
 /**
  * Convert an RGBAColor to a hex string (no alpha), e.g. '#ff0000'.
@@ -73580,6 +73647,8 @@ class EventRouter {
     constructor(config) {
         // === State ===
         this.mode = 'idle';
+        /** Mode to restore after a right-drag pan ends (so pan doesn't drop aiAssist). */
+        this.modeBeforePan = 'idle';
         this.guiTool = 'pencil';
         this.state = {
             shiftHeld: false,
@@ -73705,7 +73774,20 @@ class EventRouter {
      * Set the GUI tool (from UI buttons).
      */
     setGuiTool(tool) {
+        const prevTool = this.guiTool;
         this.guiTool = tool;
+        // AI-assist owns the canvas: left-click/drag = prompt. Taking the
+        // 'aiAssist' mode (not 'idle') is what auto-disables left-drag slice
+        // scrubbing — `isDragSliceActive()` requires mode === 'idle'.
+        if (tool === 'aiAssist') {
+            this.state.crosshairEnabled = false;
+            this.setMode('aiAssist');
+            return;
+        }
+        // Leaving aiAssist → restore idle so slice-drag / wheel resume.
+        if (prevTool === 'aiAssist' && this.mode === 'aiAssist') {
+            this.setMode('idle');
+        }
         // When entering any sphere-family tool, keep crosshair if active, otherwise idle
         if (SPHERE_TOOLS.has(tool)) {
             if (!this.state.crosshairEnabled) {
@@ -73719,8 +73801,9 @@ class EventRouter {
      * Blocked when draw or contrast mode is active, or left button is held (mutual exclusion).
      */
     toggleCrosshair() {
-        // Allow crosshair in drawing tools and all sphere-family tools (sphere / sphereBrush / sphereEraser)
-        if (!DRAWING_TOOLS.has(this.guiTool) && !SPHERE_TOOLS.has(this.guiTool))
+        // Allow crosshair in drawing tools, all sphere-family tools, AND aiAssist
+        // (so the crosshair can be used to debug while AI-assist is active).
+        if (!DRAWING_TOOLS.has(this.guiTool) && !SPHERE_TOOLS.has(this.guiTool) && this.guiTool !== 'aiAssist')
             return;
         // Block crosshair activation during draw, contrast, or while left button held.
         // The leftButtonDown guard also enforces "once a sphere preview is on screen,
@@ -73728,7 +73811,15 @@ class EventRouter {
         if (this.state.shiftHeld || this.state.leftButtonDown || this.mode === 'draw' || this.mode === 'contrast')
             return;
         this.state.crosshairEnabled = !this.state.crosshairEnabled;
-        this.setMode(this.state.crosshairEnabled ? 'crosshair' : 'idle');
+        // Crosshair has PRIORITY over aiAssist: turning it on takes the mode (so
+        // AI point/box/scribble are suspended); turning it off restores aiAssist
+        // (not idle) when the AI tool is the active tool, otherwise idle.
+        if (this.state.crosshairEnabled) {
+            this.setMode('crosshair');
+        }
+        else {
+            this.setMode(this.guiTool === 'aiAssist' ? 'aiAssist' : 'idle');
+        }
     }
     /**
      * Check if crosshair mode is enabled.
@@ -73864,8 +73955,8 @@ class EventRouter {
             }
         }
         if (this.contrastEnabled && this.keyboardSettings.contrast.includes(ev.key)) {
-            // Block contrast state when crosshair, draw, or any sphere-family tool is active (mutual exclusion)
-            if (!this.state.crosshairEnabled && this.mode !== 'draw'
+            // Block contrast state when crosshair, draw, aiAssist, or any sphere-family tool is active (mutual exclusion)
+            if (!this.state.crosshairEnabled && this.mode !== 'draw' && this.mode !== 'aiAssist'
                 && !SPHERE_TOOLS.has(this.guiTool)) {
                 this.state.ctrlHeld = true;
             }
@@ -73902,6 +73993,10 @@ class EventRouter {
         }
         else if (ev.button === 2) {
             this.state.rightButtonDown = true;
+            // Remember the mode we're panning out of so we can restore it on
+            // release — otherwise aiAssist (and any non-idle mode) is lost.
+            if (this.mode !== 'pan')
+                this.modeBeforePan = this.mode;
             this.setMode('pan');
         }
         // Route to external handler
@@ -73922,7 +74017,10 @@ class EventRouter {
         else if (ev.button === 2) {
             this.state.rightButtonDown = false;
             if (this.mode === 'pan') {
-                this.setMode('idle');
+                // Restore aiAssist if we panned out of it; otherwise idle (unchanged
+                // behaviour for normal drawing modes).
+                this.setMode(this.modeBeforePan === 'aiAssist' ? 'aiAssist' : 'idle');
+                this.modeBeforePan = 'idle';
             }
         }
         // Route to external handler
@@ -75845,6 +75943,474 @@ class SphereBrushTool extends BaseTool {
     }
 }
 
+/**
+ * AiAssistTool — interactive prompt-based segmentation (experimental).
+ *
+ * The clinician left-clicks foreground / background points (or drags a box /
+ * scribbles) on the current slice; a backend model returns a region mask that
+ * is written into an INDEPENDENT scratch MaskVolume (`aiAssistMaskVolume`,
+ * registered as `maskData.volumes['aiScratch']`) — never the validated layers.
+ *
+ * Network lives in the app layer: this tool only (a) maps screen → voxel-slice
+ * coordinates, (b) accumulates the prompt for the current slice, (c) fires
+ * `onPrompt` so the app can call the backend, and (d) applies the returned mask
+ * via `applyMask`. The app's `useAiAssist` composable wires (c)→(d).
+ *
+ * Sandbox: snapshot on enter (`snapshot`), then on exit either `discard`
+ * (restore snapshot) or merge is handled by NrrdTools (clone + pushGroup).
+ *
+ * Coordinate mapping supports all three views (axial/sagittal/coronal); it
+ * inverts the per-axis display transform of RenderingUtils.renderSliceToCanvas
+ * (only coronal 'y' is vertically flipped). Merge captures painted voxels from
+ * any view (the scratch is a full 3D volume).
+ */
+/** Scratch volume key in maskData.volumes — kept OUT of image.layers so
+ *  compositeAllLayers ignores it (we render it ourselves in start()). */
+const AI_SCRATCH_LAYER = "aiScratch";
+class AiAssistTool extends BaseTool {
+    constructor(ctx, host) {
+        super(ctx);
+        /** Independent scratch volume (also registered at maskData.volumes['aiScratch']). */
+        this.scratchVol = null;
+        /** Snapshot of the scratch buffer taken on enter (for discard). */
+        this.snapshotData = null;
+        /** Frozen regions ("New region" commits here). Pixels recorded here survive a
+         *  later re-prediction — even on the SAME channel — so multiple separate regions
+         *  can be drawn without the newest prediction wiping the previous ones. Null =
+         *  nothing frozen yet (applySliceRle then behaves as a single live region). */
+        this.committedVol = null;
+        this.promptTool = "point";
+        this.polarity = 1; // 1 = foreground (positive), 0 = background
+        /** Target channel/label (1-8) the AI paints into — the "AI layer" channel. */
+        this.channel = 1;
+        /** Scribble brush radius (px), user-adjustable via slider. */
+        this.scribbleSize = 5;
+        /** Accumulated prompts for the CURRENT slice; reset on slice/axis change. */
+        this.points = [];
+        this.scribble = [];
+        this.activeSlice = -1;
+        // Drag state (box / scribble) — voxel coords for the prompt
+        this.dragging = false;
+        this.dragStart = null;
+        // Screen-space (display px) copies for the LIVE preview drawn each frame.
+        this.dragScreenStart = null;
+        this.dragScreen = null;
+        this.screenScribble = [];
+        // Live cursor position (screen px) for the scribble brush-size preview ring —
+        // updated on every hover move so the ring follows the mouse like the paint brush.
+        this.hoverScreen = null;
+        /** Fired when a prompt gesture completes — app calls backend, then applyMask(). */
+        this.onPrompt = null;
+        this.host = host;
+    }
+    // ── Configuration (driven from the panel via NrrdTools) ────────────────────
+    setPromptTool(tool) {
+        // Switching tool starts a clean gesture — drop any stale points/box/scribble
+        // and drag state so the next click behaves predictably.
+        if (tool !== this.promptTool) {
+            this.resetPrompts();
+            this.dragging = false;
+            this.dragStart = null;
+        }
+        this.promptTool = tool;
+    }
+    setPolarity(label) { this.polarity = label === 0 ? 0 : 1; }
+    setScribbleSize(size) {
+        this.scribbleSize = Math.max(1, Math.min(40, Math.round(size)));
+    }
+    setChannel(channel) {
+        const c = Math.max(1, Math.min(8, Math.round(channel)));
+        // Changing channel starts a NEW region in the new colour — otherwise the
+        // accumulated points would be re-predicted and repainted in the new label,
+        // recolouring the previous channel's region.
+        if (c !== this.channel)
+            this.resetPrompts();
+        this.channel = c;
+    }
+    getChannel() { return this.channel; }
+    getScratchVolume() { return this.scratchVol; }
+    /** Serialize the scratch volume as per-z-slice RLE (only NON-empty slices),
+     *  for persisting to ai_generated_nii_LPS on the backend. Binary (any channel →
+     *  1); RLE is alternating run lengths starting with a 0-run — the exact format
+     *  the backend's rle_decode expects. Uses getSliceUint8 (the same path the
+     *  clinician layer's /api/mask/replace uses) so orientation matches. */
+    getScratchSlices() {
+        if (!this.scratchVol)
+            return null;
+        const { depth } = this.scratchVol.getDimensions();
+        const out = [];
+        let width = 0;
+        let height = 0;
+        for (let z = 0; z < depth; z++) {
+            const { data, width: w, height: h } = this.scratchVol.getSliceUint8(z, "z");
+            width = w;
+            height = h;
+            // RLE-encode (binarized) in one pass; skip fully-empty slices.
+            const runs = [];
+            let value = 0; // always begin with a 0-run (matches backend rle_encode)
+            let count = 0;
+            let any = false;
+            for (let i = 0; i < data.length; i++) {
+                const v = data[i] !== 0 ? 1 : 0;
+                if (v)
+                    any = true;
+                if (v === value) {
+                    count++;
+                }
+                else {
+                    runs.push(count);
+                    value = v;
+                    count = 1;
+                }
+            }
+            runs.push(count);
+            if (any)
+                out.push({ sliceIndex: z, rle: runs });
+        }
+        return { axis: "z", width, height, slices: out };
+    }
+    // ── Sandbox lifecycle ──────────────────────────────────────────────────────
+    /** Create (or reuse) the scratch volume sized to the layer grid and register
+     *  it under maskData.volumes['aiScratch']. Snapshots the empty buffer. */
+    enter() {
+        const volumes = this.ctx.protectedData.maskData.volumes;
+        const baseId = this.ctx.nrrd_states.image.layers[0];
+        const base = volumes[baseId];
+        if (!base)
+            return;
+        const d = base.getDimensions();
+        if (!this.scratchVol ||
+            this.scratchVol.getDimensions().width !== d.width ||
+            this.scratchVol.getDimensions().height !== d.height ||
+            this.scratchVol.getDimensions().depth !== d.depth) {
+            this.scratchVol = new MaskVolume(d.width, d.height, d.depth, 1);
+        }
+        else {
+            this.scratchVol.clear();
+        }
+        volumes[AI_SCRATCH_LAYER] = this.scratchVol;
+        // Paint the AI scratch with the AI-Assist palette (channel 1 = cyan) so the 2D
+        // overlay matches the cyan ai_generated GLB. Scoped to THIS volume only — the
+        // global palette / clinician mask colours are untouched.
+        for (let ch = 1; ch <= 8; ch++) {
+            const c = AI_MASK_CHANNEL_COLORS[ch];
+            if (c)
+                this.scratchVol.setChannelColor(ch, { r: c.r, g: c.g, b: c.b, a: c.a });
+        }
+        this.snapshotData = this.scratchVol.getRawData().slice();
+        this.committedVol = null; // nothing frozen at session start
+        this.resetPrompts();
+    }
+    /** Remove the scratch volume from the registry and drop references. */
+    exit() {
+        const volumes = this.ctx.protectedData.maskData.volumes;
+        delete volumes[AI_SCRATCH_LAYER];
+        this.scratchVol = null;
+        this.snapshotData = null;
+        this.committedVol = null;
+        this.resetPrompts();
+        this.dragging = false;
+        this.dragStart = null;
+    }
+    /** Discard everything painted since enter() — restore the snapshot. */
+    discard() {
+        if (this.scratchVol && this.snapshotData) {
+            this.scratchVol.setRawData(this.snapshotData.slice());
+        }
+        this.committedVol = null; // discard wipes frozen regions too
+        this.resetPrompts();
+    }
+    /** "New region": freeze every voxel painted so far so it survives later
+     *  re-predictions (even on the same channel), then start a fresh prompt set.
+     *  This is what makes drawing multiple separate regions actually work — without
+     *  it the next prediction's same-channel cleanup erases the previous region. */
+    commitRegion() {
+        if (this.scratchVol) {
+            const d = this.scratchVol.getDimensions();
+            if (!this.committedVol ||
+                this.committedVol.getDimensions().width !== d.width ||
+                this.committedVol.getDimensions().height !== d.height ||
+                this.committedVol.getDimensions().depth !== d.depth) {
+                this.committedVol = new MaskVolume(d.width, d.height, d.depth, 1);
+            }
+            this.committedVol.setRawData(this.scratchVol.getRawData().slice());
+        }
+        this.resetPrompts();
+    }
+    /** Clear the in-progress prompt set (e.g. slice/axis change). Does NOT freeze —
+     *  use commitRegion() for the "New region" action. */
+    resetPrompts() {
+        this.points = [];
+        this.scribble = [];
+        this.box = undefined;
+        this.dragScreenStart = null;
+        this.dragScreen = null;
+        this.screenScribble = [];
+    }
+    // ── Coordinate mapping (all three views) ───────────────────────────────────
+    //
+    // Mapping must INVERT exactly what RenderingUtils.renderSliceToCanvas does to
+    // display the overlay (it is the renderer used by renderOverlay):
+    //   - axial (z) / sagittal (x): no flip
+    //   - coronal (y): vertical flip (scale(1,-1))
+    // Slice voxel dims & canvas mm extents per axis (matches MaskVolume
+    // getSliceDimensions + SphereTool.setSphereCanvasSize):
+    //   z → (W=width,  H=height) over (x_mm, y_mm)
+    //   y → (W=width,  H=depth ) over (x_mm, z_mm)   [vertical flip]
+    //   x → (W=depth,  H=height) over (z_mm, y_mm)
+    /** Voxel-slice (width,height) for the current axis. */
+    sliceDims() {
+        if (!this.scratchVol)
+            return null;
+        const d = this.scratchVol.getDimensions();
+        switch (this.ctx.protectedData.axis) {
+            case "z": return { w: d.width, h: d.height };
+            case "y": return { w: d.width, h: d.depth };
+            case "x": return { w: d.depth, h: d.height };
+            default: return null;
+        }
+    }
+    /** Screen offset → voxel-slice (vx,vy) for the current axis. */
+    toVoxel(e) {
+        const sd = this.sliceDims();
+        if (!sd || !this.scratchVol)
+            return null;
+        const nrrd = this.ctx.nrrd_states;
+        const img = nrrd.image;
+        const mx = e.offsetX / nrrd.view.sizeFactor;
+        const my = e.offsetY / nrrd.view.sizeFactor;
+        let hMM, vMM, flipV;
+        switch (this.ctx.protectedData.axis) {
+            case "z":
+                hMM = img.nrrd_x_mm;
+                vMM = img.nrrd_y_mm;
+                flipV = false;
+                break;
+            case "y":
+                hMM = img.nrrd_x_mm;
+                vMM = img.nrrd_z_mm;
+                flipV = true;
+                break;
+            case "x":
+                hMM = img.nrrd_z_mm;
+                vMM = img.nrrd_y_mm;
+                flipV = false;
+                break;
+            default: return null;
+        }
+        const vx = Math.round(mx * sd.w / hMM);
+        let vy = Math.round(my * sd.h / vMM);
+        if (flipV)
+            vy = sd.h - 1 - vy;
+        if (vx < 0 || vx >= sd.w || vy < 0 || vy >= sd.h)
+            return null;
+        return { vx, vy, w: sd.w, h: sd.h };
+    }
+    // ── Pointer handlers (left button; right stays pan in EventRouter) ──────────
+    onPointerDown(e) {
+        const hit = this.toVoxel(e);
+        if (!hit)
+            return;
+        this.syncSlice();
+        if (this.promptTool === "point") {
+            this.points.push({ x: hit.vx, y: hit.vy, label: this.polarity });
+            this.emit();
+        }
+        else {
+            // box / scribble: begin a drag
+            this.dragging = true;
+            this.dragStart = { x: hit.vx, y: hit.vy };
+            this.dragScreenStart = { x: e.offsetX, y: e.offsetY };
+            this.dragScreen = { x: e.offsetX, y: e.offsetY };
+            this.screenScribble = [];
+            if (this.promptTool === "scribble") {
+                this.scribble.push({ x: hit.vx, y: hit.vy, label: this.polarity });
+                this.screenScribble.push({ x: e.offsetX, y: e.offsetY });
+            }
+        }
+    }
+    onPointerMove(e) {
+        // Track hover for the scribble preview ring even when not drawing.
+        this.hoverScreen = { x: e.offsetX, y: e.offsetY };
+        if (!this.dragging)
+            return;
+        // Track screen pos first so the live preview follows even slightly out of bounds.
+        this.dragScreen = { x: e.offsetX, y: e.offsetY };
+        const hit = this.toVoxel(e);
+        if (!hit)
+            return;
+        if (this.promptTool === "scribble") {
+            this.scribble.push({ x: hit.vx, y: hit.vy, label: this.polarity });
+            this.screenScribble.push({ x: e.offsetX, y: e.offsetY });
+        }
+        else if (this.promptTool === "box" && this.dragStart) {
+            this.box = {
+                x0: this.dragStart.x, y0: this.dragStart.y,
+                x1: hit.vx, y1: hit.vy,
+                label: this.polarity, // foreground box grows within; background box excludes
+            };
+        }
+    }
+    onPointerUp(_e) {
+        if (!this.dragging)
+            return;
+        this.dragging = false;
+        this.emit();
+        this.dragStart = null;
+        this.dragScreenStart = null;
+        this.dragScreen = null;
+        this.screenScribble = [];
+    }
+    /** Reset the accumulated prompt set when the user scrubs to a new slice. */
+    syncSlice() {
+        const slice = this.ctx.nrrd_states.view.currentSliceIndex;
+        if (slice !== this.activeSlice) {
+            this.activeSlice = slice;
+            this.resetPrompts();
+        }
+    }
+    emit() {
+        if (!this.onPrompt)
+            return;
+        const sd = this.sliceDims();
+        if (!sd)
+            return;
+        this.onPrompt({
+            axis: this.ctx.protectedData.axis,
+            sliceIndex: this.ctx.nrrd_states.view.currentSliceIndex,
+            width: sd.w,
+            height: sd.h,
+            points: [...this.points],
+            box: this.box,
+            scribble: this.scribble.length ? [...this.scribble] : undefined,
+            scribbleRadius: this.scribbleSize,
+        });
+    }
+    // ── Apply backend result → scratch volume ──────────────────────────────────
+    applyMask(result) {
+        if (!this.scratchVol)
+            return;
+        // 3D result (engine B): write each slice across the covered span.
+        if (result.slices && result.sliceRange) {
+            const [lo] = result.sliceRange;
+            for (let k = 0; k < result.slices.length; k++) {
+                this.applySliceRle(result.slices[k], result.axis, lo + k, result.width, result.height);
+            }
+            return;
+        }
+        // 2D result (engines mock / regiongrow / medsam2d): single slice.
+        this.applySliceRle(result.rle, result.axis, result.sliceIndex, result.width, result.height);
+    }
+    /** Merge one RLE-encoded predicted slice into the scratch volume at sliceIndex.
+     *  Predicted pixels → current channel; stale current-channel pixels cleared
+     *  UNLESS they belong to a frozen (committed) region; OTHER channels preserved. */
+    applySliceRle(rle, axis, sliceIndex, width, height) {
+        if (!this.scratchVol)
+            return;
+        const predicted = new Uint8Array(width * height);
+        let pos = 0;
+        let value = 0;
+        for (const run of rle) {
+            if (value === 1 && run > 0) {
+                const end = Math.min(pos + run, predicted.length);
+                for (let i = pos; i < end; i++)
+                    predicted[i] = 1;
+            }
+            pos += run;
+            value ^= 1;
+        }
+        const ch = this.channel;
+        try {
+            const out = this.scratchVol.getSliceUint8(sliceIndex, axis).data; // copy
+            // Frozen same-channel pixels for this slice (if any region was committed).
+            let frozen = null;
+            if (this.committedVol) {
+                try {
+                    frozen = this.committedVol.getSliceUint8(sliceIndex, axis).data;
+                }
+                catch (_a) {
+                    frozen = null;
+                }
+            }
+            const n = Math.min(out.length, predicted.length);
+            for (let i = 0; i < n; i++) {
+                if (predicted[i])
+                    out[i] = ch;
+                // Clear stale LIVE same-channel pixels (refinement), but never erase a
+                // frozen region committed via "New region".
+                else if (out[i] === ch && !(frozen && frozen[i] === ch))
+                    out[i] = 0;
+            }
+            this.scratchVol.setSliceUint8(sliceIndex, out, axis);
+        }
+        catch (_b) {
+            // slice out of bounds / dims changed — ignore
+        }
+    }
+    // ── Overlay render (called from DrawToolCore.start() while in aiAssist) ──────
+    renderOverlay(targetCtx) {
+        if (!this.scratchVol)
+            return;
+        const axis = this.ctx.protectedData.axis;
+        const slice = this.ctx.nrrd_states.view.currentSliceIndex;
+        const buffer = this.host.getOrCreateSliceBuffer(axis);
+        if (!buffer)
+            return;
+        try {
+            this.host.renderSliceToCanvas(AI_SCRATCH_LAYER, axis, slice, buffer, targetCtx, this.ctx.nrrd_states.view.changedWidth, this.ctx.nrrd_states.view.changedHeight);
+        }
+        catch (_a) {
+            // volume not ready / slice out of bounds
+        }
+        // Live drag preview (screen space) — rubber-band box / scribble stroke so the
+        // user sees the gesture before the prediction lands on pointer-up.
+        if (this.dragging && this.dragScreenStart && this.dragScreen) {
+            targetCtx.save();
+            // Green-ish for foreground (include), red-ish for background (exclude).
+            const color = this.polarity === 1 ? "rgba(120,255,180,0.95)" : "rgba(255,120,120,0.95)";
+            targetCtx.strokeStyle = color;
+            if (this.promptTool === "box") {
+                targetCtx.setLineDash([5, 4]);
+                targetCtx.lineWidth = 1.5;
+                const x = Math.min(this.dragScreenStart.x, this.dragScreen.x);
+                const y = Math.min(this.dragScreenStart.y, this.dragScreen.y);
+                const w = Math.abs(this.dragScreen.x - this.dragScreenStart.x);
+                const h = Math.abs(this.dragScreen.y - this.dragScreenStart.y);
+                targetCtx.strokeRect(x, y, w, h);
+            }
+            else if (this.promptTool === "scribble" && this.screenScribble.length > 1) {
+                targetCtx.lineCap = "round";
+                targetCtx.lineJoin = "round";
+                // Stroke thickness reflects the scribble brush size (diameter ≈ 2·radius).
+                targetCtx.lineWidth = Math.max(2, this.scribbleSize * 2);
+                targetCtx.beginPath();
+                targetCtx.moveTo(this.screenScribble[0].x, this.screenScribble[0].y);
+                for (let i = 1; i < this.screenScribble.length; i++) {
+                    targetCtx.lineTo(this.screenScribble[i].x, this.screenScribble[i].y);
+                }
+                targetCtx.stroke();
+            }
+            targetCtx.restore();
+        }
+        // Scribble brush-size preview ring (when NOT dragging) — a circle centred on
+        // the cursor whose radius = scribbleSize, so the user sees the brush size and
+        // how the slider changes it (mirrors the paint brush's preview ring). Drawn
+        // every frame from the live hover position by copper3d's render loop.
+        if (this.promptTool === "scribble" && !this.dragging && this.hoverScreen) {
+            targetCtx.save();
+            const fg = this.polarity === 1;
+            targetCtx.strokeStyle = fg ? "rgba(120,255,180,0.9)" : "rgba(255,120,120,0.9)";
+            targetCtx.lineWidth = 1.5;
+            if (!fg)
+                targetCtx.setLineDash([4, 4]); // dashed for background (exclude), like the eraser
+            targetCtx.beginPath();
+            targetCtx.arc(this.hoverScreen.x, this.hoverScreen.y, Math.max(2, this.scribbleSize), 0, Math.PI * 2);
+            targetCtx.stroke();
+            targetCtx.restore();
+        }
+    }
+}
+
 /**
  * DrawToolCore — Tool orchestration and event routing.
  *
@@ -75965,6 +76531,10 @@ class DrawToolCore {
             setEmptyCanvasSize: (axis) => this.setEmptyCanvasSize(axis),
             reloadMasksFromVolume: () => this.reloadMasksFromVolume(),
         });
+        this.aiAssistTool = new AiAssistTool(toolCtx, {
+            renderSliceToCanvas: (layer, axis, sliceIndex, buffer, ctx, w, h) => this.renderer.renderSliceToCanvas(layer, axis, sliceIndex, buffer, ctx, w, h),
+            getOrCreateSliceBuffer: (axis) => this.renderer.getOrCreateSliceBuffer(axis),
+        });
     }
     initDrawToolCore() {
         // Initialize EventRouter for centralized event handling
@@ -76071,6 +76641,8 @@ class DrawToolCore {
                 // Block contrast toggle during crosshair, draw, or sphere (mutual exclusion)
                 if (this.eventRouter.isCrosshairEnabled() || this.eventRouter.getMode() === 'draw')
                     return;
+                if (this.eventRouter.getMode() === 'aiAssist')
+                    return;
                 if (this.state.gui_states.mode.sphere)
                     return;
                 // Toggle contrast mode manually since it's on keyup
@@ -76084,6 +76656,10 @@ class DrawToolCore {
         });
         // Register pointer handlers with EventRouter
         this.eventRouter.setPointerMoveHandler((e) => {
+            if (this.eventRouter.getMode() === 'aiAssist') {
+                this.aiAssistTool.onPointerMove(e);
+                return;
+            }
             if (this.drawingTool.isActive || this.panTool.isActive) {
                 this.drawingPrameters.handleOnDrawingMouseMove(e);
             }
@@ -76098,6 +76674,14 @@ class DrawToolCore {
             }
         });
         this.eventRouter.setPointerUpHandler((e) => {
+            if (this.eventRouter.getMode() === 'aiAssist') {
+                if (e.button === 0)
+                    this.aiAssistTool.onPointerUp(e);
+                // Right-button pan must still clean up (cursor/state) even in AI mode.
+                else if (e.button === 2)
+                    this.panTool.onPointerUp(e, this.state.gui_states.viewConfig.defaultPaintCursor);
+                return;
+            }
             // Restore Scroll:Zoom if we swapped to Scroll:Slice on drag-start.
             // Must run outside the drawing-tool gate below: slice-drag doesn't
             // flip any of those flags, so the gate would skip restoration.
@@ -76257,7 +76841,10 @@ class DrawToolCore {
                 this.activeWheelMode = 'none';
             }
             if (e.button === 0) {
-                if (this.eventRouter.getMode() === 'draw') {
+                if (this.eventRouter.getMode() === 'aiAssist') {
+                    this.aiAssistTool.onPointerDown(e);
+                }
+                else if (this.eventRouter.getMode() === 'draw') {
                     this.drawingTool.onPointerDown(e);
                 }
                 else if (this.eventRouter.isCrosshairEnabled()) {
@@ -76372,6 +76959,12 @@ class DrawToolCore {
                     || this.state.gui_states.mode.sphereEraser) {
                     this.state.protectedData.ctxes.drawingCtx.drawImage(this.state.protectedData.canvases.drawingSphereCanvas, 0, 0, this.state.nrrd_states.view.changedWidth, this.state.nrrd_states.view.changedHeight);
                 }
+                // AI-assist scratch overlay — drawn each frame whenever an AI session is
+                // active (scratch volume exists), so it stays visible even when crosshair
+                // temporarily takes over the interaction mode for debugging.
+                if (this.aiAssistTool.getScratchVolume()) {
+                    this.aiAssistTool.renderOverlay(this.state.protectedData.ctxes.drawingCtx);
+                }
             }
             else {
                 this.redrawDisplayCanvas();
@@ -77976,6 +78569,13 @@ class NrrdTools {
         this._calculatorActive = false;
         /** Stored closure callbacks from gui.ts setupGui() */
         this.guiCallbacks = null;
+        // ═══════════════════════════════════════════════════════════════════════════
+        // 10b. AI Assist (experimental) — interactive prompt segmentation
+        // ═══════════════════════════════════════════════════════════════════════════
+        /** Whether AI-assist mode is currently active. */
+        this._aiAssistActive = false;
+        /** Layer visibility snapshot taken on enter, restored on exit. */
+        this._aiPrevVisibility = null;
         this.container = container;
         // Create shared state
         const mainAreaContainer = document.createElement("div");
@@ -78143,6 +78743,13 @@ class NrrdTools {
         var _a, _b, _c;
         if (!this.guiCallbacks)
             return;
+        // While AI-assist owns the canvas, BLOCK switching to other tools — the user
+        // must explicitly Exit AI Assist from its panel first. (The Operation panel
+        // also disables its tool buttons via the AiAssist:ActiveChanged event, so this
+        // is just a defensive guard.)
+        if (this._aiAssistActive && mode !== "aiAssist") {
+            return;
+        }
         const prevSphere = this.state.gui_states.mode.sphere;
         const prevSphereBrush = this.state.gui_states.mode.sphereBrush;
         const prevSphereEraser = this.state.gui_states.mode.sphereEraser;
@@ -78791,6 +79398,111 @@ class NrrdTools {
         this.resetLayerCanvas();
         this.reloadMasksFromVolume();
     }
+    isAiAssistActive() { return this._aiAssistActive; }
+    /**
+     * Enter AI-assist mode (sandbox): hides the existing layer masks so ONLY the
+     * AI overlay is shown, takes canvas ownership (left-click = prompt), and creates
+     * the scratch volume. Right-drag still pans; wheel/slider still scrub slices.
+     * The hidden masks are restored on exit (merge writes into them first if asked).
+     */
+    enterAiAssistMode() {
+        var _a;
+        if (this._aiAssistActive)
+            return;
+        this._aiAssistActive = true;
+        this.dragOperator.removeDragMode();
+        // Hide all layer masks (visibility=false survives recomposite on slice change).
+        const vis = this.state.gui_states.layerChannel.layerVisibility;
+        this._aiPrevVisibility = Object.assign({}, vis);
+        for (const layerId of this.state.nrrd_states.image.layers)
+            vis[layerId] = false;
+        this.drawCore.renderer.compositeAllLayers();
+        this.drawCore.aiAssistTool.enter();
+        (_a = this.drawCore.eventRouter) === null || _a === void 0 ? void 0 : _a.setGuiTool("aiAssist");
+    }
+    /**
+     * Exit AI-assist mode: drop the scratch volume, restore normal tooling AND the
+     * layer-mask visibility hidden on enter. If the caller merged first, the merged
+     * result is now part of the layer volume and reappears with the restored masks.
+     */
+    exitAiAssistMode() {
+        var _a;
+        if (!this._aiAssistActive)
+            return;
+        this._aiAssistActive = false;
+        this.drawCore.aiAssistTool.exit();
+        this.dragOperator.configDragMode();
+        (_a = this.drawCore.eventRouter) === null || _a === void 0 ? void 0 : _a.setGuiTool("pencil");
+        if (this._aiPrevVisibility) {
+            const vis = this.state.gui_states.layerChannel.layerVisibility;
+            for (const k of Object.keys(this._aiPrevVisibility))
+                vis[k] = this._aiPrevVisibility[k];
+            this._aiPrevVisibility = null;
+        }
+        this.reloadMasksFromVolume();
+    }
+    // — Driver methods called by the app-layer composable —
+    aiSetPromptTool(tool) { this.drawCore.aiAssistTool.setPromptTool(tool); }
+    aiSetPolarity(label) { this.drawCore.aiAssistTool.setPolarity(label); }
+    /** Set the AI-layer channel (1-8) the predictions paint into. */
+    aiSetChannel(channel) { this.drawCore.aiAssistTool.setChannel(channel); }
+    /** Set the scribble brush radius (px). */
+    aiSetScribbleSize(size) { this.drawCore.aiAssistTool.setScribbleSize(size); }
+    /** Register the callback invoked when a prompt gesture completes (app → backend). */
+    aiOnPrompt(cb) { this.drawCore.aiAssistTool.onPrompt = cb; }
+    /** Apply a backend mask result into the scratch volume (overlay repaints next frame). */
+    aiApplyMask(result) { this.drawCore.aiAssistTool.applyMask(result); }
+    /** Clear the in-progress prompt set (e.g. slice change). */
+    aiClearPrompts() { this.drawCore.aiAssistTool.resetPrompts(); }
+    /** "New region": freeze current regions (they persist) + start a fresh prompt set. */
+    aiCommitRegion() { this.drawCore.aiAssistTool.commitRegion(); }
+    /** Discard all AI scratch painting since enter (sandbox discard). */
+    aiDiscard() { this.drawCore.aiAssistTool.discard(); }
+    /** True if the scratch volume holds any predicted voxels. */
+    aiHasData() { var _a, _b; return (_b = (_a = this.drawCore.aiAssistTool.getScratchVolume()) === null || _a === void 0 ? void 0 : _a.hasData()) !== null && _b !== void 0 ? _b : false; }
+    /** Serialize the AI scratch as per-slice RLE for persisting to ai_generated_nii_LPS. */
+    aiGetScratchSlices() {
+        return this.drawCore.aiAssistTool.getScratchSlices();
+    }
+    /**
+     * Merge the AI scratch into a target layer as a single undoable group (sandbox
+     * merge — best-practice: non-destructive + one Ctrl+Z). The scratch's channel
+     * labels are PRESERVED (each AI channel maps onto the same channel of the
+     * target layer). Scans all z-slices, so voxels painted from any view are caught.
+     */
+    aiCommitToLayer(targetLayer = "layer1") {
+        const scratch = this.drawCore.aiAssistTool.getScratchVolume();
+        if (!scratch)
+            return;
+        const target = this.state.protectedData.maskData.volumes[targetLayer];
+        if (!target)
+            return;
+        const dims = scratch.getDimensions();
+        const deltas = [];
+        for (let z = 0; z < dims.depth; z++) {
+            const sc = scratch.getSliceUint8(z, "z").data;
+            let any = false;
+            for (let i = 0; i < sc.length; i++) {
+                if (sc[i] !== 0) {
+                    any = true;
+                    break;
+                }
+            }
+            if (!any)
+                continue;
+            const oldSlice = target.getSliceUint8(z, "z").data; // copy
+            const newSlice = oldSlice.slice();
+            for (let i = 0; i < newSlice.length; i++) {
+                if (sc[i] !== 0)
+                    newSlice[i] = sc[i]; // preserve the AI channel label
+            }
+            target.setSliceUint8(z, newSlice, "z");
+            deltas.push({ layerId: targetLayer, axis: "z", sliceIndex: z, oldSlice, newSlice: newSlice.slice() });
+        }
+        if (deltas.length)
+            this.drawCore.undoManager.pushGroup(deltas);
+        this.reloadMasksFromVolume();
+    }
     // ═══════════════════════════════════════════════════════════════════════════
     // 11. Clear / Reset
     // ═══════════════════════════════════════════════════════════════════════════
@@ -79154,7 +79866,7 @@ function evaluateElement(element, weights) {
 }
 
 // import * as kiwrious from "copper3d_plugin_heart_k";
-const REVISION = "v3.4.9-beta";
+const REVISION = "v3.5.0-beta";
 console.log(`%cCopper3D Visualisation %cBeta:${REVISION}`, "padding: 3px;color:white; background:#023047", "padding: 3px;color:white; background:#f50a25");
 
-export { CHANNEL_COLORS, CHANNEL_HEX_COLORS, CameraViewPoint, Copper3dTrackballControls, GaussianSmoother, MeshNodeTool, NrrdTools, REVISION, addBoxHelper, addLabelToScene, configKiwriousHeart, convert3DPostoScreenPos, convertScreenPosto3DPos, copperMScene, copperMSceneRenderer, copperRenderer, copperRendererOnDemond, copperScene, copperSceneOnDemond, createTexture2D_NRRD, fullScreenListenner, kiwrious, loading, removeGuiFolderChilden, rgbaToCss, rgbaToHex, setHDRFilePath, throttle };
+export { AI_CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, CHANNEL_COLORS, CHANNEL_HEX_COLORS, CameraViewPoint, Copper3dTrackballControls, GaussianSmoother, MeshNodeTool, NrrdTools, REVISION, addBoxHelper, addLabelToScene, configKiwriousHeart, convert3DPostoScreenPos, convertScreenPosto3DPos, copperMScene, copperMSceneRenderer, copperRenderer, copperRendererOnDemond, copperScene, copperSceneOnDemond, createTexture2D_NRRD, fullScreenListenner, kiwrious, loading, removeGuiFolderChilden, rgbaToCss, rgbaToHex, setHDRFilePath, throttle };