copper3d 3.4.8 → 3.5.0

package/dist/bundle.umd.js

@@ -40834,6 +40834,17 @@ void main() {
 	            windowCenter = 226;
 	            windowWidth = 537;
 	        }
+	        // Spatial geometry tags (DS VR, backslash-delimited) used to place the image plane
+	        // at its true world pose, plus InstanceNumber as an ordering fallback.
+	        const ipp = parseDS(dataSet.string("x00200032")); // ImagePositionPatient
+	        const iop = parseDS(dataSet.string("x00200037")); // ImageOrientationPatient
+	        const spacing = parseDS(dataSet.string("x00280030")); // PixelSpacing
+	        let instanceNumber = parseInt(dataSet.string("x00200013"));
+	        if (Number.isNaN(instanceNumber))
+	            instanceNumber = undefined;
+	        const corners = ipp && iop && spacing
+	            ? computeImagePlaneCorners(ipp, iop, spacing, w, h)
+	            : undefined;
 	        let pixelData = dataSet.elements.x7fe00010;
 	        let uint16 = convertImplicitElement(pixelData, dicomFileAsBuffer);
 	        let voiLUT;
@@ -40852,10 +40863,44 @@ void main() {
 	            uint16,
 	            uint8,
 	            order,
+	            instanceNumber,
+	            imagePositionPatient: ipp,
+	            imageOrientationPatient: iop,
+	            pixelSpacing: spacing,
+	            corners,
 	        };
 	        callback && callback(copperVolume);
 	    });
 	}
+	// Parse a DICOM DS/IS multi-value string ("a\\b\\c") into a number[].
+	function parseDS(s) {
+	    if (!s)
+	        return undefined;
+	    const a = s.split("\\").map((v) => parseFloat(v));
+	    return a.length && !a.some((n) => Number.isNaN(n)) ? a : undefined;
+	}
+	/**
+	 * Compute the 4 world-space corners of a DICOM image plane from its geometry tags.
+	 * IPP is the CENTER of pixel (0,0), so corners sit half a pixel out. PixelSpacing is
+	 * [rowSpacing, colSpacing]; IOP's first vector is the +column-index direction.
+	 */
+	function computeImagePlaneCorners(ipp, iop, spacing, cols, rows) {
+	    const row = new Vector3(iop[0], iop[1], iop[2]); // +column-index dir
+	    const col = new Vector3(iop[3], iop[4], iop[5]); // +row-index dir
+	    const sc = spacing[1]; // column spacing (along row)
+	    const sr = spacing[0]; // row spacing (along col)
+	    const O = new Vector3(ipp[0], ipp[1], ipp[2]); // center of pixel (0,0)
+	    const p = (a, b) => O.clone()
+	        .addScaledVector(row, a * sc)
+	        .addScaledVector(col, b * sr)
+	        .toArray();
+	    return {
+	        tl: p(-0.5, -0.5),
+	        tr: p(cols - 0.5, -0.5),
+	        bl: p(-0.5, rows - 0.5),
+	        br: p(cols - 0.5, rows - 0.5),
+	    };
+	}
 	function convertImplicitElement(elementData, dicomFileAsBuffer) {
 	    let w1Buffer = dicomParser.sharedCopy(dicomFileAsBuffer, elementData.dataOffset, elementData.length);
 	    let unit16 = new Uint16Array(w1Buffer.buffer, w1Buffer.byteOffset, w1Buffer.byteLength / Uint16Array.BYTES_PER_ELEMENT);
@@ -40892,514 +40937,23 @@ void main() {
 	    };
 	}
 
-	// DEFLATE is a complex format; to read this code, you should probably check the RFC first:
+	var vert_2d = "#define GLSLIFY 1\nout vec2 vUv;void main(){gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);vUv=vec2(uv.x,1.0-uv.y);}"; // eslint-disable-line
 
