From 10a2cb287fe31f51a061f111afaf51346b7060c2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 13 Jul 2026 03:21:01 +0000
Subject: [PATCH 1/2] Extract Quantosaurus class + event bus; drive existing UI
 through it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce js/quantosaurus.js: an EventTarget-based app core that owns the
shared state object (images, forest, tools, camera) and attaches to a board
element. Every state change now flows out as a CustomEvent (imageadded,
labelschanged, trainingstart/complete, statscomputed, dirtychange, etc.), so
chrome subscribes instead of being hard-wired — the groundwork for embedding
the board without the sidebar.

- images.js/training.js stop importing ui.js and reach into document by id;
  they read state.board/state.brushSize and dispatch via state.events
  (optional-chained so the CPU unit tests stay Node-importable).
- Brush size becomes real instance state instead of being read off the slider
  DOM inside the paint handlers.
- ui.js gains bindChrome(q), a pure event subscriber reproducing today's
  sidebar rows, status line, save indicator, and count badges unchanged.
- index.html's inline script becomes a consumer of the class; the File System
  Access .ilp save stays in the shell and calls q.markSaved().
- Consolidate the two duplicate class-rename onblur handlers into one path
  through q.setClassName (the old second copy dropped saveSettings).
- config.js: add BRUSH_SIZE_* constants + pure clampBrushSize, covered by
  config.test.mjs.

No visual or behavioral change; verified in a headless browser (load, paint,
train, counts, brush hotkeys, recolor, rename+persist, contrast, delete) with
zero console errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VobFMvLSfYoBDLD1tAANma
---
 index.html         | 281 +++++++++++++----------------------
 js/config.js       |  20 +++
 js/config.test.mjs |  35 ++++-
 js/images.js       | 117 ++++++++-------
 js/quantosaurus.js | 362 +++++++++++++++++++++++++++++++++++++++++++++
 js/training.js     |  41 +++--
 js/ui.js           |  76 ++++++++++
 7 files changed, 686 insertions(+), 246 deletions(-)
 create mode 100644 js/quantosaurus.js

diff --git a/index.html b/index.html
index 824f46b..c1abcb9 100644
--- a/index.html
+++ b/index.html
@@ -231,79 +231,37 @@ <h3>Frequently Asked Questions</h3>
 
 </div>
 <script type="module">