-	// aliases for shorter compressed code (most minifers don't do this)
-	var u8$1 = Uint8Array, u16$1 = Uint16Array, u32 = Uint32Array;
-	// fixed length extra bits
-	var fleb$1 = new u8$1([0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0, /* unused */ 0, 0, /* impossible */ 0]);
-	// fixed distance extra bits
-	// see fleb note
-	var fdeb$1 = new u8$1([0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13, /* unused */ 0, 0]);
-	// code length index map
-	var clim$1 = new u8$1([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]);
-	// get base, reverse index map from extra bits
-	var freb$1 = function (eb, start) {
-	    var b = new u16$1(31);
-	    for (var i = 0; i < 31; ++i) {
-	        b[i] = start += 1 << eb[i - 1];
-	    }
-	    // numbers here are at max 18 bits
-	    var r = new u32(b[30]);
-	    for (var i = 1; i < 30; ++i) {
-	        for (var j = b[i]; j < b[i + 1]; ++j) {
-	            r[j] = ((j - b[i]) << 5) | i;
-	        }
-	    }
-	    return [b, r];
-	};
-	var _a$1 = freb$1(fleb$1, 2), fl$1 = _a$1[0], revfl$1 = _a$1[1];
-	// we can ignore the fact that the other numbers are wrong; they never happen anyway
-	fl$1[28] = 258, revfl$1[258] = 28;
-	var _b$1 = freb$1(fdeb$1, 0), fd$1 = _b$1[0];
-	// map of value to reverse (assuming 16 bits)
-	var rev$1 = new u16$1(32768);
-	for (var i$1 = 0; i$1 < 32768; ++i$1) {
-	    // reverse table algorithm from SO
-	    var x$1 = ((i$1 & 0xAAAA) >>> 1) | ((i$1 & 0x5555) << 1);
-	    x$1 = ((x$1 & 0xCCCC) >>> 2) | ((x$1 & 0x3333) << 2);
-	    x$1 = ((x$1 & 0xF0F0) >>> 4) | ((x$1 & 0x0F0F) << 4);
-	    rev$1[i$1] = (((x$1 & 0xFF00) >>> 8) | ((x$1 & 0x00FF) << 8)) >>> 1;
-	}
-	// create huffman tree from u8 "map": index -> code length for code index
-	// mb (max bits) must be at most 15
-	// TODO: optimize/split up?
-	var hMap$1 = (function (cd, mb, r) {
-	    var s = cd.length;
-	    // index
-	    var i = 0;
-	    // u16 "map": index -> # of codes with bit length = index
-	    var l = new u16$1(mb);
-	    // length of cd must be 288 (total # of codes)
-	    for (; i < s; ++i) {
-	        if (cd[i])
-	            ++l[cd[i] - 1];
-	    }
-	    // u16 "map": index -> minimum code for bit length = index
-	    var le = new u16$1(mb);
-	    for (i = 0; i < mb; ++i) {
-	        le[i] = (le[i - 1] + l[i - 1]) << 1;
-	    }
-	    var co;
-	    if (r) {
-	        // u16 "map": index -> number of actual bits, symbol for code
-	        co = new u16$1(1 << mb);
-	        // bits to remove for reverser
-	        var rvb = 15 - mb;
-	        for (i = 0; i < s; ++i) {
-	            // ignore 0 lengths
-	            if (cd[i]) {
-	                // num encoding both symbol and bits read
-	                var sv = (i << 4) | cd[i];
-	                // free bits
-	                var r_1 = mb - cd[i];
-	                // start value
-	                var v = le[cd[i] - 1]++ << r_1;
-	                // m is end value
-	                for (var m = v | ((1 << r_1) - 1); v <= m; ++v) {
-	                    // every 16 bit value starting with the code yields the same result
-	                    co[rev$1[v] >>> rvb] = sv;
-	                }
-	            }
-	        }
-	    }
-	    else {
-	        co = new u16$1(s);
-	        for (i = 0; i < s; ++i) {
-	            if (cd[i]) {
-	                co[i] = rev$1[le[cd[i] - 1]++] >>> (15 - cd[i]);
-	            }
-	        }
-	    }
-	    return co;
-	});
-	// fixed length tree
-	var flt$1 = new u8$1(288);
-	for (var i$1 = 0; i$1 < 144; ++i$1)
-	    flt$1[i$1] = 8;
-	for (var i$1 = 144; i$1 < 256; ++i$1)
-	    flt$1[i$1] = 9;
-	for (var i$1 = 256; i$1 < 280; ++i$1)
-	    flt$1[i$1] = 7;
-	for (var i$1 = 280; i$1 < 288; ++i$1)
-	    flt$1[i$1] = 8;
-	// fixed distance tree
-	var fdt$1 = new u8$1(32);
-	for (var i$1 = 0; i$1 < 32; ++i$1)
-	    fdt$1[i$1] = 5;
-	// fixed length map
-	var flrm$1 = /*#__PURE__*/ hMap$1(flt$1, 9, 1);
-	// fixed distance map
-	var fdrm$1 = /*#__PURE__*/ hMap$1(fdt$1, 5, 1);
-	// find max of array
-	var max$1 = function (a) {
-	    var m = a[0];
-	    for (var i = 1; i < a.length; ++i) {
-	        if (a[i] > m)
-	            m = a[i];
-	    }
-	    return m;
-	};
-	// read d, starting at bit p and mask with m
-	var bits$1 = function (d, p, m) {
-	    var o = (p / 8) | 0;
-	    return ((d[o] | (d[o + 1] << 8)) >> (p & 7)) & m;
-	};
-	// read d, starting at bit p continuing for at least 16 bits
-	var bits16$1 = function (d, p) {
-	    var o = (p / 8) | 0;
-	    return ((d[o] | (d[o + 1] << 8) | (d[o + 2] << 16)) >> (p & 7));
-	};
-	// get end of byte
-	var shft$1 = function (p) { return ((p + 7) / 8) | 0; };
-	// typed array slice - allows garbage collector to free original reference,
-	// while being more compatible than .slice
-	var slc$1 = function (v, s, e) {
-	    if (s == null || s < 0)
-	        s = 0;
-	    if (e == null || e > v.length)
-	        e = v.length;
-	    // can't use .constructor in case user-supplied
-	    var n = new (v.BYTES_PER_ELEMENT == 2 ? u16$1 : v.BYTES_PER_ELEMENT == 4 ? u32 : u8$1)(e - s);
-	    n.set(v.subarray(s, e));
-	    return n;
-	};
-	// error codes
-	var ec$1 = [
-	    'unexpected EOF',
-	    'invalid block type',
-	    'invalid length/literal',
-	    'invalid distance',
-	    'stream finished',
-	    'no stream handler',
-	    ,
-	    'no callback',
-	    'invalid UTF-8 data',
-	    'extra field too long',
-	    'date not in range 1980-2099',
-	    'filename too long',
-	    'stream finishing',
-	    'invalid zip data'
-	    // determined by unknown compression method
-	];
-	var err$1 = function (ind, msg, nt) {
-	    var e = new Error(msg || ec$1[ind]);
-	    e.code = ind;
-	    if (Error.captureStackTrace)
-	        Error.captureStackTrace(e, err$1);
-	    if (!nt)
-	        throw e;
-	    return e;
-	};
-	// expands raw DEFLATE data
-	var inflt$1 = function (dat, buf, st) {
-	    // source length
-	    var sl = dat.length;
-	    if (!sl || (st && st.f && !st.l))
-	        return buf || new u8$1(0);
-	    // have to estimate size
-	    var noBuf = !buf || st;
-	    // no state
-	    var noSt = !st || st.i;
-	    if (!st)
-	        st = {};
-	    // Assumes roughly 33% compression ratio average
-	    if (!buf)
-	        buf = new u8$1(sl * 3);
-	    // ensure buffer can fit at least l elements
-	    var cbuf = function (l) {
-	        var bl = buf.length;
-	        // need to increase size to fit
-	        if (l > bl) {
-	            // Double or set to necessary, whichever is greater
-	            var nbuf = new u8$1(Math.max(bl * 2, l));
-	            nbuf.set(buf);
-	            buf = nbuf;
-	        }
-	    };
-	    //  last chunk         bitpos           bytes
-	    var final = st.f || 0, pos = st.p || 0, bt = st.b || 0, lm = st.l, dm = st.d, lbt = st.m, dbt = st.n;
-	    // total bits
-	    var tbts = sl * 8;
-	    do {
-	        if (!lm) {
-	            // BFINAL - this is only 1 when last chunk is next
-	            final = bits$1(dat, pos, 1);
-	            // type: 0 = no compression, 1 = fixed huffman, 2 = dynamic huffman
-	            var type = bits$1(dat, pos + 1, 3);
-	            pos += 3;
-	            if (!type) {
-	                // go to end of byte boundary
-	                var s = shft$1(pos) + 4, l = dat[s - 4] | (dat[s - 3] << 8), t = s + l;
-	                if (t > sl) {
-	                    if (noSt)
-	                        err$1(0);
-	                    break;
-	                }
-	                // ensure size
-	                if (noBuf)
-	                    cbuf(bt + l);
-	                // Copy over uncompressed data
-	                buf.set(dat.subarray(s, t), bt);
-	                // Get new bitpos, update byte count
-	                st.b = bt += l, st.p = pos = t * 8, st.f = final;
-	                continue;
-	            }
-	            else if (type == 1)
-	                lm = flrm$1, dm = fdrm$1, lbt = 9, dbt = 5;
-	            else if (type == 2) {
-	                //  literal                            lengths
-	                var hLit = bits$1(dat, pos, 31) + 257, hcLen = bits$1(dat, pos + 10, 15) + 4;
-	                var tl = hLit + bits$1(dat, pos + 5, 31) + 1;
-	                pos += 14;
-	                // length+distance tree
-	                var ldt = new u8$1(tl);
-	                // code length tree
-	                var clt = new u8$1(19);
-	                for (var i = 0; i < hcLen; ++i) {
-	                    // use index map to get real code
-	                    clt[clim$1[i]] = bits$1(dat, pos + i * 3, 7);
-	                }
-	                pos += hcLen * 3;
-	                // code lengths bits
-	                var clb = max$1(clt), clbmsk = (1 << clb) - 1;
-	                // code lengths map
-	                var clm = hMap$1(clt, clb, 1);
-	                for (var i = 0; i < tl;) {
-	                    var r = clm[bits$1(dat, pos, clbmsk)];
-	                    // bits read
-	                    pos += r & 15;
-	                    // symbol
-	                    var s = r >>> 4;
-	                    // code length to copy
-	                    if (s < 16) {
-	                        ldt[i++] = s;
-	                    }
-	                    else {
-	                        //  copy   count
-	                        var c = 0, n = 0;
-	                        if (s == 16)
-	                            n = 3 + bits$1(dat, pos, 3), pos += 2, c = ldt[i - 1];
-	                        else if (s == 17)
-	                            n = 3 + bits$1(dat, pos, 7), pos += 3;
-	                        else if (s == 18)
-	                            n = 11 + bits$1(dat, pos, 127), pos += 7;
-	                        while (n--)
-	                            ldt[i++] = c;
-	                    }
-	                }
-	                //    length tree                 distance tree
-	                var lt = ldt.subarray(0, hLit), dt = ldt.subarray(hLit);
-	                // max length bits
-	                lbt = max$1(lt);
-	                // max dist bits
-	                dbt = max$1(dt);
-	                lm = hMap$1(lt, lbt, 1);
-	                dm = hMap$1(dt, dbt, 1);
-	            }
-	            else
-	                err$1(1);
-	            if (pos > tbts) {
-	                if (noSt)
-	                    err$1(0);
-	                break;
-	            }
-	        }
-	        // Make sure the buffer can hold this + the largest possible addition
-	        // Maximum chunk size (practically, theoretically infinite) is 2^17;
-	        if (noBuf)
-	            cbuf(bt + 131072);
-	        var lms = (1 << lbt) - 1, dms = (1 << dbt) - 1;
-	        var lpos = pos;
-	        for (;; lpos = pos) {
-	            // bits read, code
-	            var c = lm[bits16$1(dat, pos) & lms], sym = c >>> 4;
-	            pos += c & 15;
-	            if (pos > tbts) {
-	                if (noSt)
-	                    err$1(0);
-	                break;
-	            }
-	            if (!c)
-	                err$1(2);
-	            if (sym < 256)
-	                buf[bt++] = sym;
-	            else if (sym == 256) {
-	                lpos = pos, lm = null;
-	                break;
-	            }
-	            else {
-	                var add = sym - 254;
-	                // no extra bits needed if less
-	                if (sym > 264) {
-	                    // index
-	                    var i = sym - 257, b = fleb$1[i];
-	                    add = bits$1(dat, pos, (1 << b) - 1) + fl$1[i];
-	                    pos += b;
-	                }
-	                // dist
-	                var d = dm[bits16$1(dat, pos) & dms], dsym = d >>> 4;
-	                if (!d)
-	                    err$1(3);
-	                pos += d & 15;
-	                var dt = fd$1[dsym];
-	                if (dsym > 3) {
-	                    var b = fdeb$1[dsym];
-	                    dt += bits16$1(dat, pos) & ((1 << b) - 1), pos += b;
-	                }
-	                if (pos > tbts) {
-	                    if (noSt)
-	                        err$1(0);
-	                    break;
-	                }
-	                if (noBuf)
-	                    cbuf(bt + 131072);
-	                var end = bt + add;
-	                for (; bt < end; bt += 4) {
-	                    buf[bt] = buf[bt - dt];
-	                    buf[bt + 1] = buf[bt + 1 - dt];
-	                    buf[bt + 2] = buf[bt + 2 - dt];
-	                    buf[bt + 3] = buf[bt + 3 - dt];
-	                }
-	                bt = end;
-	            }
-	        }
-	        st.l = lm, st.p = lpos, st.b = bt, st.f = final;
-	        if (lm)
-	            final = 1, st.m = lbt, st.d = dm, st.n = dbt;
-	    } while (!final);
-	    return bt == buf.length ? buf : slc$1(buf, 0, bt);
-	};
-	// empty
-	var et$1 = /*#__PURE__*/ new u8$1(0);
-	// read 2 bytes
-	var b2 = function (d, b) { return d[b] | (d[b + 1] << 8); };
-	// read 4 bytes
-	var b4 = function (d, b) { return (d[b] | (d[b + 1] << 8) | (d[b + 2] << 16) | (d[b + 3] << 24)) >>> 0; };
-	var b8 = function (d, b) { return b4(d, b) + (b4(d, b + 4) * 4294967296); };
-	/**
-	 * Expands DEFLATE data with no wrapper
-	 * @param data The data to decompress
-	 * @param out Where to write the data. Saves memory if you know the decompressed size and provide an output buffer of that length.
-	 * @returns The decompressed version of the data
-	 */
-	function inflateSync(data, out) {
-	    return inflt$1(data, out);
-	}
-	// text decoder
-	var td$1 = typeof TextDecoder != 'undefined' && /*#__PURE__*/ new TextDecoder();
-	// text decoder stream
-	var tds$1 = 0;
-	try {
-	    td$1.decode(et$1, { stream: true });
-	    tds$1 = 1;
-	}
-	catch (e) { }
-	// decode UTF8
-	var dutf8 = function (d) {
-	    for (var r = '', i = 0;;) {
-	        var c = d[i++];
-	        var eb = (c > 127) + (c > 223) + (c > 239);
-	        if (i + eb > d.length)
-	            return [r, slc$1(d, i - 1)];
-	        if (!eb)
-	            r += String.fromCharCode(c);
-	        else if (eb == 3) {
-	            c = ((c & 15) << 18 | (d[i++] & 63) << 12 | (d[i++] & 63) << 6 | (d[i++] & 63)) - 65536,
-	                r += String.fromCharCode(55296 | (c >> 10), 56320 | (c & 1023));
-	        }
-	        else if (eb & 1)
-	            r += String.fromCharCode((c & 31) << 6 | (d[i++] & 63));
-	        else
-	            r += String.fromCharCode((c & 15) << 12 | (d[i++] & 63) << 6 | (d[i++] & 63));
-	    }
-	};
-	/**
-	 * Converts a Uint8Array to a string
-	 * @param dat The data to decode to string
-	 * @param latin1 Whether or not to interpret the data as Latin-1. This should
-	 *               not need to be true unless encoding to binary string.
-	 * @returns The original UTF-8/Latin-1 string
-	 */
-	function strFromU8(dat, latin1) {
-	    if (latin1) {
-	        var r = '';
-	        for (var i = 0; i < dat.length; i += 16384)
-	            r += String.fromCharCode.apply(null, dat.subarray(i, i + 16384));
-	        return r;
-	    }
-	    else if (td$1)
-	        return td$1.decode(dat);
-	    else {
-	        var _a = dutf8(dat), out = _a[0], ext = _a[1];
-	        if (ext.length)
-	            err$1(8);
-	        return out;
-	    }
-	}
-	// skip local zip header
-	var slzh = function (d, b) { return b + 30 + b2(d, b + 26) + b2(d, b + 28); };
-	// read zip header
-	var zh = function (d, b, z) {
-	    var fnl = b2(d, b + 28), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl, bs = b4(d, b + 20);
-	    var _a = z && bs == 4294967295 ? z64e(d, es) : [bs, b4(d, b + 24), b4(d, b + 42)], sc = _a[0], su = _a[1], off = _a[2];
-	    return [b2(d, b + 10), sc, su, fn, es + b2(d, b + 30) + b2(d, b + 32), off];
-	};
-	// read zip64 extra field
-	var z64e = function (d, b) {
-	    for (; b2(d, b) != 1; b += 4 + b2(d, b + 2))
-	        ;
-	    return [b8(d, b + 12), b8(d, b + 4), b8(d, b + 20)];
-	};
-	/**
-	 * Synchronously decompresses a ZIP archive. Prefer using `unzip` for better
-	 * performance with more than one file.
-	 * @param data The raw compressed ZIP file
-	 * @param opts The ZIP extraction options
-	 * @returns The decompressed files
-	 */
-	function unzipSync(data, opts) {
-	    var files = {};
-	    var e = data.length - 22;
-	    for (; b4(data, e) != 0x6054B50; --e) {
-	        if (!e || data.length - e > 65558)
-	            err$1(13);
-	    }
-	    var c = b2(data, e + 8);
-	    if (!c)
-	        return {};
-	    var o = b4(data, e + 16);
-	    var z = o == 4294967295 || c == 65535;
-	    if (z) {
-	        var ze = b4(data, e - 12);
-	        z = b4(data, ze) == 0x6064B50;
-	        if (z) {
-	            c = b4(data, ze + 32);
-	            o = b4(data, ze + 48);
-	        }
-	    }
-	    var fltr = opts && opts.filter;
-	    for (var i = 0; i < c; ++i) {
-	        var _a = zh(data, o, z), c_2 = _a[0], sc = _a[1], su = _a[2], fn = _a[3], no = _a[4], off = _a[5], b = slzh(data, off);
-	        o = no;
-	        if (!fltr || fltr({
-	            name: fn,
-	            size: sc,
-	            originalSize: su,
-	            compression: c_2
-	        })) {
-	            if (!c_2)
-	                files[fn] = slc$1(data, b, b + sc);
-	            else if (c_2 == 8)
-	                files[fn] = inflateSync(data.subarray(b, b + sc), new u8$1(su));
-	            else
-	                err$1(14, 'unknown compression type ' + c_2);
-	        }
-	    }
-	    return files;
-	}
-
-	var vert_2d = "#define GLSLIFY 1\nuniform vec2 size;out vec2 vUv;void main(){gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);vUv.xy=position.xy/size+0.5;vUv.y=1.0-vUv.y;}"; // eslint-disable-line
-
-	var frag_2d = "precision highp float;precision highp int;precision highp sampler2DArray;\n#define GLSLIFY 1\nuniform sampler2DArray diffuse;in vec2 vUv;uniform int depth;out vec4 outColor;void main(){vec4 color=texture(diffuse,vec3(vUv,depth));outColor=vec4(color.rrr*1.5,1.0);}"; // eslint-disable-line
+	var frag_2d = "precision highp float;precision highp int;precision highp sampler2DArray;\n#define GLSLIFY 1\nuniform sampler2DArray diffuse;in vec2 vUv;uniform int depth;uniform float uOpacity;out vec4 outColor;void main(){vec4 color=texture(diffuse,vec3(vUv,depth));outColor=vec4(color.rrr*1.5,uOpacity);}"; // eslint-disable-line
 
 	let planeWidth = 80;
 	let planeHeight = 80;
-	function createTexture2D_Zip(url, scene) {
-	    new FileLoader()
-	        .setResponseType("arraybuffer")
-	        .load(url, function (data) {
-	        const zip = unzipSync(new Uint8Array(data));
-	        const array = new Uint8Array(zip["head256x256x109"].buffer);
-	        const texture = new DataArrayTexture(array, 256, 256, 109);
-	        texture.format = RedFormat;
-	        texture.needsUpdate = true;
-	        const material = new ShaderMaterial({
-	            uniforms: {
-	                diffuse: { value: texture },
-	                depth: { value: 1 },
-	                size: { value: new Vector2(planeWidth, planeHeight) },
-	            },
-	            vertexShader: vert_2d,
-	            fragmentShader: frag_2d,
-	            glslVersion: GLSL3,
-	            side: DoubleSide,
-	        });
-	        const geometry = new PlaneGeometry(planeWidth, planeHeight);
-	        const mesh = new Mesh(geometry, material);
-	        mesh.name = "texture2d_mesh_zip";
-	        scene.add(mesh);
-	    });
+	// Build a quad from the 4 world-space image-plane corners (preserves real pose).
+	function buildAlignedQuad(c) {
+	    const g = new BufferGeometry();
+	    // two triangles: tl,bl,tr / tr,bl,br
+	    g.setAttribute("position", new BufferAttribute(new Float32Array([...c.tl, ...c.bl, ...c.tr, ...c.tr, ...c.bl, ...c.br]), 3));
+	    // vertex order is tl, bl, tr, tr, bl, br. The fragment shader flips v (vUv.y = 1-uv.y)
+	    // and DataArrayTexture has no flipY, so the image-top (data row 0) must map to the
+	    // top world corner: tl/tr get uv.y = 1.
+	    g.setAttribute("uv", new BufferAttribute(new Float32Array([0, 1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 0]), 2));
+	    g.computeVertexNormals();
+	    return g;
 	}
 	function createTexture2D_NRRD(data, width, height, depth, callback) {
 	    const texture = new DataArrayTexture(data, width, height, depth);
@@ -41409,7 +40963,7 @@ void main() {
 	        uniforms: {
 	            diffuse: { value: texture },
 	            depth: { value: 1 },
-	            size: { value: new Vector2(planeWidth, planeHeight) },
+	            uOpacity: { value: 1 },
 	        },
 	        vertexShader: vert_2d,
 	        fragmentShader: frag_2d,
@@ -41421,13 +40975,9 @@ void main() {
 	    mesh.name = "texture2d_mesh_zip";
 	    callback(mesh);
 	}
-	function createTexture2D_Array(copperVolume, depth, scene, gui) {
+	function createTexture2D_Array(copperVolume, depth, scene, gui, aligned = false) {
 	    planeWidth = copperVolume.width / 2;
 	    planeHeight = copperVolume.height / 2;
-	    ({
-	        windowWidth: copperVolume.windowWidth,
-	        windowCenter: copperVolume.windowCenter,
-	    });
 	    const texture = new DataArrayTexture(copperVolume.uint8, copperVolume.width, copperVolume.height, depth);
 	    texture.format = RedFormat;
 	    texture.needsUpdate = true;
@@ -41454,18 +41004,22 @@ void main() {
 	    const material = new ShaderMaterial({
 	        uniforms: {
 	            diffuse: { value: texture },
-	            depth: { value: 1 },
-	            size: { value: new Vector2(planeWidth, planeHeight) },
+	            depth: { value: 0 },
+	            uOpacity: { value: 1 },
 	        },
 	        vertexShader: vert_2d,
 	        fragmentShader: frag_2d,
 	        glslVersion: GLSL3,
 	        side: DoubleSide,
 	    });
-	    const geometry = new PlaneGeometry(planeWidth, planeHeight);
+	    // Aligned world-space quad only when explicitly requested and geometry tags exist;
+	    // otherwise the legacy centred plane (keeps existing loadDicom behaviour unchanged).
+	    const geometry = aligned && copperVolume.corners
+	        ? buildAlignedQuad(copperVolume.corners)
+	        : new PlaneGeometry(planeWidth, planeHeight);
 	    const mesh = new Mesh(geometry, material);
-	    scene.add(mesh);
 	    mesh.name = "texture2d_mesh_array";
+	    scene.add(mesh);
 	    function updateTexture(copperVolumeUp) {
 	        if (!!copperVolumeUp) {
 	            let voiLUT;
@@ -41476,7 +41030,15 @@ void main() {
 	            texture.needsUpdate = true;
 	        }
 	    }
-	    return { mesh, copperVolume, updateTexture };
+	    function setFrame(i) {
+	        material.uniforms.depth.value = i;
+	    }
+	    function setWindow(center, width) {
+	        copperVolume.windowCenter = center;
+	        copperVolume.windowWidth = width;
+	        updateTexture(copperVolume);
+	    }
+	    return { mesh, copperVolume, updateTexture, setFrame, setWindow };
 	}
 
 	/*!
@@ -50532,6 +50094,7 @@ void main() {
 	class baseRenderer {
 	    constructor(container, options) {
 	        var _a, _b, _c, _d, _e;
+	        this.running = true;
 	        this.visualCtrls = [];
 	        this.container = container;
 	        this.options = options;
@@ -50632,6 +50195,25 @@ void main() {
 	    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({
@@ -59308,6 +58890,7 @@ void main() {
 	}
 
 	class copperScene extends baseScene {
+	    // rayster pick
 	    constructor(container, renderer, opt) {
 	        super(container, renderer, opt);
 	        this.clock = new Clock();
@@ -59315,9 +58898,6 @@ void main() {
 	        this.mixer = null;
 	        this.playRate = 1.0;
 	        this.modelReady = false;
-	        // rayster pick
-	        // texture2d
-	        this.texture2dMesh = null;
 	        if ((opt === null || opt === void 0 ? void 0 : opt.controls) === "trackball") {
 	            this.controls = new TrackballControls(this.camera, this.renderer.domElement);
 	        }
@@ -59523,38 +59103,177 @@ void main() {
 	            this.exportContent.animations.push(clip);
 	        };
 	    }
-	    // texture2d
-	    texture2d(url) {
-	        createTexture2D_Zip(url, this.scene);
-	        const textureInterval = setInterval(() => {
-	            var _a;
-	            this.scene.children.forEach((child) => {
-	                if (child.isMesh) {
-	                    if (child.name === "texture2d_mesh_zip") {
-	                        this.texture2dMesh = child;
-	                        const render_texture2d = () => {
-	                            if (this.texture2dMesh) {
-	                                let value = this.texture2dMesh.material.uniforms["depth"].value;
-	                                value += this.depthStep;
-	                                if (value > 109.0 || value < 0.0) {
-	                                    if (value > 1.0)
-	                                        value = 109.0 * 2.0 - value;
-	                                    if (value < 0.0)
-	                                        value = -value;
-	                                    this.depthStep = -this.depthStep;
-	                                }
-	                                this.texture2dMesh.material.uniforms["depth"].value =
-	                                    value;
-	                            }
-	                        };
-	                        this.addPreRenderCallbackFunction(render_texture2d);
-	                    }
-	                }
+	    /**
+	     * Load an aligned 4D scene: a cine MRI (one slice, N cardiac phases) rendered as a
+	     * world-placed plane, plus 0..N deforming surface sequences (e.g. LV endo/epi). MRI
+	     * and surfaces stay in their shared patient coordinate frame (no center/scale), and
+	     * advance together off ONE shared frame clock. Returns a controller (play/pause/...).
+	     */
+	    loadAligned4D(opts, callback) {
+	        var _a;
+	        const dicomDepth = opts.dicomUrls.length;
+	        const loadDicomStack = () => new Promise((resolve) => {
+	            const volumes = [];
+	            opts.dicomUrls.forEach((url) => {
+	                copperDicomLoader(url, (volume) => {
+	                    volumes.push(volume);
+	                    if (volumes.length !== dicomDepth)
+	                        return;
+	                    // order frames by cardiac phase (TriggerTime / SliceLocation)
+	                    volumes.sort((a, b) => a.order - b.order);
+	                    const frameSize = volumes[0].width * volumes[0].height;
+	                    const uint8 = new Uint8ClampedArray(frameSize * dicomDepth);
+	                    const uint16 = new Uint16Array(uint8.length);
+	                    volumes.forEach((v, index) => {
+	                        uint8.set(v.uint8, index * frameSize);
+	                        uint16.set(v.uint16, index * frameSize);
+	                    });
+	                    const stacked = Object.assign(Object.assign({}, volumes[0]), { uint8,
+	                        uint16 });
+	                    resolve(stacked);
+	                });
+	            });
+	        });
+	        const loadSurfaceSequence = (urls) => new Promise((resolve) => {
+	            const loader = new VTKLoader();
+	            const geometries = new Array(urls.length);
+	            let done = 0;
+	            urls.forEach((url, index) => {
+	                loader.load(url, (geometry) => {
+	                    // keep world coordinates — no center()/scale()
+	                    geometry.computeVertexNormals();
+	                    geometries[index] = geometry;
+	                    if (++done === urls.length)
+	                        resolve(geometries);
+	                });
 	            });
-	            if (((_a = this.texture2dMesh) === null || _a === void 0 ? void 0 : _a.name) === "texture2d_mesh_zip") {
-	                clearInterval(textureInterval);
+	        });
+	        const surfaceDefs = (_a = opts.surfaces) !== null && _a !== void 0 ? _a : [];
+	        Promise.all([
+	            loadDicomStack(),
+	            ...surfaceDefs.map((s) => loadSurfaceSequence(s.urls)),
+	        ]).then(([stacked, ...surfaceGeoms]) => {
+	            var _a;
+	            if (opts.window) {
+	                stacked.windowCenter = opts.window.center;
+	                stacked.windowWidth = opts.window.width;
 	            }
-	        }, 500);
+	            const tex = createTexture2D_Array(stacked, dicomDepth, this.scene, undefined, true);
+	            tex.setFrame(0);
+	            if (opts.window)
+	                tex.setWindow(opts.window.center, opts.window.width);
+	            const surfaceMeshes = {};
+	            const seqs = [];
+	            surfaceDefs.forEach((def, i) => {
+	                var _a;
+	                const geometries = surfaceGeoms[i];
+	                const { vtkmaterial } = copperMultipleVtk(def.opts);
+	                const mesh = new Mesh(geometries[0], vtkmaterial);
+	                mesh.name = def.name;
+	                this.scene.add(mesh);
+	                surfaceMeshes[def.name] = mesh;
+	                seqs.push({ mesh, geometries, offset: (_a = def.offset) !== null && _a !== void 0 ? _a : 0 });
+	            });
+	            const frameCount = dicomDepth;
+	            // Default one cardiac cycle ≈ 1012ms (32 phases × ~31.6ms) unless overridden.
+	            const cycleMs = (_a = opts.cycleMs) !== null && _a !== void 0 ? _a : 1012;
+	            let frameIndex = 0;
+	            let speed = 1;
+	            let playing = true;
+	            let disposed = false;
+	            let lastStep = performance.now();
+	            const dtBase = cycleMs / frameCount;
+	            const applyFrame = () => {
+	                tex.setFrame(frameIndex);
+	                for (const s of seqs) {
+	                    const i = (frameIndex + s.offset + s.geometries.length) % s.geometries.length;
+	                    s.mesh.geometry = s.geometries[i];
+	                }
+	            };
+	            const tick = () => {
+	                if (disposed || !playing)
+	                    return;
+	                const now = performance.now();
+	                if (now - lastStep >= dtBase / speed) {
+	                    lastStep = now;
+	                    frameIndex = (frameIndex + 1) % frameCount;
+	                    applyFrame();
+	                }
+	            };
+	            this.addPreRenderCallbackFunction(tick);
+	            const clockId = tick.id;
+	            const ctrl = {
+	                plane: tex.mesh,
+	                surfaceMeshes,
+	                frameCount,
+	                play: () => {
+	                    playing = true;
+	                    lastStep = performance.now();
+	                },
+	                pause: () => {
+	                    playing = false;
+	                },
+	                toggle: () => {
+	                    playing = !playing;
+	                    lastStep = performance.now();
+	                },
+	                setSpeed: (x) => {
+	                    speed = Math.max(0.01, x);
+	                },
+	                setFrame: (i) => {
+	                    frameIndex = ((i % frameCount) + frameCount) % frameCount;
+	                    applyFrame();
+	                },
+	                setFrameOffset: (name, n) => {
+	                    const s = seqs.find((q) => q.mesh.name === name);
+	                    if (s) {
+	                        s.offset = n;
+	                        applyFrame();
+	                    }
+	                },
+	                setWindow: (center, width) => {
+	                    tex.setWindow(center, width);
+	                },
+	                setPlaneOpacity: (v) => {
+	                    const m = tex.mesh.material;
+	                    m.transparent = v < 1;
+	                    m.uniforms.uOpacity.value = v;
+	                    m.needsUpdate = true;
+	                },
+	                setSurfaceOpacity: (name, v) => {
+	                    const mesh = surfaceMeshes[name];
+	                    if (!mesh)
+	                        return;
+	                    const m = mesh.material;
+	                    m.transparent = v < 1;
+	                    m.opacity = v;
+	                    m.needsUpdate = true;
+	                },
+	                setSurfaceVisible: (name, visible) => {
+	                    const mesh = surfaceMeshes[name];
+	                    if (mesh)
+	                        mesh.visible = visible;
+	                },
+	                dispose: () => {
+	                    var _a, _b;
+	                    disposed = true;
+	                    this.removePreRenderCallbackFunction(clockId);
+	                    // plane
+	                    this.scene.remove(tex.mesh);
+	                    tex.mesh.geometry.dispose();
+	                    const pm = tex.mesh.material;
+	                    (_b = (_a = pm.uniforms.diffuse.value) === null || _a === void 0 ? void 0 : _a.dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
+	                    pm.dispose();
+	                    // surfaces
+	                    for (const s of seqs) {
+	                        this.scene.remove(s.mesh);
+	                        s.geometries.forEach((g) => g.dispose());
+	                        s.mesh.material.dispose();
+	                    }
+	                },
+	            };
+	            callback && callback(ctrl);
+	        });
 	    }
 	    getPlayRate() {
 	        return this.playRate;
@@ -59662,6 +59381,8 @@ void main() {
 	        this.preRenderCallbackFunctions = [];
 	        this.animate = (time) => {
 	            var _a, _b, _c;
+	            if (!this.running)
+	                return;
 	            switch ((_a = this.options) === null || _a === void 0 ? void 0 : _a.fpsMode) {
 	                case "1":
 	                    // fpsControl one: 30fps
@@ -60212,6 +59933,7 @@ void main() {
 	            alpha: true,
 	            antialias: true,
 	        });
+	        this.running = true;
 	        this.renderSceneInfo = (sceneInfo) => {
 	            const elem = sceneInfo.container;
 	            // get the viewpoint relative position of this element
@@ -60250,6 +59972,8 @@ void main() {
 	            }
 	        };
 	        this.animate = () => {
+	            if (!this.running)
+	                return;
 	            const clearColor = new Color$1("#000");
 	            this.renderer.setScissorTest(false);
 	            this.renderer.setClearColor(clearColor, 0);
@@ -60315,6 +60039,25 @@ void main() {
 	            }, 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());
+	    }
 	}
 
 	/******************************************************************************
@@ -70734,6 +70477,36 @@ void main() {
 	    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'.
@@ -73882,6 +73655,8 @@ void main() {
 	    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,
@@ -74007,7 +73782,20 @@ void main() {
 	     * 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) {
@@ -74021,8 +73809,9 @@ void main() {
 	     * 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,
@@ -74030,7 +73819,15 @@ void main() {
 	        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.
@@ -74166,8 +73963,8 @@ void main() {
 	            }
 	        }
 	        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;
 	            }
@@ -74204,6 +74001,10 @@ void main() {
 	        }
 	        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
@@ -74224,7 +74025,10 @@ void main() {
 	        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
@@ -76147,6 +75951,474 @@ void main() {
 	    }
 	}
 
+	/**
+	 * 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.
 	 *
@@ -76267,6 +76539,10 @@ void main() {
 	            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
@@ -76373,6 +76649,8 @@ void main() {
 	                // 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
@@ -76386,6 +76664,10 @@ void main() {
 	        });
 	        // 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);
 	            }
@@ -76400,6 +76682,14 @@ void main() {
 	            }
 	        });
 	        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.
@@ -76559,7 +76849,10 @@ void main() {
 	                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()) {
@@ -76674,6 +76967,12 @@ void main() {
 	                    || 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();
@@ -78278,6 +78577,13 @@ void main() {
 	        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");
@@ -78445,6 +78751,13 @@ void main() {
 	        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;
@@ -79093,6 +79406,111 @@ void main() {
 	        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
 	    // ═══════════════════════════════════════════════════════════════════════════
@@ -79456,9 +79874,11 @@ void main() {
 	}
 
 	// import * as kiwrious from "copper3d_plugin_heart_k";
-	const REVISION = "v3.4.8-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");
 
+	exports.AI_CHANNEL_HEX_COLORS = AI_CHANNEL_HEX_COLORS;
+	exports.AI_MASK_CHANNEL_COLORS = AI_MASK_CHANNEL_COLORS;
 	exports.CHANNEL_COLORS = CHANNEL_COLORS;
 	exports.CHANNEL_HEX_COLORS = CHANNEL_HEX_COLORS;
 	exports.CameraViewPoint = CameraViewPoint;