-    import { DEFAULT_LABEL_COLORS, RF_CONFIG } from './js/config.js'
-    import { addFiles, redrawLabels, renderCentroids } from './js/images.js';
-    import { zipImages, exportIlp } from './js/export.js';
-    import { setupCamera } from './js/camera.js';
-    import { FlatRandomForest } from './js/rf.js';
-    import { scheduleTraining } from './js/training.js'
-    import { loadSettings, saveSettings } from './js/settings.js';
-    import { updateSaveIndicator } from './js/ui.js';
-
-    const state = {
-        // Images — ordered array; visual order == export order
-        images: [],
-
-        // ML
-        rf: new FlatRandomForest(RF_CONFIG),
-
-        // Presentation — per-class overlay colors, indexed by class. Owned by the
-        // UI (mutable), seeded from config defaults. The class *count* comes from
-        // rf.numClasses; colors are a separate concern that can change at runtime.
-        labelColors: [...DEFAULT_LABEL_COLORS],
-
-        // Per-class display names, indexed by class. Like labelColors, this is a
-        // UI-owned presentation concern (renamable at runtime, persisted to
-        // localStorage); the class *count* still comes from rf.numClasses.
-        classNames: Array.from({ length: RF_CONFIG.numClasses }, (_, i) => `Class ${i + 1}`),
-
-        // Whether each class's centroid markers are drawn on canvas (toggled via the
-        // class-item's swatch dot). Session-only — like camera/labels, not persisted.
-        classMarkersVisible: new Array(RF_CONFIG.numClasses).fill(true),
-
-        // Drawing / Tools
-        currentClass: 0,
-        isDrawing: false,
-        activeImageId: null,
-        toolMode: 'grab', // 'grab', 'paint', 'erase'
-
-        // Features
-        sigma: 1.0,
-
-        // Camera
-        camera: { x: 0, y: 0, scale: 1 },
-        isSpaceDown: false,
-        isPanning: false,
-        activePointerCount: 0,
-
-        // True while a debounced retrain+inference is running; drives the training
-        // progress cursor / status message (see setTrainingIndicator).
-        isTraining: false,
-        // Save state for the .ilp export (Ctrl+S). dirty tracks whether there
-        // are changes since the last successful save (set on image/label
-        // mutations in images.js, cleared by saveIlpProject); ilpFileHandle is
-        // the FileSystemFileHandle from a prior showSaveFilePicker() call, kept
-        // so repeat saves overwrite the same file instead of re-prompting
-        // (Chromium only — unset in browsers without the File System Access API).
-        dirty: false,
-        ilpFileHandle: null,
-    };
+    import { Quantosaurus } from './js/quantosaurus.js';
+    import { bindChrome } from './js/ui.js';
+
+    // The app core — owns the shared state (images, forest, tools, camera) and
+    // emits CustomEvents for every state change. All chrome below is a consumer:
+    // it calls methods on `q` and subscribes to its events (see bindChrome and
+    // setupUI), never mutating q.state directly.
+    let q;
+
+    // FileSystemFileHandle from a prior showSaveFilePicker() call, kept so
+    // repeat saves overwrite the same file instead of re-prompting (Chromium
+    // only — stays null in browsers without the File System Access API). Owned
+    // by this shell, not the app core: how a project blob gets persisted is a
+    // host concern (an embed would save differently).
+    let ilpFileHandle = null;
 
     function init() {
         const viewport = document.getElementById('viewport');
         const board    = document.getElementById('canvas-board');
-        setupCamera(state, viewport, board);
-        loadSettings(state);   // restore persisted colors/names before the class UI renders
+        q = new Quantosaurus(board, { viewportEl: viewport });
+        bindChrome(q);
         setupUI();
         setupFeedback();
         setupTheme();
 
         // Guard against accidentally discarding work (loaded images + painted labels,
         // none of which is persisted). Only prompt when there are actual unsaved
-        // changes — state.dirty tracks that precisely (see images.js's mutation
-        // points and saveIlpProject below), so this stays quiet right after a save.
+        // changes — q.dirty tracks that precisely (set on image/label mutations,
+        // cleared by saveIlpProject below), so this stays quiet right after a save.
         window.addEventListener('beforeunload', (e) => {
-            if (state.dirty) {
+            if (q.dirty) {
                 e.preventDefault();
                 e.returnValue = '';
             }
@@ -339,12 +297,12 @@ <h3>Frequently Asked Questions</h3>
     }
 
     /**
-     * Writes `blob` to state.ilpFileHandle, prompting via showSaveFilePicker if
+     * Writes `blob` to ilpFileHandle, prompting via showSaveFilePicker if
      * there's no handle yet (Chromium only). Falls back to a plain download link
      * in browsers without the File System Access API (Firefox, Safari), which
      * re-prompts on every save since there's no persistent handle to reuse.
      * Throws (with err.name === 'AbortError') if the user cancels the picker;
-     * clears state.ilpFileHandle and rethrows on any other write failure so the
+     * clears ilpFileHandle and rethrows on any other write failure so the
      * caller can retry once with a fresh picker (the old handle may be stale —
      * revoked permission, or the file was moved/deleted).
      */
@@ -353,18 +311,18 @@ <h3>Frequently Asked Questions</h3>
             downloadBlob(blob, `quantosaurus_${dateStamp()}.ilp`);
             return;
         }
-        if (!state.ilpFileHandle) {
-            state.ilpFileHandle = await window.showSaveFilePicker({
+        if (!ilpFileHandle) {
+            ilpFileHandle = await window.showSaveFilePicker({
                 suggestedName: `quantosaurus_${dateStamp()}.ilp`,
                 ...ILP_PICKER_OPTS,
             });
         }
         try {
-            const writable = await state.ilpFileHandle.createWritable();
+            const writable = await ilpFileHandle.createWritable();
             await writable.write(blob);
             await writable.close();
         } catch (err) {
-            state.ilpFileHandle = null;
+            ilpFileHandle = null;
             throw err;
         }
     }
@@ -377,19 +335,18 @@ <h3>Frequently Asked Questions</h3>
     const ILP_BUTTON_LABEL = 'Export ilastik Project (.ilp)';
 
     async function saveIlpProject() {
-        if (state.images.length === 0) return;
+        if (q.getImageInfo().length === 0) return;
         const btn = document.getElementById('btnExportIlp');
         btn.disabled = true;
         try {
-            const blob = exportIlp(state, { classNames: state.classNames });
+            const blob = q.exportIlp();
             try {
                 await writeIlpBlob(blob);
             } catch (err) {
                 if (err.name === 'AbortError') return; // user cancelled the picker
                 await writeIlpBlob(blob); // handle was likely stale — retry once with a fresh picker
             }
-            state.dirty = false;
-            updateSaveIndicator(state);
+            q.markSaved();
             // Transient confirmation on the button itself — mirrors btnExportAll's
             // existing pattern of repurposing its own label during an operation
             // ('Training…'/'Exporting…'), just for success instead of progress.
@@ -480,8 +437,8 @@ <h3>Frequently Asked Questions</h3>
                         windowSize: `${window.innerWidth}x${window.innerHeight}`,
                         cores: navigator.hardwareConcurrency || 'unknown',
                         memoryGB: navigator.deviceMemory || 'unknown',
-                        appState_imagesLoaded: state.images ? state.images.length : 0,
-                        appState_activeTool: state.toolMode || 'unknown'
+                        appState_imagesLoaded: q.getImageInfo().length,
+                        appState_activeTool: q.tool || 'unknown'
                     };
                 }
 
@@ -527,7 +484,7 @@ <h3>Frequently Asked Questions</h3>
 
         // File input
         document.getElementById('fileInput').onchange = (e) =>
-            addFiles(state, e.target.files).catch(console.error);
+            q.addFiles(e.target.files).catch(console.error);
 
         // Viewport drag-and-drop
         const viewport = document.getElementById('viewport');
@@ -536,55 +493,48 @@ <h3>Frequently Asked Questions</h3>
         viewport.ondrop      = (e) => {
             e.preventDefault();
             viewport.classList.remove('drag-active');
-            addFiles(state, e.dataTransfer.files).catch(console.error);
+            q.addFiles(e.dataTransfer.files).catch(console.error);
         };
 
-        // Sigma
-        document.getElementById('sigmaRange').oninput = async (e) => {
-            state.sigma = parseFloat(e.target.value);
-            document.getElementById('sigmaVal').innerText = state.sigma.toFixed(1);
-            for (const img of state.images) {
-                await img.backend.updateFeatures(img.intensityArray, state.sigma);
-            }
-            scheduleTraining(state);
-        };
+        // Sigma — the control drives q.setSigma; the readout follows the event
+        // so it stays correct no matter what triggers the change.
+        document.getElementById('sigmaRange').oninput = (e) =>
+            q.setSigma(parseFloat(e.target.value)).catch(console.error);
+        q.addEventListener('sigmachanged', (e) => {
+            document.getElementById('sigmaVal').innerText = e.detail.sigma.toFixed(1);
+        });
 
-        // Brush Size
+        // Brush size — slider and [ / ] hotkeys both go through q.setBrushSize
+        // (which clamps); the slider + readout reflect the event.
         const brushRange = document.getElementById('brushSizeRange');
-        const brushVal    = document.getElementById('brushVal');
-        function setBrushSize(size) {
-            const clamped = Math.min(parseInt(brushRange.max, 10), Math.max(parseInt(brushRange.min, 10), size));
-            brushRange.value = clamped;
-            brushVal.innerText = clamped;
-        }
-        brushRange.oninput = () => setBrushSize(parseInt(brushRange.value, 10));
-
-        // Tools Setup (Grab, Paint, Erase)
-        function selectTool(tool) {
-            const btn = document.querySelector(`.tool-btn[data-tool="${tool}"]`);
-            if (!btn) return;
-            document.querySelectorAll('.tool-btn').forEach(b => b.classList.remove('active'));
-            btn.classList.add('active');
-            state.toolMode = tool;
-
-            // Update body class for cursors
-            document.body.classList.remove('mode-grab', 'mode-paint', 'mode-erase');
-            document.body.classList.add(`mode-${state.toolMode}`);
-        }
+        const brushVal   = document.getElementById('brushVal');
+        brushRange.oninput = () => q.setBrushSize(parseInt(brushRange.value, 10));
+        q.addEventListener('brushsizechanged', (e) => {
+            brushRange.value   = e.detail.size;
+            brushVal.innerText = e.detail.size;
+        });
+
+        // Tools (Grab, Paint, Erase) — buttons call q.setTool; the active
+        // highlight follows the toolchanged event (q handles the body cursor class).
         document.querySelectorAll('.tool-btn').forEach(btn => {
-            btn.onclick = () => selectTool(btn.dataset.tool);
+            btn.onclick = () => q.setTool(btn.dataset.tool);
+        });
+        q.addEventListener('toolchanged', (e) => {
+            document.querySelectorAll('.tool-btn').forEach(b =>
+                b.classList.toggle('active', b.dataset.tool === e.detail.tool));
         });
 
         // Setup class selector with stat badges. The forest owns the class count
-        // (rf.numClasses); colors come from the mutable state.labelColors palette,
-        // falling back to neutral gray if fewer colors than classes are defined.
+        // (q.numClasses); colors come from the mutable palette q owns, falling
+        // back to neutral gray if fewer colors than classes are defined.
         // The color swatch is a native <input type="color">, which always emits
-        // #rrggbb hex — state.labelColors entries are expected to stay hex from
-        // this point on so they round-trip through the picker cleanly.
+        // #rrggbb hex — palette entries are expected to stay hex from this point
+        // on so they round-trip through the picker cleanly.
+        const classColors = q.getClassColors();
+        const classNames  = q.getClassNames();
         document.querySelector('.class-selector').innerHTML =
-            Array.from({ length: state.rf.numClasses }, (_, index) => {
-                const color = state.labelColors[index] ?? '#888888';
-                const name = state.classNames[index] ?? `Class ${index + 1}`;
+            Array.from({ length: q.numClasses }, (_, index) => {
+                const color = classColors[index] ?? '#888888';
                 return `
             <div class="class-item ${index === 0 ? 'active' : ''}" data-class="${index}">
                 <input type="color" class="color-box" data-class="${index}" value="${color}" title="Click to change color">
@@ -601,25 +551,22 @@ <h3>Frequently Asked Questions</h3>
         // Fill class names via textContent (not innerHTML above) so persisted, user-
         // supplied names can't inject markup into the class selector.
         document.querySelectorAll('.class-item span[contenteditable]').forEach(span => {
-            span.textContent = state.classNames[parseInt(span.dataset.class, 10)];
+            span.textContent = classNames[parseInt(span.dataset.class, 10)];
         });
 
         // Tint each class's swatch dot with its overlay color, matching the markers
         // drawn over each object of that class.
-        for (let i = 0; i < state.rf.numClasses; i++) {
-            document.getElementById(`dot-class-${i}`)?.style.setProperty('--dot-color', state.labelColors[i] ?? '#888888');
+        for (let i = 0; i < q.numClasses; i++) {
+            document.getElementById(`dot-class-${i}`)?.style.setProperty('--dot-color', classColors[i] ?? '#888888');
         }
 
-        // Class selector interaction
-        function selectClass(index) {
-            const el = document.querySelector(`.class-item[data-class="${index}"]`);
-            if (!el) return;
-            document.querySelectorAll('.class-item').forEach(i => i.classList.remove('active'));
-            el.classList.add('active');
-            state.currentClass = index;
-        }
+        // Class selection — items call q.setClass; the highlight follows the event.
         document.querySelectorAll('.class-item').forEach(el => {
-            el.onclick = () => selectClass(parseInt(el.dataset.class, 10));
+            el.onclick = () => q.setClass(parseInt(el.dataset.class, 10));
+        });
+        q.addEventListener('classchanged', (e) => {
+            document.querySelectorAll('.class-item').forEach(el =>
+                el.classList.toggle('active', parseInt(el.dataset.class, 10) === e.detail.index));
         });
 
         // Swatch dot — toggles that class's on-canvas centroid markers. Cheap: just
@@ -629,45 +576,37 @@ <h3>Frequently Asked Questions</h3>
             dot.onclick = (e) => {
                 e.stopPropagation(); // don't also re-select the class
                 const idx = parseInt(dot.dataset.class, 10);
-                const visible = !state.classMarkersVisible[idx];
-                state.classMarkersVisible[idx] = visible;
-                dot.classList.toggle('hidden', !visible);
-                dot.setAttribute('aria-pressed', String(visible));
-                state.images.forEach(img => renderCentroids(state, img));
+                q.setMarkersVisible(idx, !q.getMarkersVisible()[idx]);
             };
         });
+        q.addEventListener('markersvisibilitychanged', (e) => {
+            const dot = document.getElementById(`dot-class-${e.detail.index}`);
+            dot?.classList.toggle('hidden', !e.detail.visible);
+            dot?.setAttribute('aria-pressed', String(e.detail.visible));
+        });
 
-        // Class rename — persist on blur. Clicking into the name to edit shouldn't
-        // interfere with class selection (the item's onclick just marks it active).
-        // An empty/whitespace name falls back to the default so we never render a
-        // blank label or persist "".
+        // Class rename — persist on blur through q.setClassName, which trims,
+        // falls back to the default for empty/whitespace names (so we never
+        // render a blank label or persist ""), and saves the settings. The span
+        // is rewritten with whatever name was actually stored.
         document.querySelectorAll('.class-item span[contenteditable]').forEach(span => {
             span.onblur = () => {
                 const idx = parseInt(span.dataset.class, 10);
-                const name = span.textContent.trim();
-                state.classNames[idx] = name || `Class ${idx + 1}`;
-                span.textContent = state.classNames[idx];
-                saveSettings(state);
+                span.textContent = q.setClassName(idx, span.textContent);
             };
         });
 
         // Class color pickers — recolor live as the user drags in the native
         // picker (oninput, not change), mirroring how the contrast slider drives
-        // setWindow on every tick; setColors is just as cheap (uniform write + repaint).
+        // setWindow on every tick; q.setClassColor is just as cheap per image
+        // (uniform write + repaint, no recompile). The dot tint follows the event.
         document.querySelectorAll('.color-box').forEach(input => {
             input.onclick = (e) => e.stopPropagation(); // don't also re-select the class
-            input.oninput = (e) => {
-                const idx = parseInt(input.dataset.class, 10);
-                state.labelColors[idx] = e.target.value;
-                document.getElementById(`dot-class-${idx}`)?.style.setProperty('--dot-color', e.target.value);
-                state.images.forEach(img => {
-                    img.backend.setColors(state.labelColors);
-                    redrawLabels(state, img);
-                    // Repaint cached centroid markers so they recolor live too.
-                    renderCentroids(state, img);
-                });
-                saveSettings(state);
-            };
+            input.oninput = (e) => q.setClassColor(parseInt(input.dataset.class, 10), e.target.value);
+        });
+        q.addEventListener('classcolorchanged', (e) => {
+            document.getElementById(`dot-class-${e.detail.index}`)
+                ?.style.setProperty('--dot-color', e.detail.color);
         });
 
         // Hotkeys (see cheatsheet): [ / ] resize brush, 1-9 select class, P/E/G switch tool.
@@ -678,29 +617,20 @@ <h3>Frequently Asked Questions</h3>
             if (e.ctrlKey || e.metaKey || e.altKey) return;
 
             if (e.key === '[') {
-                setBrushSize(parseInt(brushRange.value, 10) - 1);
+                q.setBrushSize(q.brushSize - 1);
             } else if (e.key === ']') {
-                setBrushSize(parseInt(brushRange.value, 10) + 1);
+                q.setBrushSize(q.brushSize + 1);
             } else if (e.key === 'p' || e.key === 'P' || e.key === 'b' || e.key === 'B') {
-                selectTool('paint');
+                q.setTool('paint');
             } else if (e.key === 'e' || e.key === 'E') {
-                selectTool('erase');
+                q.setTool('erase');
             } else if (e.key === 'g' || e.key === 'G') {
-                selectTool('grab');
+                q.setTool('grab');
             } else if (e.key >= '1' && e.key <= '9') {
-                selectClass(parseInt(e.key, 10) - 1);
+                q.setClass(parseInt(e.key, 10) - 1);
             }
         });
 
-        // Class name edits — persist into state.classNames on blur, mirroring
-        // how the color pickers persist into state.labelColors, so exports
-        // (e.g. exportIlp) can read live names straight off state.
-        document.querySelectorAll('.class-item span[contenteditable]').forEach((span, idx) => {
-            span.onblur = () => {
-                state.classNames[idx] = span.textContent.trim() || `Class ${idx + 1}`;
-            };
-        });
-
         // Export
         const btnExport = document.getElementById('btnExportAll');
         btnExport.onclick = async () => {
@@ -716,12 +646,11 @@ <h3>Frequently Asked Questions</h3>
             btnExport.innerText = 'Training…';
             try {
                 btnExport.innerText = 'Exporting…';
-                const zipBlob = await zipImages(
-                    state.images,
-                    exportSeg,
-                    exportProb,
-                    (metadata) => btnExport.innerText = metadata.percent.toFixed(2) + "%",
-                );
+                const zipBlob = await q.exportZip({
+                    seg: exportSeg,
+                    prob: exportProb,
+                    onProgress: (metadata) => btnExport.innerText = metadata.percent.toFixed(2) + "%",
+                });
 
                 if (!zipBlob) throw Error('zip is empty, nothing to export')
 
@@ -737,9 +666,9 @@ <h3>Frequently Asked Questions</h3>
             }
         };
 
-        // Export .ilp — same entry point as Ctrl+S (see saveIlpProject above),
-        // reading class names from state.classNames (kept in sync with the
-        // class selector's contenteditable spans, see above).
+        // Export .ilp — same entry point as Ctrl+S (see saveIlpProject above).
+        // q.exportIlp reads live class names off the app core (kept in sync with
+        // the class selector's contenteditable spans via q.setClassName, see above).
         document.getElementById('btnExportIlp').onclick = () => saveIlpProject();
     }
 
diff --git a/js/config.js b/js/config.js
index 9089c19..22da0f6 100644
--- a/js/config.js
+++ b/js/config.js
@@ -32,6 +32,26 @@ export const RF_CONFIG = { numTrees: 8, maxDepth: 8, numClasses: NUM_CLASSES };
 // Random Forest's feature stride is keyed off this value.
 export const NUM_FEATURES = 8;
 export const MIN_LABELS_TO_TRAIN = 5;
+
+// Brush radius bounds (in image pixels) shared by the brush control and the
+// [ / ] hotkeys. The paint handlers read the current size off state.brushSize;
+// these constants are the single source of truth for its valid range.
+export const BRUSH_SIZE_MIN = 1;
+export const BRUSH_SIZE_MAX = 32;
+export const BRUSH_SIZE_DEFAULT = 5;
+
+/**
+ * Clamps a requested brush size into [BRUSH_SIZE_MIN, BRUSH_SIZE_MAX], coercing
+ * non-numeric input to the default. Pure — shared by Quantosaurus.setBrushSize
+ * and any UI control that needs to sanitize user input before applying it.
+ * @param {*} size - Requested brush size (any type; coerced via Number()).
+ * @returns {number} An integer size within the valid range.
+ */
+export function clampBrushSize(size) {
+    const n = Math.round(Number(size));
+    if (!Number.isFinite(n)) return BRUSH_SIZE_DEFAULT;
+    return Math.min(BRUSH_SIZE_MAX, Math.max(BRUSH_SIZE_MIN, n));
+}
 export const CAMERA_ZOOM_MIN = 0.1;
 export const CAMERA_ZOOM_MAX = 32;
 export const CAMERA_ZOOM_SENSITIVITY = 0.01;
diff --git a/js/config.test.mjs b/js/config.test.mjs
index 18d0227..55a2a36 100644
--- a/js/config.test.mjs
+++ b/js/config.test.mjs
@@ -1,6 +1,9 @@
-// Tests for the pure config constants in config.js.
+// Tests for the pure config constants and helpers in config.js.
 // Dependency-free — run with: node js/config.test.mjs
-import { NUM_CLASSES, DEFAULT_LABEL_COLORS, RF_CONFIG } from './config.js';
+import {
+    NUM_CLASSES, DEFAULT_LABEL_COLORS, RF_CONFIG,
+    BRUSH_SIZE_MIN, BRUSH_SIZE_MAX, BRUSH_SIZE_DEFAULT, clampBrushSize,
+} from './config.js';
 
 let failures = 0;
 function assert(cond, msg) {
@@ -32,5 +35,33 @@ function assert(cond, msg) {
     );
 }
 
+// ---- Test 4: brush-size bounds are a sane, ordered range containing the default ----
+{
+    assert(
+        BRUSH_SIZE_MIN <= BRUSH_SIZE_DEFAULT && BRUSH_SIZE_DEFAULT <= BRUSH_SIZE_MAX,
+        `BRUSH_SIZE_DEFAULT within [min, max] (${BRUSH_SIZE_MIN} <= ${BRUSH_SIZE_DEFAULT} <= ${BRUSH_SIZE_MAX})`
+    );
+}
+
+// ---- Test 5: clampBrushSize clamps, rounds, and rejects garbage ----
+{
+    assert(clampBrushSize(BRUSH_SIZE_DEFAULT) === BRUSH_SIZE_DEFAULT,
+        `in-range size passes through (got ${clampBrushSize(BRUSH_SIZE_DEFAULT)})`);
+    assert(clampBrushSize(0) === BRUSH_SIZE_MIN,
+        `below-min clamps to BRUSH_SIZE_MIN (got ${clampBrushSize(0)})`);
+    assert(clampBrushSize(-5) === BRUSH_SIZE_MIN,
+        `negative clamps to BRUSH_SIZE_MIN (got ${clampBrushSize(-5)})`);
+    assert(clampBrushSize(BRUSH_SIZE_MAX + 100) === BRUSH_SIZE_MAX,
+        `above-max clamps to BRUSH_SIZE_MAX (got ${clampBrushSize(BRUSH_SIZE_MAX + 100)})`);
+    assert(clampBrushSize(4.6) === 5,
+        `fractional sizes round to the nearest integer (got ${clampBrushSize(4.6)})`);
+    assert(clampBrushSize('12') === 12,
+        `numeric strings coerce (got ${clampBrushSize('12')})`);
+    assert(clampBrushSize('garbage') === BRUSH_SIZE_DEFAULT,
+        `non-numeric input falls back to the default (got ${clampBrushSize('garbage')})`);
+    assert(clampBrushSize(NaN) === BRUSH_SIZE_DEFAULT,
+        `NaN falls back to the default (got ${clampBrushSize(NaN)})`);
+}
+
 console.log(failures === 0 ? '\nALL TESTS PASSED' : `\n${failures} FAILURES`);
 process.exit(failures === 0 ? 0 : 1);
diff --git a/js/images.js b/js/images.js
index 1e2c8e9..ce49286 100644
--- a/js/images.js
+++ b/js/images.js
@@ -2,10 +2,25 @@ import { RF_CONFIG, CENTROID_OVERLAY } from './config.js';
 import { WebGpuBackend } from './backends/webgpu.js';
 import { WebGl2Backend } from './backends/webgl2.js';
 import { loadFileIntoArray } from './io.js';
-import { createImageRow, syncUI, updateSaveIndicator } from './ui.js';
-import { openContrastPopover } from './contrast.js';
 import { scheduleTraining } from './training.js';
 
+// Dispatches a CustomEvent on the owning Quantosaurus instance (state.events).
+// Optional-chained so state objects without a dispatch target (unit tests,
+// plain-object fixtures) keep working — events are strictly additive here.
+function emit(state, name, detail) {
+    state.events?.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
+// Flips the dirty flag, emitting dirtychange only on the false->true
+// transition — paint() is the hottest path in the app (fires on every
+// mousemove while dragging), and dirty stays true for the rest of a typical
+// painting session.
+function markDirty(state) {
+    if (state.dirty) return;
+    state.dirty = true;
+    emit(state, 'dirtychange', { dirty: true });
+}
+
 
 /**
  * Creates a compute/render backend for one image canvas, preferring WebGPU and
@@ -63,38 +78,33 @@ export async function addFiles(state, files) {
 }
 
 /**
- * Loads a single image file, builds its sidebar row and canvas tile, spins up a
- * backend, computes initial features, and registers the paint handlers. Bails
- * out (cleaning up the partial DOM) on load failure or non-2D images.
+ * Loads a single image file, builds its canvas tile, spins up a backend,
+ * computes initial features, and registers the paint handlers. Emits
+ * imageloadstart at the top, then either imageadded on success or
+ * imageloaderror (cleaning up any partial DOM) on load failure, non-2D
+ * images, or backend-init failure — chrome tracks load progress off these.
  * @param {Object} state - Shared app state; the new image is pushed to state.images.
  * @param {File} file - The image file to load.
  */
 export async function addImage(state, file) {
     const imgId = crypto.randomUUID();
-    const row   = createImageRow(imgId, file.name, {
-        onReorder: (dir)      => reorderImage(state, imgId, dir),
-        onDelete:  ()         => deleteImage(state, imgId),
-        onContrast: (anchor)  => openContrastPopover(state, imgId, anchor),
-    });
-    row.classList.add('loading');
-    document.getElementById('img-empty').style.display = 'none';
-    document.getElementById('image-list').appendChild(row);
+    emit(state, 'imageloadstart', { id: imgId, name: file.name });
 
     let loaded;
     try {
         loaded = await loadFileIntoArray(file);
     } catch (err) {
         console.error(err);
-        alert(`Failed to load ${file.name}: ${err.message}`);
-        row.remove();
-        syncUI(state);
+        emit(state, 'imageloaderror', {
+            id: imgId, name: file.name, reason: 'load-failed',
+            message: `Failed to load ${file.name}: ${err.message}`,
+        });
         return;
     }
 
     if (loaded.shape.length > 2) {
       console.warn(`Only 2D images are currently supported. ${file.name} has shape (${loaded.shape})`);
-      row.remove();
-      syncUI(state);
+      emit(state, 'imageloaderror', { id: imgId, name: file.name, reason: 'unsupported-dimensions' });
       return;
     }
 
@@ -128,17 +138,16 @@ export async function addImage(state, file) {
     container.appendChild(labelCanvas);
     container.appendChild(overlayCanvas);
     container.appendChild(tileLabel);
-    document.getElementById('canvas-board').appendChild(container);
+    state.board.appendChild(container);
 
     let backend = null;
-  
+
     try {
         backend = await initializeBackend(gpuCanvas, state.labelColors)
     } catch (err) {
         console.error(err);
         container.remove();
-        row.remove();
-        syncUI(state);
+        emit(state, 'imageloaderror', { id: imgId, name: file.name, reason: 'no-backend' });
         return;
     }
     await backend.allocateImage(w, h, intensityArray, range);
@@ -160,10 +169,9 @@ export async function addImage(state, file) {
         labels: [],
         gpuCanvas, labelCanvas, overlayCanvas, container,
         _cachedRect: null,
-        _sidebarRow: row,
     };
     state.images.push(imgState);
-    state.dirty = true;
+    markDirty(state);
 
     // Pointer events unify mouse/touch/pen. Only the primary pointer paints
     // (the first touch contact, or the mouse) — a second simultaneous touch is
@@ -175,16 +183,14 @@ export async function addImage(state, file) {
         imgState._cachedRect = labelCanvas.getBoundingClientRect();
         state.isDrawing    = true;
         state.activeImageId = imgId;
-        const radius = parseInt(document.getElementById('brushSizeRange').value, 10);
-        paint(state, imgState, e, radius);
+        paint(state, imgState, e, state.brushSize);
     });
     labelCanvas.addEventListener('pointermove', (e) => {
         if (!e.isPrimary) return;
         if (state.isSpaceDown) return;
         if (state.activePointerCount > 1) return; // a second finger joined — pause the stroke
         if (state.isDrawing && state.activeImageId === imgId && state.toolMode !== 'grab') {
-            const radius = parseInt(document.getElementById('brushSizeRange').value, 10);
-            paint(state, imgState, e, radius);
+            paint(state, imgState, e, state.brushSize);
         }
     });
     function endStroke(e) {
@@ -192,6 +198,11 @@ export async function addImage(state, file) {
         if (state.activeImageId === imgId) {
             state.isDrawing    = false;
             state.activeImageId = null;
+            emit(state, 'labelschanged', {
+                id: imgId,
+                labelCount: imgState.labels.length,
+                totalLabels: state.images.reduce((s, i) => s + i.labels.length, 0),
+            });
             scheduleTraining(state);
         }
     }
@@ -201,14 +212,16 @@ export async function addImage(state, file) {
     const ro = new ResizeObserver(() => { imgState._cachedRect = null; });
     ro.observe(labelCanvas);
 
-    row.classList.remove('loading');
-
-    syncUI(state);
+    emit(state, 'imageadded', {
+        id: imgId, name: file.name, width: w, height: h,
+        index: state.images.length - 1,
+    });
 }
 
 /**
- * Moves an image one slot up or down, keeping state.images, the canvas tiles,
- * and the sidebar rows in the same visual order (which is also export order).
+ * Moves an image one slot up or down, keeping state.images and the canvas
+ * tiles in the same visual order (which is also export order). Emits
+ * imagereordered so chrome tracking image order can follow.
  * @param {Object} state - Shared app state.
  * @param {string} imgId - Id of the image to move.
  * @param {-1|1} direction - -1 to move up, +1 to move down.
@@ -221,22 +234,15 @@ export function reorderImage(state, imgId, direction) {
 
     [state.images[idx], state.images[newIdx]] =
     [state.images[newIdx], state.images[idx]];
-    state.dirty = true; // changes export lane order
-    updateSaveIndicator(state);
+    markDirty(state); // changes export lane order
 
-    const board = document.getElementById('canvas-board');
-    const tiles = [...board.children];
+    const tiles = [...state.board.children];
     const a = tiles[idx];
     const b = tiles[newIdx];
-    if (direction === -1) board.insertBefore(a, b);
-    else                  board.insertBefore(b, a);
-
-    const list = document.getElementById('image-list');
-    const rows = [...list.children];
-    const ra = rows[idx];
-    const rb = rows[newIdx];
-    if (direction === -1) list.insertBefore(ra, rb);
-    else                  list.insertBefore(rb, ra);
+    if (direction === -1) state.board.insertBefore(a, b);
+    else                  state.board.insertBefore(b, a);
+
+    emit(state, 'imagereordered', { id: imgId, fromIndex: idx, toIndex: newIdx });
 }
 
 /**
@@ -262,13 +268,19 @@ export function deleteImage(state, imgId) {
 
     imgState.backend.destroy();
     imgState.container.remove();
-    imgState._sidebarRow.remove();
     state.images.splice(idx, 1);
-    state.dirty = true;
+    markDirty(state);
 
-    if (labelCount > 0) scheduleTraining(state);
+    emit(state, 'imageremoved', { id: imgId, index: idx });
 
-    syncUI(state);
+    if (labelCount > 0) {
+        emit(state, 'labelschanged', {
+            id: imgId,
+            labelCount: 0,
+            totalLabels: state.images.reduce((s, i) => s + i.labels.length, 0),
+        });
+        scheduleTraining(state);
+    }
 }
 
 /**
@@ -405,10 +417,7 @@ export function paint(state, imgState, e, radius) {
 
     const pixels = getPixelsInRadius(x, y, radius, imgState.width, imgState.height);
     if (pixels.length === 0) return;
-    // Only touch the DOM on the false->true transition — paint() is the
-    // hottest path in the app (fires on every mousemove while dragging), and
-    // dirty stays true for the rest of a typical painting session.
-    if (!state.dirty) { state.dirty = true; updateSaveIndicator(state); }
+    markDirty(state);
 
     const pixelSet = new Set(pixels.map(p => `${p.x},${p.y}`));
     imgState.labels = imgState.labels.filter(lbl => !pixelSet.has(`${lbl.x},${lbl.y}`));
diff --git a/js/quantosaurus.js b/js/quantosaurus.js
new file mode 100644
index 0000000..affc0ff
--- /dev/null
+++ b/js/quantosaurus.js
@@ -0,0 +1,362 @@
+// The embeddable app core: one Quantosaurus instance owns the shared `state`
+// object (images, forest, tools, camera) and a pan/zoom board element, and is
+// itself an EventTarget — every state change the app makes flows out as a
+// CustomEvent (see the event catalog below), so any chrome (the built-in
+// taskbar, or a host page embedding the board in a notebook) can subscribe
+// instead of being hard-wired in.
+//
+// This class and the GPU backends are the deliberate exceptions to the
+// "functions take state explicitly" convention (see CLAUDE.md): the modules it
+// orchestrates (images.js, training.js, camera.js, contrast.js, settings.js,
+// export.js) keep their fn(state, ...) signatures and know nothing about the
+// class beyond the optional `state.events` dispatch target.
+//
+// Event catalog (all CustomEvents on the instance; payload in event.detail):
+//   imageloadstart          { id, name }
+//   imageadded              { id, name, width, height, index }
+//   imageloaderror          { id, name, reason, message? }   reason: 'load-failed' | 'unsupported-dimensions' | 'no-backend'
+//   imageremoved            { id, index }
+//   imagereordered          { id, fromIndex, toIndex }
+//   labelschanged           { id, labelCount, totalLabels }
+//   dirtychange             { dirty }
+//   toolchanged             { tool }
+//   brushsizechanged        { size }
+//   sigmachanged            { sigma }
+//   classchanged            { index }
+//   classcolorchanged       { index, color }
+//   classnamechanged        { index, name }
+//   markersvisibilitychanged{ index, visible }
+//   trainingstart           { }
+//   trainingcomplete        { trained }
+//   statscomputed           { counts, perImage, animate, reason? }
+
+import { DEFAULT_LABEL_COLORS, RF_CONFIG, BRUSH_SIZE_DEFAULT, clampBrushSize } from './config.js';
+import { FlatRandomForest } from './rf.js';
+import { addFiles, reorderImage, deleteImage, redrawLabels, renderCentroids } from './images.js';
+import { scheduleTraining } from './training.js';
+import { setupCamera } from './camera.js';
+import { openContrastPopover, closeContrastPopover } from './contrast.js';
+import { loadSettings, saveSettings } from './settings.js';
+import { zipImages, exportIlp } from './export.js';
+
+const TOOLS = ['grab', 'paint', 'erase'];
+
+export class Quantosaurus extends EventTarget {
+    /**
+     * Attaches a new app instance to a board element. The board is the
+     * pan/zoom transform target that image tiles are appended to; the viewport
+     * is the clipping element that receives wheel/pointer gestures (camera.js).
+     * @param {HTMLElement} boardEl - Element the image tiles live in (transformed by the camera).
+     * @param {{viewportEl?: HTMLElement}} [options] - Viewport element; defaults to the board's parent.
+     */
+    constructor(boardEl, { viewportEl = boardEl.parentElement } = {}) {
+        super();
+
+        /**
+         * The shared mutable app state threaded through every module. Exposed
+         * so existing fn(state, ...) modules and chrome can keep working with
+         * it directly; embedders should prefer the methods/events on this class.
+         */
+        this.state = {
+            // Images — ordered array; visual order == export order
+            images: [],
+
+            // ML
+            rf: new FlatRandomForest(RF_CONFIG),
+
+            // Presentation — per-class overlay colors, indexed by class. Owned by the
+            // UI (mutable), seeded from config defaults. The class *count* comes from
+            // rf.numClasses; colors are a separate concern that can change at runtime.
+            labelColors: [...DEFAULT_LABEL_COLORS],
+
+            // Per-class display names, indexed by class. Like labelColors, this is a
+            // UI-owned presentation concern (renamable at runtime, persisted to
+            // localStorage); the class *count* still comes from rf.numClasses.
+            classNames: Array.from({ length: RF_CONFIG.numClasses }, (_, i) => `Class ${i + 1}`),
+
+            // Whether each class's centroid markers are drawn on canvas. Session-only —
+            // like camera/labels, not persisted.
+            classMarkersVisible: new Array(RF_CONFIG.numClasses).fill(true),
+
+            // Drawing / Tools
+            currentClass: 0,
+            isDrawing: false,
+            activeImageId: null,
+            toolMode: 'grab', // 'grab', 'paint', 'erase'
+            brushSize: BRUSH_SIZE_DEFAULT,
+
+            // Features
+            sigma: 1.0,
+
+            // Camera
+            camera: { x: 0, y: 0, scale: 1 },
+            isSpaceDown: false,
+            isPanning: false,
+            activePointerCount: 0,
+
+            // True while a debounced retrain+inference is running.
+            isTraining: false,
+
+            // Whether there are changes since the last successful save (set on
+            // image/label mutations in images.js, cleared by markSaved()).
+            dirty: false,
+
+            // Last per-class object counts from the stats pass (see statscomputed).
+            lastCounts: new Array(RF_CONFIG.numClasses).fill(0),
+
+            // DOM the instance owns / dispatch target for module-emitted events.
+            board: boardEl,
+            viewport: viewportEl,
+            events: this,
+        };
+
+        loadSettings(this.state); // restore persisted colors/names before any chrome renders
+        if (viewportEl) setupCamera(this.state, viewportEl, boardEl);
+    }
+
+    /** @returns {'grab'|'paint'|'erase'} The active tool. */
+    get tool() { return this.state.toolMode; }
+
+    /** @returns {number} The active brush radius in image pixels. */
+    get brushSize() { return this.state.brushSize; }
+
+    /** @returns {number} The active class index. */
+    get currentClass() { return this.state.currentClass; }
+
+    /** @returns {number} The current feature scale (sigma). */
+    get sigma() { return this.state.sigma; }
+
+    /** @returns {boolean} Whether there are unsaved changes. */
+    get dirty() { return this.state.dirty; }
+
+    /** @returns {number} How many classes exist (fixed — see NUM_CLASSES in config.js). */
+    get numClasses() { return this.state.rf.numClasses; }
+
+    /** Dispatches a CustomEvent on this instance. @param {string} name @param {Object} [detail] */
+    _emit(name, detail = {}) {
+        this.dispatchEvent(new CustomEvent(name, { detail }));
+    }
+
+    // ---------------------------------------------------------------- images
+
+    /**
+     * Imports a batch of files onto the board, skipping unsupported types and
+     * duplicates. Emits imageloadstart/imageadded/imageloaderror per file.
+     * @param {Iterable<File>} files
+     */
+    async addFiles(files) {
+        await addFiles(this.state, files);
+    }
+
+    /**
+     * Moves an image one slot up or down in board/export order.
+     * @param {string} imgId @param {-1|1} direction
+     */
+    reorderImage(imgId, direction) {
+        reorderImage(this.state, imgId, direction);
+    }
+
+    /**
+     * Removes an image and frees its GPU resources (confirms first if it
+     * carries labels). Emits imageremoved.
+     * @param {string} imgId
+     */
+    deleteImage(imgId) {
+        deleteImage(this.state, imgId);
+    }
+
+    /**
+     * Lightweight descriptors of the loaded images, in board/export order.
+     * @returns {Array<{id: string, name: string, width: number, height: number, labelCount: number}>}
+     */
+    getImageInfo() {
+        return this.state.images.map(({ id, name, width, height, labels }) =>
+            ({ id, name, width, height, labelCount: labels.length }));
+    }
+
+    // ----------------------------------------------------------------- tools
+
+    /**
+     * Switches the active tool and updates the body cursor class.
+     * @param {'grab'|'paint'|'erase'} tool
+     */
+    setTool(tool) {
+        if (!TOOLS.includes(tool) || tool === this.state.toolMode) return;
+        this.state.toolMode = tool;
+        document.body.classList.remove(...TOOLS.map(t => `mode-${t}`));
+        document.body.classList.add(`mode-${tool}`);
+        this._emit('toolchanged', { tool });
+    }
+
+    /**
+     * Sets the brush radius, clamped to the valid range (see config.js).
+     * @param {number} size
+     */
+    setBrushSize(size) {
+        const clamped = clampBrushSize(size);
+        if (clamped === this.state.brushSize) return;
+        this.state.brushSize = clamped;
+        this._emit('brushsizechanged', { size: clamped });
+    }
+
+    /**
+     * Selects the class that painting assigns.
+     * @param {number} index
+     */
+    setClass(index) {
+        if (!Number.isInteger(index) || index < 0 || index >= this.numClasses) return;
+        if (index === this.state.currentClass) return;
+        this.state.currentClass = index;
+        this._emit('classchanged', { index });
+    }
+
+    /**
+     * Sets the feature scale, recomputes every image's filter bank at the new
+     * sigma, and schedules a retrain. Resolves once features are updated.
+     * @param {number} sigma
+     */
+    async setSigma(sigma) {
+        this.state.sigma = sigma;
+        this._emit('sigmachanged', { sigma });
+        for (const img of this.state.images) {
+            await img.backend.updateFeatures(img.intensityArray, sigma);
+        }
+        scheduleTraining(this.state);
+    }
+
+    // --------------------------------------------------- class presentation
+
+    /**
+     * Recolors a class's overlay everywhere (composite, painted labels,
+     * centroid markers) and persists the palette.
+     * @param {number} index @param {string} color - #rrggbb hex.
+     */
+    setClassColor(index, color) {
+        if (index < 0 || index >= this.numClasses) return;
+        this.state.labelColors[index] = color;
+        this.state.images.forEach(img => {
+            img.backend.setColors(this.state.labelColors);
+            redrawLabels(this.state, img);
+            renderCentroids(this.state, img);
+        });
+        saveSettings(this.state);
+        this._emit('classcolorchanged', { index, color });
+    }
+
+    /**
+     * Renames a class and persists the name. Empty/whitespace names fall back
+     * to the default so a blank label is never rendered or persisted.
+     * @param {number} index @param {string} name
+     * @returns {string|undefined} The normalized name actually stored.
+     */
+    setClassName(index, name) {
+        if (index < 0 || index >= this.numClasses) return undefined;
+        const normalized = String(name ?? '').trim() || `Class ${index + 1}`;
+        this.state.classNames[index] = normalized;
+        saveSettings(this.state);
+        this._emit('classnamechanged', { index, name: normalized });
+        return normalized;
+    }
+
+    /**
+     * Shows/hides a class's on-canvas centroid markers. Cheap: repaints the 2D
+     * overlay from cached objects, no GPU or stats work.
+     * @param {number} index @param {boolean} visible
+     */
+    setMarkersVisible(index, visible) {
+        if (index < 0 || index >= this.numClasses) return;
+        this.state.classMarkersVisible[index] = !!visible;
+        this.state.images.forEach(img => renderCentroids(this.state, img));
+        this._emit('markersvisibilitychanged', { index, visible: !!visible });
+    }
+
+    /** @returns {string[]} A copy of the per-class overlay colors. */
+    getClassColors() { return [...this.state.labelColors]; }
+
+    /** @returns {string[]} A copy of the per-class display names. */
+    getClassNames() { return [...this.state.classNames]; }
+
+    /** @returns {boolean[]} A copy of the per-class marker-visibility flags. */
+    getMarkersVisible() { return [...this.state.classMarkersVisible]; }
+
+    // -------------------------------------------------------------- contrast
+
+    /**
+     * Opens (or toggles shut) the per-image contrast popover anchored beside
+     * the given element.
+     * @param {string} imgId @param {HTMLElement} anchorEl
+     */
+    openContrast(imgId, anchorEl) {
+        openContrastPopover(this.state, imgId, anchorEl);
+    }
+
+    /** Closes the contrast popover, if open. */
+    closeContrast() {
+        closeContrastPopover();
+    }
+
+    // --------------------------------------------------------------- results
+
+    /**
+     * The most recent per-class object counts (summed across images), as last
+     * reported by a statscomputed event.
+     * @returns {number[]}
+     */
+    getCounts() { return [...this.state.lastCounts]; }
+
+    /**
+     * The most recent detected objects per image, grouped by class — each
+     * object carries its centroid (image-pixel coords) and area.
+     * @returns {Array<{id: string, objectsByClass: Array<Array<{cx: number, cy: number, area: number}>>}>}
+     */
+    getObjects() {
+        return this.state.images
+            .filter(img => img._centroids)
+            .map(img => ({ id: img.id, objectsByClass: img._centroids }));
+    }
+
+    // --------------------------------------------------------- export / save
+
+    /**
+     * Builds a zip of segmentation masks and/or probability maps for every
+     * loaded image (see export.js).
+     * @param {{seg?: boolean, prob?: boolean, onProgress?: (metadata: Object) => void}} [options]
+     * @returns {Promise<Blob|undefined>} The zip blob (undefined when there is nothing to export).
+     */
+    async exportZip({ seg = true, prob = false, onProgress } = {}) {
+        return zipImages(this.state.images, seg, prob, onProgress);
+    }
+
+    /**
+     * Builds a self-contained ilastik .ilp project blob (images + labels
+     * embedded). Persisting it (file pickers, downloads) is the caller's job —
+     * call markSaved() after a successful write.
+     * @param {{classNames?: string[]}} [options]
+     * @returns {Blob}
+     */
+    exportIlp(options = {}) {
+        return exportIlp(this.state, { classNames: this.state.classNames, ...options });
+    }
+
+    /** Clears the dirty flag after a successful save and emits dirtychange. */
+    markSaved() {
+        if (!this.state.dirty) return;
+        this.state.dirty = false;
+        this._emit('dirtychange', { dirty: false });
+    }
+
+    // --------------------------------------------------------------- cleanup
+
+    /**
+     * Frees every image's GPU resources and removes their tiles from the
+     * board. The instance should not be used afterward.
+     */
+    destroy() {
+        closeContrastPopover();
+        for (const img of this.state.images) {
+            img.backend.destroy();
+            img.container.remove();
+        }
+        this.state.images.length = 0;
+    }
+}
diff --git a/js/training.js b/js/training.js
index 247621e..e746b04 100644
--- a/js/training.js
+++ b/js/training.js
@@ -1,7 +1,13 @@
 import { MIN_LABELS_TO_TRAIN, NUM_FEATURES, RF_CONFIG, TRAIN_DEBOUNCE_MS, STATS_LAYOUT } from './config.js';
-import { updateClassStatBadges, animateClassStatBadges, setClassBadgesLoading, setTrainingIndicator } from './ui.js';
 import { setCentroids, renderCentroids, clearCentroids } from './images.js';
 
+// Dispatches a CustomEvent on the owning Quantosaurus instance (state.events).
+// Optional-chained so state objects without a dispatch target (unit tests,
+// plain-object fixtures) keep working.
+function emit(state, name, detail) {
+    state.events?.dispatchEvent(new CustomEvent(name, { detail }));
+}
+
 // Fields per object in the dense stats struct backends return from downloadStats
 // (see STATS_LAYOUT): label, area, total_intensity {lo,hi}, sum_x {lo,hi},
 // sum_y {lo,hi}, min_intensity, max_intensity.
@@ -83,25 +89,27 @@ export function scheduleTraining(state) {
 
 /**
  * Retrains the forest on all current labels, then runs inference on every image
- * and refreshes the per-class object counts. No-ops (and zeroes the badges) if
- * there are fewer than MIN_LABELS_TO_TRAIN labels total.
+ * and refreshes the per-class object counts. No-ops (emitting zeroed stats) if
+ * there are fewer than MIN_LABELS_TO_TRAIN labels total. Emits trainingstart /
+ * trainingcomplete around the run so chrome can show progress affordances.
  * @param {Object} state - Shared app state; reads state.images and mutates state.rf.
  */
 export async function trainAndPredictAll(state) {
     const totalLabels = state.images.reduce((s, i) => s + i.labels.length, 0);
     if (totalLabels < MIN_LABELS_TO_TRAIN) {
-        updateClassStatBadges(new Array(RF_CONFIG.numClasses).fill(0));
+        const zeros = new Array(RF_CONFIG.numClasses).fill(0);
+        state.lastCounts = zeros;
         state.images.forEach(clearCentroids);
+        emit(state, 'statscomputed', {
+            counts: zeros, perImage: [], animate: false, reason: 'insufficient-labels',
+        });
         return;
     }
 
-    // Give immediate feedback for the otherwise-silent await: a progress cursor +
-    // "Training…" status while the overlay recomputes, and the count badges wiped to
-    // a pulsing placeholder so the stale numbers don't just sit there.
     state.isTraining = true;
-    setTrainingIndicator(state, true);
-    setClassBadgesLoading();
+    emit(state, 'trainingstart', {});
 
+    let trained = false;
     try {
         const { combinedX, yArray } = await buildTrainingDataset(state.images, totalLabels);
         state.rf.train(combinedX, yArray, NUM_FEATURES);
@@ -111,21 +119,24 @@ export async function trainAndPredictAll(state) {
         }
 
         await updateObjectCounts(state);
+        trained = true;
     } finally {
         state.isTraining = false;
-        setTrainingIndicator(state, false);
+        emit(state, 'trainingcomplete', { trained });
     }
 }
 
 /**
- * Runs connected-component labeling + stats per class, per image, and pushes the
- * summed object counts into the class-selector badges. Each object is one dense
- * stats struct, so the count is stats.length / STATS_FIELDS_PER_OBJECT.
+ * Runs connected-component labeling + stats per class, per image, caches the
+ * results on state, and emits statscomputed with the summed per-class counts
+ * plus each image's detected objects. Each object is one dense stats struct,
+ * so the count is stats.length / STATS_FIELDS_PER_OBJECT.
  * @param {Object} state - Shared app state.
  */
 async function updateObjectCounts(state) {
     const numClasses = RF_CONFIG.numClasses;
     const counts = new Array(numClasses).fill(0);
+    const perImage = [];
 
     for (const img of state.images) {
         const objectsByClass = Array.from({ length: numClasses }, () => []);
@@ -146,7 +157,9 @@ async function updateObjectCounts(state) {
         // Cache and repaint this image's centroid markers from the freshly detected objects.
         setCentroids(img, objectsByClass);
         renderCentroids(state, img);
+        perImage.push({ id: img.id, objectsByClass });
     }
 
-    animateClassStatBadges(counts);
+    state.lastCounts = counts;
+    emit(state, 'statscomputed', { counts, perImage, animate: true });
 }
diff --git a/js/ui.js b/js/ui.js
index 3b58d87..17f02c2 100644
--- a/js/ui.js
+++ b/js/ui.js
@@ -1,3 +1,79 @@
+/**
+ * Wires the sidebar/top-bar chrome onto a Quantosaurus instance's events: the
+ * per-image sidebar rows (with loading state), the status line, the training
+ * indicator, the save indicator, and the per-class count badges. The chrome is
+ * a pure subscriber — every mutation goes back through methods on `q`, so this
+ * whole layer can be swapped out (or omitted, in an embed) without touching
+ * the app core.
+ * @param {import('./quantosaurus.js').Quantosaurus} q - The app instance.
+ */
+export function bindChrome(q) {
+    const state = q.state;
+    const rows = new Map(); // imgId -> sidebar row element
+
+    q.addEventListener('imageloadstart', (e) => {
+        const { id, name } = e.detail;
+        const row = createImageRow(id, name, {
+            onReorder: (dir)     => q.reorderImage(id, dir),
+            onDelete:  ()        => q.deleteImage(id),
+            onContrast: (anchor) => q.openContrast(id, anchor),
+        });
+        row.classList.add('loading');
+        document.getElementById('img-empty').style.display = 'none';
+        document.getElementById('image-list').appendChild(row);
+        rows.set(id, row);
+    });
+
+    q.addEventListener('imageadded', (e) => {
+        rows.get(e.detail.id)?.classList.remove('loading');
+        syncUI(state);
+    });
+
+    q.addEventListener('imageloaderror', (e) => {
+        const { id, message } = e.detail;
+        rows.get(id)?.remove();
+        rows.delete(id);
+        syncUI(state);
+        if (message) alert(message);
+    });
+
+    q.addEventListener('imageremoved', (e) => {
+        rows.get(e.detail.id)?.remove();
+        rows.delete(e.detail.id);
+        syncUI(state);
+    });
+
+    q.addEventListener('imagereordered', (e) => {
+        const { fromIndex, toIndex } = e.detail;
+        const list = document.getElementById('image-list');
+        const els  = [...list.children];
+        // Mirror the board-tile swap in images.js:reorderImage — the moved row
+        // goes before (moving up) or after (moving down) its neighbor.
+        if (toIndex < fromIndex) list.insertBefore(els[fromIndex], els[toIndex]);
+        else                     list.insertBefore(els[toIndex], els[fromIndex]);
+        updateSaveIndicator(state);
+    });
+
+    q.addEventListener('dirtychange', () => updateSaveIndicator(state));
+
+    q.addEventListener('trainingstart', () => {
+        // Give immediate feedback for the otherwise-silent await: a progress
+        // cursor + "Training…" status while the overlay recomputes, and the
+        // count badges wiped to a pulsing placeholder so the stale numbers
+        // don't just sit there.
+        setTrainingIndicator(state, true);
+        setClassBadgesLoading();
+    });
+
+    q.addEventListener('trainingcomplete', () => setTrainingIndicator(state, false));
+
+    q.addEventListener('statscomputed', (e) => {
+        const { counts, animate } = e.detail;
+        if (animate) animateClassStatBadges(counts);
+        else         updateClassStatBadges(counts);
+    });
+}
+
 /**
  * Refreshes all image-count-driven chrome (status line, export button, empty
  * state) in one call. Invoke after any change to state.images.

From 3bb519a469245d6f1605be2025aed5021ebbf263 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 13 Jul 2026 03:34:50 +0000
Subject: [PATCH 2/2] Replace sidebar with a single floating taskbar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Condense all chrome into one bottom-center floating taskbar (Figma-style) for a
mobile-first, embeddable posture. The taskbar is a pure consumer of the
Quantosaurus class API introduced in the previous commit.

- Remove the sidebar and top bar. Tools, a numeric brush-size input, a class
  dropdown (color + editable name + selection), the sigma slider, and an
  overflow menu (Add images / Export / Cheatsheet / Theme / Feedback) all live
  in the taskbar.
- Per-class object counts move to a floating chip in the upper right, each with
  a marker-visibility toggle dot; the "unsaved changes" indicator moves to a
  chip in the upper left. A load toast covers the gap left by the old per-row
  loading bar.
- Import: drag-and-drop plus a centered empty-state "Select Files" shown only
  when no images are loaded (an "Add images…" overflow item covers the
  non-empty case, notably on touch).
- Export options move into a modal opened from the overflow menu; Cmd/Ctrl+S
  still saves the .ilp.
- Per-image controls (reorder / contrast / delete) move to a hover (always-on
  for coarse pointers) overlay on each board tile; the contrast popover
  re-anchors to the tile button.
- New chrome is fixed-position outside #viewport so taps aren't swallowed by
  its touch-action:none, uses env(safe-area-inset-*) for mobile, and themes via
  the existing surface/border tokens. Added a global [hidden] reset so the
  menus' display rules don't override the attribute.

CLAUDE.md's data-flow section updated for the class + event architecture.
Verified in a headless browser end to end (empty state, load, paint→train→
counts, brush clamp, class dropdown recolor/rename/select, marker toggle,
overflow menu, export modal, tile contrast, theme toggle, delete) with zero
console errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VobFMvLSfYoBDLD1tAANma
---
 CLAUDE.md    |  26 +++-
 index.html   | 345 ++++++++++++++++++++++++++++----------------
 js/images.js |  37 +++++
 js/ui.js     | 157 +++-----------------
 style.css    | 393 +++++++++++++++++++++++++++++++--------------------
 5 files changed, 539 insertions(+), 419 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 442cfff..8e675c6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,20 +44,34 @@ in a browser (see the `run`/`verify` skills for driving a browser check).
 
 ### Data flow
 
-`index.html`'s inline module owns the single shared `state` object (images array, the `FlatRandomForest`
-instance, current tool/class, camera transform) and wires up all top-level DOM event handlers. Every other
-module is a set of functions that take `state` (or a specific image's entry in `state.images`) as an explicit
-argument — there are no classes or singletons for app logic, only for the GPU backends and the `FlatRandomForest`.
+`Quantosaurus` (`js/quantosaurus.js`) is the app core: a class (extending `EventTarget`) that owns the single
+shared `state` object (images array, the `FlatRandomForest` instance, current tool/class, brush size, camera
+transform) and attaches to a board element. It's the deliberate class exception alongside the GPU backends and
+`FlatRandomForest`; every other module is still a set of functions that take `state` (or a specific image's
+entry in `state.images`) as an explicit argument. The class is a thin wrapper: its methods call those module
+functions and then dispatch a `CustomEvent` for the change. All UI is a *subscriber* — nothing reaches into
+the app core's internals. `index.html`'s inline module constructs one instance, wires the taskbar controls to
+its methods, and subscribes to its events; `js/ui.js:bindChrome(q)` subscribes the count badges / save
+indicator / training cursor the same way. This is what makes the board embeddable (e.g. in a notebook): a host
+page can `new Quantosaurus(div)` and `addEventListener` for results without any of the built-in chrome.
+
+**Event catalog** (all `CustomEvent`s on the instance; see the header of `quantosaurus.js` for payload shapes):
+`imageloadstart`/`imageadded`/`imageloaderror`/`imageremoved`/`imagereordered`, `labelschanged`, `dirtychange`,
+`toolchanged`/`brushsizechanged`/`sigmachanged`/`classchanged`, `classcolorchanged`/`classnamechanged`/
+`markersvisibilitychanged`, `trainingstart`/`trainingcomplete`, and `statscomputed` (carries per-class counts +
+per-image detected objects). Modules dispatch through `state.events?.dispatchEvent(...)`, optional-chained so
+the CPU unit tests can import `images.js`/`training.js` under Node without a dispatch target.
 
 Per-image state (`state.images[i]`) carries: the loaded `intensityArray` (raw pixel values, not normalized),
 its GPU `backend` instance, `labels` (sparse `{x, y, cls}` painted by the user), the display `windowLo`/`windowHi`
-contrast bounds, and the DOM nodes for its canvas tile and sidebar row.
+contrast bounds, and the DOM nodes for its canvas tile (the tile carries its own hover controls — reorder /
+contrast / delete; there is no separate sidebar).
 
 The core loop: user paints labels (`images.js:paint`) → `training.js:scheduleTraining` debounces
 (`TRAIN_DEBOUNCE_MS`) → `trainAndPredictAll` gathers per-pixel features for every labeled pixel across all
 images (`backend.gatherFeaturesForTraining`), trains one `FlatRandomForest` shared across all images, then
 reruns `backend.runInference` per image, then recomputes per-class object counts via connected-component
-labeling + stats for the sidebar badges.
+labeling + stats, emitted as `statscomputed` for the count chip.
 
 ### GPU backend interface
 
diff --git a/index.html b/index.html
index c1abcb9..90b0215 100644
--- a/index.html
+++ b/index.html
@@ -10,15 +10,6 @@
 </head>
 <body class="mode-grab">
 
-<div id="top-bar">
-    <h2>🦖 Quantosaurus</h2>
-    <div id="status">No images loaded. Drag &amp; drop onto the canvas.</div>
-    <div style="flex: 1;"></div>
-    <button id="btnCheatsheet" class="btn-subtle">❓&nbsp;&nbsp;Cheatsheet</button>
-    <button id="btnThemeToggle" class="btn-subtle">☀️&nbsp;&nbsp;Light Mode</button>
-    <button id="btnFeedback" class="btn-subtle">💬&nbsp;&nbsp;Feedback</button>
-</div>
-
 <div id="feedbackModal" class="modal-overlay" style="display: none;">
     <div class="modal-content heavy-panel">
         <div class="heavy-panel-header">
@@ -137,98 +128,111 @@ <h3>Frequently Asked Questions</h3>
     </div>
 </div>
 
-<div id="main-container">
-
-    <div id="sidebar">
+<!-- Hidden file input, opened by the empty-state label and the taskbar's
+     "Add images…" action. Drag-and-drop onto the viewport is the primary path. -->
+<input type="file" id="fileInput" accept=".tif,.tiff,.png,.jpg,.jpeg" multiple hidden>
 
-        <div class="sidebar-section" id="section-ingest">
-            <div class="section-header">Images</div>
-            
-            <input type="file" id="fileInput" accept=".tif,.tiff,.png,.jpg,.jpeg"
-                   multiple style="font-size:12px;">
-
-            <div id="img-empty">
-                Drop images onto the canvas<br>or use the file picker above.
-            </div>
+<!-- Export options modal (opened from the taskbar overflow menu). -->
+<div id="exportModal" class="modal-overlay" style="display: none;">
+    <div class="modal-content heavy-panel">
+        <div class="heavy-panel-header">
+            <span class="heavy-panel-title">Export</span>
+            <button id="btnCloseExport" class="img-delete" style="background:none; padding:2px 6px;">✕</button>
+        </div>
 
-            <div id="image-list"></div>
+        <div class="control-group" style="margin-bottom: 12px;">
+            <label style="display:flex; align-items:center; gap:8px; font-size: 13px;">
+                <input type="checkbox" id="chkExportSeg" checked>
+                Segmentations
+            </label>
+            <label style="display:flex; align-items:center; gap:8px; font-size: 13px;">
+                <input type="checkbox" id="chkExportProb">
+                Probabilities
+            </label>
         </div>
 
-        <div class="sidebar-section" id="section-train">
-            <div class="section-header">Train</div>
+        <button id="btnExportAll" class="btn-primary" style="width:100%;" disabled>
+            Export Loaded Images
+        </button>
+        <p class="hint" style="margin: 6px 0 14px 0;">
+            At least 5 labels are needed to train before export.
+        </p>
+
+        <button id="btnExportIlp" class="btn-primary" style="width:100%;" disabled>
+            Export ilastik Project (.ilp)
+        </button>
+        <p class="hint" style="margin-top: 6px;">
+            Fully self-contained — images and labels are embedded in the file. Opens in
+            desktop ilastik, which retrains its own classifier on open. Ctrl/Cmd+S to save.
+        </p>
+    </div>
+</div>
 
-            <div class="control-group">
-                <span class="control-label">Tools</span>
-                <div style="display:flex; gap:10px; align-items:end;">
-                    <div style="display:flex; gap:4px; flex:1;">
-                        <button class="tool-btn active" data-tool="grab" title="Grab (Pan)">🖐</button>
-                        <button class="tool-btn" data-tool="paint" title="Paint">🖌</button>
-                        <button class="tool-btn" data-tool="erase" title="Erase">🧽</button>
-                    </div>
-                </div>
-            </div>
+<div id="viewport">
+    <div id="canvas-board"></div>
 
-            <div class="control-group">
-                <span class="control-label">Brush Size</span>
-                <div style="display:flex; gap:10px; align-items:center;">
-                    <input type="range" id="brushSizeRange" min="1" max="32" step="1" value="5">
-                    <span id="brushVal" style="min-width:30px; font-size:12px;">5</span>
-                </div>
-            </div>
+    <!-- Centered drop target / file picker, shown only when no images are loaded. -->
+    <div id="empty-state">
+        <div class="empty-dino">🦖</div>
+        <div class="empty-title">Drop images to begin</div>
+        <div class="empty-sub">.tif, .png or .jpg — everything runs locally in your browser.</div>
+        <label for="fileInput" class="btn-primary empty-pick">Select Files</label>
+    </div>
+</div>
 
-            <div class="control-group">
-                <span class="control-label">Classes</span>
-                <div class="class-selector"></div>
-            </div>
+<!-- Floating corner chrome (siblings of #viewport, never inside it — the
+     viewport's touch-action:none would otherwise swallow taps). -->
+<div id="dirty-chip" class="save-status" aria-live="polite"></div>
 
-            <div class="control-group">
-                <span class="control-label">Feature Scale (Sigma)</span>
-                <div style="display:flex; gap:10px; align-items:center;">
-                    <input type="range" id="sigmaRange" min="0.3" max="10.0" step="0.1" value="1.0">
-                    <span id="sigmaVal" style="min-width:30px; font-size:12px;">1.0</span>
-                </div>
-            </div>
-        </div>
+<div id="counts-chip"></div>
 
-        <div class="sidebar-section" id="section-export">
-            <div class="section-header">Export</div>
-
-            <div class="control-group">
-                <label style="display:flex; align-items:center; gap:8px; font-size: 13px;">
-                    <input type="checkbox" id="chkExportSeg" checked>
-                    Segmentations
-                </label>
-                <label style="display:flex; align-items:center; gap:8px; font-size: 13px;">
-                    <input type="checkbox" id="chkExportProb">
-                    Probabilities
-                </label>
-            </div>
+<div id="loading-toast" aria-live="polite" hidden></div>
 
-            <button id="btnExportAll" class="btn-primary" disabled>
-                Export Loaded Images
-            </button>
-
-            <p class="hint">
-                At least 5 labels are needed to train before export.
-            </p>
+<!-- Bottom-center floating taskbar — the single control surface. -->
+<div id="taskbar" role="toolbar" aria-label="Tools">
+    <div class="tb-group">
+        <button class="tool-btn active" data-tool="grab" title="Grab / Pan (G)">🖐</button>
+        <button class="tool-btn" data-tool="paint" title="Paint (P)">🖌</button>
+        <button class="tool-btn" data-tool="erase" title="Erase (E)">🧽</button>
+    </div>
 
-            <button id="btnExportIlp" class="btn-primary" disabled>
-                Export ilastik Project (.ilp)
-            </button>
-            <div id="ilpSaveStatus" class="save-status"></div>
+    <span class="tb-sep"></span>
 
-            <p class="hint">
-                Fully self-contained — images and labels are embedded in the file. Opens in
-                desktop ilastik, which retrains its own classifier on open. Ctrl/Cmd+S to save.
-            </p>
-        </div>
+    <label class="tb-field" title="Brush size ( [ / ] )">
+        <span class="tb-field-label">Brush</span>
+        <input type="number" id="brushSizeInput" min="1" max="32" step="1" value="5">
+    </label>
 
+    <div id="classDropdown" class="tb-dropdown">
+        <button class="cd-trigger" aria-haspopup="true" aria-expanded="false" title="Active class">
+            <span class="cd-trigger-swatch"></span>
+            <span class="cd-trigger-name">Class 1</span>
+            <span class="cd-caret">▾</span>
+        </button>
+        <div class="cd-popup class-selector" hidden></div>
     </div>
 
-    <div id="viewport">
-        <div id="canvas-board"></div>
+    <span class="tb-sep"></span>
+
+    <label class="tb-field tb-field-sigma" title="Feature scale (sigma)">
+        <span class="tb-field-label">Sigma</span>
+        <input type="range" id="sigmaRange" min="0.3" max="10.0" step="0.1" value="1.0">
+        <span id="sigmaVal">1.0</span>
+    </label>
+
+    <span class="tb-sep"></span>
+
+    <div id="overflowWrap" class="tb-dropdown">
+        <button id="btnOverflow" class="tool-btn" aria-haspopup="true" aria-expanded="false" title="More">⋯</button>
+        <div id="overflowMenu" hidden>
+            <button id="btnAddImages" class="overflow-item">🖼️&nbsp;&nbsp;Add images…</button>
+            <button id="btnOpenExport" class="overflow-item">⬇️&nbsp;&nbsp;Export…</button>
+            <div class="overflow-sep"></div>
+            <button id="btnCheatsheet" class="overflow-item">❓&nbsp;&nbsp;Cheatsheet</button>
+            <button id="btnThemeToggle" class="overflow-item">☀️&nbsp;&nbsp;Light Mode</button>
+            <button id="btnFeedback" class="overflow-item">💬&nbsp;&nbsp;Feedback</button>
+        </div>
     </div>
-
 </div>
 <script type="module">
     import { Quantosaurus } from './js/quantosaurus.js';
@@ -504,15 +508,12 @@ <h3>Frequently Asked Questions</h3>
             document.getElementById('sigmaVal').innerText = e.detail.sigma.toFixed(1);
         });
 
-        // Brush size — slider and [ / ] hotkeys both go through q.setBrushSize
-        // (which clamps); the slider + readout reflect the event.
-        const brushRange = document.getElementById('brushSizeRange');
-        const brushVal   = document.getElementById('brushVal');
-        brushRange.oninput = () => q.setBrushSize(parseInt(brushRange.value, 10));
-        q.addEventListener('brushsizechanged', (e) => {
-            brushRange.value   = e.detail.size;
-            brushVal.innerText = e.detail.size;
-        });
+        // Brush size — the number input and the [ / ] hotkeys both go through
+        // q.setBrushSize (which clamps); the input reflects the event, so its
+        // shown value is always the clamped one.
+        const brushInput = document.getElementById('brushSizeInput');
+        brushInput.onchange = () => q.setBrushSize(parseInt(brushInput.value, 10));
+        q.addEventListener('brushsizechanged', (e) => { brushInput.value = e.detail.size; });
 
         // Tools (Grab, Paint, Erase) — buttons call q.setTool; the active
         // highlight follows the toolchanged event (q handles the body cursor class).
@@ -524,33 +525,38 @@ <h3>Frequently Asked Questions</h3>
                 b.classList.toggle('active', b.dataset.tool === e.detail.tool));
         });
 
-        // Setup class selector with stat badges. The forest owns the class count
-        // (q.numClasses); colors come from the mutable palette q owns, falling
-        // back to neutral gray if fewer colors than classes are defined.
+        // Setup the class dropdown (color swatch + editable name + selection)
+        // and the upper-right counts chip (per-class object count + a marker
+        // toggle dot). The forest owns the class count (q.numClasses); colors
+        // come from the mutable palette q owns, falling back to neutral gray.
         // The color swatch is a native <input type="color">, which always emits
-        // #rrggbb hex — palette entries are expected to stay hex from this point
-        // on so they round-trip through the picker cleanly.
+        // #rrggbb hex — palette entries stay hex so they round-trip cleanly.
         const classColors = q.getClassColors();
         const classNames  = q.getClassNames();
-        document.querySelector('.class-selector').innerHTML =
+
+        // Dropdown popup: one selectable row per class.
+        document.querySelector('.cd-popup').innerHTML =
             Array.from({ length: q.numClasses }, (_, index) => {
                 const color = classColors[index] ?? '#888888';
                 return `
             <div class="class-item ${index === 0 ? 'active' : ''}" data-class="${index}">
-                <input type="color" class="color-box" data-class="${index}" value="${color}" title="Click to change color">
+                <input type="color" class="color-box" data-class="${index}" value="${color}" title="Class color">
                 <span contenteditable data-class="${index}"></span>
-                <div class="class-count">
-                    <span class="class-count-number" id="stat-class-${index}">0</span>
-                    <button type="button"class="class-count-dot" id="dot-class-${index}" data-class="${index}"
-                            title="Toggle markers on canvas" aria-pressed="true"></button>
-                </div>
-            </div>
-        `;
+            </div>`;
             }).join('');
 
+        // Counts chip: one badge per class (count + marker-toggle dot).
+        document.getElementById('counts-chip').innerHTML =
+            Array.from({ length: q.numClasses }, (_, index) => `
+            <div class="cc-item" data-class="${index}">
+                <button type="button" class="class-count-dot" id="dot-class-${index}" data-class="${index}"
+                        title="Toggle markers on canvas" aria-pressed="true"></button>
+                <span class="class-count-number" id="stat-class-${index}">0</span>
+            </div>`).join('');
+
         // Fill class names via textContent (not innerHTML above) so persisted, user-
         // supplied names can't inject markup into the class selector.
-        document.querySelectorAll('.class-item span[contenteditable]').forEach(span => {
+        document.querySelectorAll('.cd-popup .class-item span[contenteditable]').forEach(span => {
             span.textContent = classNames[parseInt(span.dataset.class, 10)];
         });
 
@@ -560,21 +566,33 @@ <h3>Frequently Asked Questions</h3>
             document.getElementById(`dot-class-${i}`)?.style.setProperty('--dot-color', classColors[i] ?? '#888888');
         }
 
-        // Class selection — items call q.setClass; the highlight follows the event.
-        document.querySelectorAll('.class-item').forEach(el => {
+        // Dropdown trigger reflects the active class (swatch + name).
+        const cdSwatch = document.querySelector('.cd-trigger-swatch');
+        const cdName   = document.querySelector('.cd-trigger-name');
+        function updateClassTrigger() {
+            const i = q.currentClass;
+            cdSwatch.style.background = q.getClassColors()[i] ?? '#888888';
+            cdName.textContent = q.getClassNames()[i] ?? `Class ${i + 1}`;
+        }
+        updateClassTrigger();
+
+        // Class selection — clicking a row (including its name) makes that class
+        // active. The dropdown stays open so colors/names can be tweaked in the
+        // same session; it dismisses via the trigger, an outside click, or Escape.
+        document.querySelectorAll('.cd-popup .class-item').forEach(el => {
             el.onclick = () => q.setClass(parseInt(el.dataset.class, 10));
         });
         q.addEventListener('classchanged', (e) => {
-            document.querySelectorAll('.class-item').forEach(el =>
+            document.querySelectorAll('.cd-popup .class-item').forEach(el =>
                 el.classList.toggle('active', parseInt(el.dataset.class, 10) === e.detail.index));
+            updateClassTrigger();
         });
 
-        // Swatch dot — toggles that class's on-canvas centroid markers. Cheap: just
-        // re-runs the existing 2D canvas redraw from already-cached detected objects,
-        // no GPU/backend call or stats re-download.
+        // Marker-toggle dot — toggles that class's on-canvas centroid markers.
+        // Cheap: re-runs the 2D canvas redraw from already-cached objects, no
+        // GPU/backend call or stats re-download.
         document.querySelectorAll('.class-count-dot').forEach(dot => {
-            dot.onclick = (e) => {
-                e.stopPropagation(); // don't also re-select the class
+            dot.onclick = () => {
                 const idx = parseInt(dot.dataset.class, 10);
                 q.setMarkersVisible(idx, !q.getMarkersVisible()[idx]);
             };
@@ -589,26 +607,94 @@ <h3>Frequently Asked Questions</h3>
         // falls back to the default for empty/whitespace names (so we never
         // render a blank label or persist ""), and saves the settings. The span
         // is rewritten with whatever name was actually stored.
-        document.querySelectorAll('.class-item span[contenteditable]').forEach(span => {
+        document.querySelectorAll('.cd-popup .class-item span[contenteditable]').forEach(span => {
+            // No stopPropagation: clicking the name still selects the row's class
+            // (it fills most of the row) and places the caret for editing.
             span.onblur = () => {
                 const idx = parseInt(span.dataset.class, 10);
                 span.textContent = q.setClassName(idx, span.textContent);
+                updateClassTrigger();
             };
         });
 
         // Class color pickers — recolor live as the user drags in the native
-        // picker (oninput, not change), mirroring how the contrast slider drives
-        // setWindow on every tick; q.setClassColor is just as cheap per image
-        // (uniform write + repaint, no recompile). The dot tint follows the event.
-        document.querySelectorAll('.color-box').forEach(input => {
-            input.onclick = (e) => e.stopPropagation(); // don't also re-select the class
+        // picker (oninput, not change); q.setClassColor is cheap per image
+        // (uniform write + repaint, no recompile). Dot tint + trigger follow the event.
+        document.querySelectorAll('.cd-popup .color-box').forEach(input => {
+            input.onclick = (e) => e.stopPropagation(); // don't also select+close
             input.oninput = (e) => q.setClassColor(parseInt(input.dataset.class, 10), e.target.value);
         });
         q.addEventListener('classcolorchanged', (e) => {
             document.getElementById(`dot-class-${e.detail.index}`)
                 ?.style.setProperty('--dot-color', e.detail.color);
+            updateClassTrigger();
         });
 
+        // ── Class dropdown open/close ─────────────────────────────────────
+        const classDropdown = document.getElementById('classDropdown');
+        const cdTrigger = classDropdown.querySelector('.cd-trigger');
+        const cdPopup   = classDropdown.querySelector('.cd-popup');
+        function closeClassDropdown() {
+            cdPopup.hidden = true;
+            cdTrigger.setAttribute('aria-expanded', 'false');
+        }
+        function toggleClassDropdown() {
+            const open = cdPopup.hidden;
+            closeAllMenus();
+            if (open) {
+                cdPopup.hidden = false;
+                cdTrigger.setAttribute('aria-expanded', 'true');
+            }
+        }
+        cdTrigger.onclick = (e) => { e.stopPropagation(); toggleClassDropdown(); };
+
+        // ── Taskbar overflow menu ─────────────────────────────────────────
+        const overflowWrap = document.getElementById('overflowWrap');
+        const btnOverflow  = document.getElementById('btnOverflow');
+        const overflowMenu = document.getElementById('overflowMenu');
+        function closeOverflow() {
+            overflowMenu.hidden = true;
+            btnOverflow.setAttribute('aria-expanded', 'false');
+        }
+        btnOverflow.onclick = (e) => {
+            e.stopPropagation();
+            const open = overflowMenu.hidden;
+            closeAllMenus();
+            if (open) { overflowMenu.hidden = false; btnOverflow.setAttribute('aria-expanded', 'true'); }
+        };
+
+        // One dismiss path for every floating menu: click anywhere else, or Escape.
+        function closeAllMenus() { closeClassDropdown(); closeOverflow(); }
+        document.addEventListener('click', closeAllMenus);
+        document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeAllMenus(); });
+        classDropdown.addEventListener('click', (e) => e.stopPropagation());
+        overflowWrap.addEventListener('click', (e) => e.stopPropagation());
+
+        // ── Add images ────────────────────────────────────────────────────
+        // The empty-state's <label for="fileInput"> opens the picker directly;
+        // this taskbar item is the path once images already fill the board.
+        // (Empty-state visibility itself is owned by ui.js syncUI.)
+        const fileInput = document.getElementById('fileInput');
+        document.getElementById('btnAddImages').onclick = () => { closeOverflow(); fileInput.click(); };
+
+        // ── Loading toast ─────────────────────────────────────────────────
+        // Large TIFFs decode slowly and the board tile only appears once the
+        // load finishes, so show a brief toast in between. Counts concurrent
+        // loads so a multi-file drop clears the toast only when all are done.
+        const loadingToast = document.getElementById('loading-toast');
+        let loadingCount = 0;
+        q.addEventListener('imageloadstart', (e) => {
+            loadingCount++;
+            loadingToast.textContent = loadingCount > 1 ? `Loading ${loadingCount} images…` : `Loading ${e.detail.name}…`;
+            loadingToast.hidden = false;
+        });
+        const doneLoading = () => {
+            loadingCount = Math.max(0, loadingCount - 1);
+            if (loadingCount === 0) loadingToast.hidden = true;
+        };
+        q.addEventListener('imageadded', doneLoading);
+        q.addEventListener('imageloaderror', doneLoading);
+
         // Hotkeys (see cheatsheet): [ / ] resize brush, 1-9 select class, P/E/G switch tool.
         // Ignored while typing into an input/textarea or renaming a class (contenteditable).
         window.addEventListener('keydown', (e) => {
@@ -631,6 +717,19 @@ <h3>Frequently Asked Questions</h3>
             }
         });
 
+        // Overflow menu items each dismiss the menu (their clicks are stopped
+        // from bubbling to the document-level dismiss handler by overflowWrap).
+        overflowMenu.querySelectorAll('.overflow-item').forEach(b =>
+            b.addEventListener('click', closeOverflow));
+
+        // ── Export modal ──────────────────────────────────────────────────
+        const exportModal = document.getElementById('exportModal');
+        const openExport  = () => { exportModal.style.display = 'flex'; };
+        const closeExport = () => { exportModal.style.display = 'none'; };
+        document.getElementById('btnOpenExport').onclick = openExport;
+        document.getElementById('btnCloseExport').onclick = closeExport;
+        exportModal.onclick = (e) => { if (e.target === exportModal) closeExport(); };
+
         // Export
         const btnExport = document.getElementById('btnExportAll');
         btnExport.onclick = async () => {
diff --git a/js/images.js b/js/images.js
index ce49286..5f23658 100644
--- a/js/images.js
+++ b/js/images.js
@@ -3,6 +3,7 @@ import { WebGpuBackend } from './backends/webgpu.js';
 import { WebGl2Backend } from './backends/webgl2.js';
 import { loadFileIntoArray } from './io.js';
 import { scheduleTraining } from './training.js';
+import { openContrastPopover } from './contrast.js';
 
 // Dispatches a CustomEvent on the owning Quantosaurus instance (state.events).
 // Optional-chained so state objects without a dispatch target (unit tests,
@@ -59,6 +60,36 @@ async function initializeBackend(canvas, labelColors) {
   throw new Error("No compatible rendering backend found.");
 }
 
+/**
+ * Builds the floating controls overlaid on one image tile: reorder left/right,
+ * contrast, and delete. Buttons call the image-lifecycle functions directly
+ * with `state` (the tile owns them, like the paint handlers) — the contrast
+ * button anchors its popover to itself.
+ * @param {Object} state - Shared app state.
+ * @param {string} imgId - Id of the image this tile represents.
+ * @returns {HTMLDivElement} The controls overlay (not yet attached).
+ */
+function buildTileControls(state, imgId) {
+    const wrap = document.createElement('div');
+    wrap.className = 'tile-controls';
+
+    const mk = (cls, glyph, title, onClick) => {
+        const b = document.createElement('button');
+        b.className   = `tile-btn ${cls}`;
+        b.textContent = glyph;
+        b.title       = title;
+        b.onclick     = (e) => { e.stopPropagation(); onClick(b); };
+        return b;
+    };
+
+    wrap.appendChild(mk('tile-reorder', '‹', 'Move earlier', () => reorderImage(state, imgId, -1)));
+    wrap.appendChild(mk('tile-reorder', '›', 'Move later',   () => reorderImage(state, imgId, +1)));
+    wrap.appendChild(mk('tile-contrast', '◐', 'Adjust contrast', (btn) => openContrastPopover(state, imgId, btn)));
+    wrap.appendChild(mk('tile-delete', '✕', 'Remove image', () => deleteImage(state, imgId)));
+
+    return wrap;
+}
+
 /**
  * Adds a batch of dropped/selected files, skipping unsupported types and
  * duplicates (matched by name + size).
@@ -134,10 +165,16 @@ export async function addImage(state, file) {
     tileLabel.className   = 'image-tile-label';
     tileLabel.textContent = `${file.name} ${w}x${h}`;
 
+    // Per-tile controls (reorder ‹ ›, contrast ◐, delete ✕) — revealed on hover
+    // (or always, on coarse pointers; see .tile-controls in style.css). These
+    // replace the old sidebar row's buttons now that the board is the only view.
+    const controls = buildTileControls(state, imgId);
+
     container.appendChild(gpuCanvas);
     container.appendChild(labelCanvas);
     container.appendChild(overlayCanvas);
     container.appendChild(tileLabel);
+    container.appendChild(controls);
     state.board.appendChild(container);
 
     let backend = null;
diff --git a/js/ui.js b/js/ui.js
index 17f02c2..d0deefb 100644
--- a/js/ui.js
+++ b/js/ui.js
@@ -1,66 +1,28 @@
 /**
- * Wires the sidebar/top-bar chrome onto a Quantosaurus instance's events: the
- * per-image sidebar rows (with loading state), the status line, the training
- * indicator, the save indicator, and the per-class count badges. The chrome is
- * a pure subscriber — every mutation goes back through methods on `q`, so this
- * whole layer can be swapped out (or omitted, in an embed) without touching
- * the app core.
+ * Wires the floating chrome onto a Quantosaurus instance's events: the count
+ * badges, the training indicator, the save indicator, the export-button enable
+ * state, and image-load errors. The chrome is a pure subscriber — every
+ * mutation goes back through methods on `q`, so this whole layer can be swapped
+ * out (or omitted, in an embed) without touching the app core. The taskbar
+ * controls themselves are wired separately (see index.html's setupUI).
  * @param {import('./quantosaurus.js').Quantosaurus} q - The app instance.
  */
 export function bindChrome(q) {
     const state = q.state;
-    const rows = new Map(); // imgId -> sidebar row element
 
-    q.addEventListener('imageloadstart', (e) => {
-        const { id, name } = e.detail;
-        const row = createImageRow(id, name, {
-            onReorder: (dir)     => q.reorderImage(id, dir),
-            onDelete:  ()        => q.deleteImage(id),
-            onContrast: (anchor) => q.openContrast(id, anchor),
-        });
-        row.classList.add('loading');
-        document.getElementById('img-empty').style.display = 'none';
-        document.getElementById('image-list').appendChild(row);
-        rows.set(id, row);
-    });
-
-    q.addEventListener('imageadded', (e) => {
-        rows.get(e.detail.id)?.classList.remove('loading');
-        syncUI(state);
-    });
+    q.addEventListener('imageadded', () => syncUI(state));
+    q.addEventListener('imageremoved', () => syncUI(state));
 
     q.addEventListener('imageloaderror', (e) => {
-        const { id, message } = e.detail;
-        rows.get(id)?.remove();
-        rows.delete(id);
-        syncUI(state);
-        if (message) alert(message);
-    });
-
-    q.addEventListener('imageremoved', (e) => {
-        rows.get(e.detail.id)?.remove();
-        rows.delete(e.detail.id);
-        syncUI(state);
-    });
-
-    q.addEventListener('imagereordered', (e) => {
-        const { fromIndex, toIndex } = e.detail;
-        const list = document.getElementById('image-list');
-        const els  = [...list.children];
-        // Mirror the board-tile swap in images.js:reorderImage — the moved row
-        // goes before (moving up) or after (moving down) its neighbor.
-        if (toIndex < fromIndex) list.insertBefore(els[fromIndex], els[toIndex]);
-        else                     list.insertBefore(els[toIndex], els[fromIndex]);
-        updateSaveIndicator(state);
+        if (e.detail.message) alert(e.detail.message);
     });
 
     q.addEventListener('dirtychange', () => updateSaveIndicator(state));
 
     q.addEventListener('trainingstart', () => {
         // Give immediate feedback for the otherwise-silent await: a progress
-        // cursor + "Training…" status while the overlay recomputes, and the
-        // count badges wiped to a pulsing placeholder so the stale numbers
-        // don't just sit there.
+        // cursor while the overlay recomputes, and the count badges wiped to a
+        // pulsing placeholder so the stale numbers don't just sit there.
         setTrainingIndicator(state, true);
         setClassBadgesLoading();
     });
@@ -72,43 +34,30 @@ export function bindChrome(q) {
         if (animate) animateClassStatBadges(counts);
         else         updateClassStatBadges(counts);
     });
+
+    syncUI(state); // seed the initial empty/export state
 }
 
 /**
- * Refreshes all image-count-driven chrome (status line, export button, empty
- * state) in one call. Invoke after any change to state.images.
+ * Refreshes all image-count-driven chrome (export button, empty state, save
+ * indicator) in one call. Invoke after any change to state.images.
  * @param {Object} state - Shared app state.
  */
 export function syncUI(state) {
-    updateStatus(state);
     updateExportButtonCount(state);
     refreshEmptyState(state);
     updateSaveIndicator(state);
 }
 
-/** Updates the status line with the loaded-image count. @param {Object} state */
-export function updateStatus(state) {
-    const n = state.images.length;
-    document.getElementById('status').innerText =
-        n === 0 ? 'No images loaded. Drag & drop onto the canvas.'
-                : `${n} image${n !== 1 ? 's' : ''} loaded.`;
-}
-
 /**
- * Toggles the global "training in progress" affordance: a progress cursor (via a
- * body class) plus a status-line message. On turn-off it restores the normal
- * image-count status. Gives feedback while the overlay/probabilities recompute,
- * which is otherwise a silent await.
- * @param {Object} state - Shared app state (for restoring the status text).
+ * Toggles the global "training in progress" affordance: a progress cursor via a
+ * body class. Gives feedback while the overlay/probabilities recompute, which
+ * is otherwise a silent await.
+ * @param {Object} _state - Shared app state (unused; kept for call-site symmetry).
  * @param {boolean} on - Whether training is currently running.
  */
-export function setTrainingIndicator(state, on) {
+export function setTrainingIndicator(_state, on) {
     document.body.classList.toggle('training', on);
-    if (on) {
-        document.getElementById('status').innerText = 'Training…';
-    } else {
-        updateStatus(state);
-    }
 }
 
 /** Enables/labels the "Export Loaded Images" button by image count. @param {Object} state */
@@ -122,10 +71,10 @@ export function updateExportButtonCount(state) {
     if (ilpBtn) ilpBtn.disabled = n === 0;
 }
 
-/** Shows/hides the image-list empty-state placeholder. @param {Object} state */
+/** Shows/hides the centered empty-state drop target. @param {Object} state */
 export function refreshEmptyState(state) {
-    document.getElementById('img-empty').style.display =
-        state.images.length === 0 ? '' : 'none';
+    const el = document.getElementById('empty-state');
+    if (el) el.style.display = state.images.length === 0 ? '' : 'none';
 }
 
 // Handle of the in-flight count-up animation frame, so a new retrain (or a no-op
@@ -238,63 +187,3 @@ export function animateClassStatBadges(counts) {
 
     _countupRaf = requestAnimationFrame(step);
 }
-
-/**
- * Builds the sidebar DOM row for one image. The controller supplies the
- * callbacks so this view stays decoupled from the image-lifecycle module.
- * @param {string} imgId - Image id, stored on the row's dataset.
- * @param {string} name - Display name.
- * @param {{onReorder: (direction: -1|1) => void, onDelete: () => void}} handlers
- * @returns {HTMLDivElement} The constructed row element (not yet attached).
- */
-export function createImageRow(imgId, name, { onReorder, onDelete, onContrast }) {
-    const row = document.createElement('div');
-    row.className  = 'img-row';
-    row.dataset.id = imgId;
-
-    const loadBar = document.createElement('div');
-    loadBar.className = 'img-loading-bar';
-
-    const header = document.createElement('div');
-    header.className = 'img-row-header';
-
-    const reorder = document.createElement('div');
-    reorder.className = 'img-reorder';
-    const btnUp   = document.createElement('button');
-    const btnDown = document.createElement('button');
-    btnUp.textContent   = '▲';
-    btnDown.textContent = '▼';
-    btnUp.title   = 'Move up';
-    btnDown.title = 'Move down';
-    btnUp.onclick   = () => onReorder(-1);
-    btnDown.onclick = () => onReorder(+1);
-    reorder.appendChild(btnUp);
-    reorder.appendChild(btnDown);
-
-    const nameEl = document.createElement('div');
-    nameEl.className   = 'img-name';
-    nameEl.textContent = name;
-    nameEl.title       = name;
-
-    const btnContrast = document.createElement('button');
-    btnContrast.className   = 'img-contrast';
-    btnContrast.textContent = '◐';
-    btnContrast.title       = 'Adjust contrast';
-    btnContrast.onclick     = (e) => { e.stopPropagation(); onContrast?.(btnContrast); };
-
-    const btnDel = document.createElement('button');
-    btnDel.className   = 'img-delete';
-    btnDel.textContent = '✕';
-    btnDel.title       = 'Remove image';
-    btnDel.onclick     = () => onDelete();
-
-    header.appendChild(reorder);
-    header.appendChild(nameEl);
-    header.appendChild(btnContrast);
-    header.appendChild(btnDel);
-
-    row.appendChild(loadBar);
-    row.appendChild(header);
-
-    return row;
-}
diff --git a/style.css b/style.css
index b4f7940..267441d 100644
--- a/style.css
+++ b/style.css
@@ -44,6 +44,13 @@
     box-sizing: border-box;
 }
 
+/* The [hidden] attribute must win over the display values set on menus/popups
+   below (a bare `display:flex` rule otherwise overrides [hidden]'s display:none,
+   leaving them permanently visible). */
+[hidden] {
+    display: none !important;
+}
+
 body {
     font-family:
         -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial,
@@ -84,59 +91,9 @@ body.theme-light .btn-subtle { color: var(--text-main); }
 
 
 /* ── Layout & Structure ───────────────────────────────────────────── */
-#top-bar {
-    padding: 10px 20px;
-    background: var(--bg-surface-elevated);
-    border-bottom: 1px solid var(--border-subtle);
-    display: flex;
-    align-items: center;
-    gap: 20px;
-    z-index: 10;
-    flex-shrink: 0;
-}
-
-#main-container {
-    flex: 1;
-    display: flex;
-    overflow: hidden;
-}
-
-#sidebar {
-    width: 270px;
-    background: var(--bg-surface);
-    border-right: 1px solid var(--border-subtle);
-    display: flex;
-    flex-direction: column;
-    overflow-y: auto;
-    overflow-x: hidden;
-    flex-shrink: 0;
-    z-index: 10;
-}
-
-h2 {
-    margin: 0;
-    font-size: 18px;
-    font-weight: bold;
-    color: var(--text-muted);
-;
-}
-
-.sidebar-section {
-    display: flex;
-    flex-direction: column;
-    gap: 14px;
-    padding: 16px;
-    border-bottom: 1px solid var(--border-subtle);
-}
-
-.section-header {
-    font-size: 13px;
-    font-weight: 600;
-    color: var(--text-main);
-    text-transform: uppercase;
-    letter-spacing: 0.6px;
-    margin-bottom: -4px;
-}
+/* The viewport is the only in-flow child of <body>; all chrome floats over it
+   (position:fixed) so the board can fill the screen edge-to-edge — the
+   mobile-first / embeddable posture. */
 
 a {
     color: var(--accent-primary);
@@ -271,130 +228,142 @@ button:disabled {
     background: var(--accent-subtle-hover);
 }
 
-/* ── Image Ingest Modules ─────────────────────────────────────────── */
-#image-list {
+/* ── Floating Taskbar ─────────────────────────────────────────────── */
+#taskbar {
+    position: fixed;
+    left: 50%;
+    transform: translateX(-50%);
+    bottom: calc(env(safe-area-inset-bottom, 0px) + 16px);
+    z-index: 100;
     display: flex;
-    flex-direction: column;
-    gap: 6px;
-}
-
-.img-row {
+    align-items: center;
+    gap: 8px;
+    padding: 8px 10px;
+    max-width: calc(100vw - 24px);
     background: var(--bg-surface-elevated);
     border: 1px solid var(--border-subtle);
-    border-radius: var(--radius-md);
-    overflow: hidden;
+    border-radius: 14px;
+    box-shadow: 0 8px 30px rgba(0, 0, 0, 0.45);
+    /* Taps on the taskbar controls must not be swallowed by the viewport's
+       pan/pinch handling — the taskbar lives outside #viewport, and this keeps
+       button/slider taps snappy on touch. */
+    touch-action: manipulation;
+}
+.tb-group {
+    display: flex;
+    gap: 4px;
 }
-
-.img-row-header {
+#taskbar .tool-btn {
+    flex: 0 0 auto;
+    width: 38px;
+    height: 34px;
+    font-size: 16px;
+}
+.tb-sep {
+    width: 1px;
+    align-self: stretch;
+    margin: 2px 2px;
+    background: var(--border-subtle);
+}
+.tb-field {
     display: flex;
     align-items: center;
     gap: 6px;
-    padding: 6px 8px;
 }
-
-.img-reorder {
-    display: flex;
-    flex-direction: column;
-    gap: 1px;
-    flex-shrink: 0;
-}
-.img-reorder button {
-    background: none;
-    border: none;
-    color: var(--text-disabled);
-    padding: 0;
+.tb-field-label {
     font-size: 10px;
-    line-height: 1;
-    cursor: pointer;
-    font-weight: normal;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--text-muted);
 }
-.img-reorder button:hover {
-    color: var(--text-dim);
-    background: none;
+#brushSizeInput {
+    width: 48px;
+    text-align: center;
+    font-size: 12px;
 }
-
-.img-name {
-    flex: 1;
+.tb-field-sigma { min-width: 130px; }
+.tb-field-sigma input[type="range"] { flex: 1; min-width: 64px; }
+#sigmaVal {
     font-size: 12px;
+    font-family: monospace;
     color: var(--text-dim);
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
+    min-width: 26px;
+    text-align: right;
 }
 
-.img-delete {
-    flex-shrink: 0;
-    background: none;
-    border: none;
-    color: var(--text-disabled);
-    font-size: 13px;
-    cursor: pointer;
-    padding: 2px 4px;
+/* Class dropdown + overflow menu share the "trigger + popup that opens upward"
+   pattern (the taskbar is pinned to the bottom of the screen). */
+.tb-dropdown { position: relative; }
+.cd-trigger {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    height: 34px;
+    padding: 0 8px;
+    background: var(--bg-control);
+    color: var(--text-main);
+    border: 1px solid var(--border-control);
     border-radius: var(--radius-sm);
-    line-height: 1;
-}
-/* :not(:disabled) matches the specificity of the global button:hover rule so this
-   red actually wins (a plain .img-delete:hover loses to button:hover:not(:disabled)). */
-.img-delete:hover:not(:disabled) {
-    background: var(--accent-danger);
-    color: var(--text-light);
+    font-size: 12px;
+    font-weight: 600;
+    max-width: 140px;
 }
-
-.img-contrast {
-    flex-shrink: 0;
-    background: none;
-    border: none;
-    color: var(--text-disabled);
-    font-size: 13px;
-    cursor: pointer;
-    padding: 2px 4px;
+.cd-trigger:hover { background: var(--accent-subtle-hover); }
+.cd-trigger-swatch {
+    width: 14px;
+    height: 14px;
     border-radius: var(--radius-sm);
-    line-height: 1;
+    flex-shrink: 0;
 }
-.img-contrast:hover:not(:disabled) {
-    background: var(--accent-subtle-hover);
-    color: var(--text-light);
+.cd-trigger-name {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
 }
+.cd-caret { color: var(--text-muted); font-size: 10px; flex-shrink: 0; }
 
-/* Async Processing states */
-.img-row.loading .img-row-header {
-    opacity: 0.5;
-    pointer-events: none;
+/* A popup anchored above its trigger (menus open upward off the taskbar). */
+.cd-popup,
+#overflowMenu {
+    position: absolute;
+    bottom: calc(100% + 8px);
+    background: var(--bg-surface-elevated);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-md);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+    padding: 6px;
+    z-index: 1000;
 }
-.img-loading-bar {
-    height: 2px;
-    background: var(--accent-primary);
-    animation: indeterminate 1.2s linear infinite;
-    display: none;
+.cd-popup {
+    left: 0;
+    min-width: 180px;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
 }
-.img-row.loading .img-loading-bar {
-    display: block;
+#overflowMenu {
+    right: 0;
+    min-width: 180px;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
 }
-
-@keyframes indeterminate {
-    0% {
-        margin-left: 0%;
-        width: 30%;
-    }
-    50% {
-        margin-left: 50%;
-        width: 30%;
-    }
-    100% {
-        margin-left: 100%;
-        width: 0%;
-    }
+.overflow-item {
+    background: none;
+    color: var(--text-main);
+    text-align: left;
+    padding: 8px 10px;
+    border-radius: var(--radius-sm);
+    font-weight: 500;
 }
-
-#img-empty {
-    font-size: 12px;
-    color: var(--text-muted);
-    text-align: center;
-    padding: 20px 0;
-    line-height: 1.6;
+.overflow-item:hover { background: var(--accent-subtle-hover); }
+.overflow-sep {
+    height: 1px;
+    background: var(--border-subtle);
+    margin: 4px 0;
 }
 
-/* ── Train Phase Items ────────────────────────────────────────────── */
+/* Class rows inside the dropdown popup (color swatch + editable name). */
 .class-selector {
     display: flex;
     flex-direction: column;
@@ -410,10 +379,94 @@ button:disabled {
     cursor: pointer;
     border: 2px solid transparent;
 }
+.class-item span[contenteditable] {
+    flex: 1;
+    font-size: 13px;
+    outline: none;
+}
 .class-item.active {
     border-color: var(--accent-primary);
     background: var(--bg-surface-elevated);
 }
+
+/* ── Corner Chips ─────────────────────────────────────────────────── */
+#dirty-chip {
+    position: fixed;
+    top: calc(env(safe-area-inset-top, 0px) + 12px);
+    left: 12px;
+    z-index: 100;
+    padding: 4px 10px;
+    background: var(--bg-surface-elevated);
+    border: 1px solid var(--border-subtle);
+    border-radius: 999px;
+    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
+}
+#dirty-chip:empty { display: none; }
+
+#counts-chip {
+    position: fixed;
+    top: calc(env(safe-area-inset-top, 0px) + 12px);
+    right: 12px;
+    z-index: 100;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 6px 12px;
+    background: var(--bg-surface-elevated);
+    border: 1px solid var(--border-subtle);
+    border-radius: 999px;
+    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
+}
+.cc-item {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+}
+
+#loading-toast {
+    position: fixed;
+    left: 50%;
+    top: calc(env(safe-area-inset-top, 0px) + 12px);
+    transform: translateX(-50%);
+    z-index: 100;
+    padding: 6px 14px;
+    font-size: 12px;
+    color: var(--text-dim);
+    background: var(--bg-surface-elevated);
+    border: 1px solid var(--border-subtle);
+    border-radius: 999px;
+    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
+}
+
+/* ── Empty State ──────────────────────────────────────────────────── */
+#empty-state {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 10px;
+    text-align: center;
+    pointer-events: none; /* let drag-and-drop reach the viewport underneath */
+    color: var(--text-muted);
+}
+#empty-state .empty-dino { font-size: 48px; }
+#empty-state .empty-title { font-size: 16px; font-weight: 600; color: var(--text-dim); }
+#empty-state .empty-sub { font-size: 12px; }
+#empty-state .empty-pick {
+    pointer-events: auto; /* the picker button stays clickable */
+    margin-top: 6px;
+    padding: 8px 16px;
+    background: var(--accent-primary);
+    color: var(--text-light);
+    border-radius: var(--radius-sm);
+    font-size: 12px;
+    font-weight: 600;
+    cursor: pointer;
+    text-decoration: none;
+}
+#empty-state .empty-pick:hover { background: var(--accent-primary-hover); }
 .color-box {
     width: 14px;
     height: 14px;
@@ -440,12 +493,6 @@ button:disabled {
     outline: 1px solid var(--accent-primary);
     outline-offset: 1px;
 }
-.class-count {
-    display: flex;
-    align-items: center;
-    gap: 6px;
-    margin-left: auto;
-}
 /* A small class-colored swatch that doubles as a toggle button for that class's
    on-canvas centroid markers — --dot-color is set inline per class (index.html). */
 .class-count-dot {
@@ -644,6 +691,40 @@ button:disabled {
     z-index: 5;
 }
 
+/* Per-tile controls (reorder / contrast / delete), top-right of each tile.
+   Revealed on hover on fine pointers; always visible on touch (no hover). */
+.tile-controls {
+    position: absolute;
+    top: 4px;
+    right: 4px;
+    display: flex;
+    gap: 3px;
+    z-index: 6;
+    opacity: 0;
+    transition: opacity 0.12s ease;
+}
+.image-container:hover .tile-controls { opacity: 1; }
+.tile-btn {
+    width: 22px;
+    height: 22px;
+    padding: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 12px;
+    line-height: 1;
+    background: rgba(0, 0, 0, 0.65);
+    color: var(--text-light);
+    border: 1px solid rgba(255, 255, 255, 0.15);
+    border-radius: var(--radius-sm);
+}
+.tile-btn:hover { background: rgba(0, 0, 0, 0.85); }
+.tile-btn.tile-delete:hover { background: var(--accent-danger); }
+/* Touch devices have no hover, so keep the controls visible there. */
+@media (pointer: coarse) {
+    .tile-controls { opacity: 1; }
+}
+
 canvas {
     position: absolute;
     top: 0;