Low-vision accessibility mode, modular architecture refactor, and QA fixes

CLAUDE.md

@@ -22,7 +22,7 @@ python -m src.digitalsreeni_image_annotator.main
 
 Python 3.10+ | PyQt6 6.7+ | Ultralytics 8.3.27 (SAM 2) | NumPy | OpenCV | Shapely
 
-**Test suite**: `tests/` (pytest + pytest-qt). 65 tests pass on PyQt6.
+**Test suite**: `tests/` (pytest + pytest-qt). 94 tests pass on PyQt6.
 
 ## Documentation
 
@@ -40,23 +40,44 @@ See [docs/README.md](docs/README.md) for full documentation index.
 
 ```
 src/digitalsreeni_image_annotator/
-├── main.py                    # Entry point
-├── annotator_window.py        # ImageAnnotator - main window, project state
-├── image_label.py             # ImageLabel - display, mouse events, rendering
-├── sam_utils.py               # SAMUtils - SAM model management
-├── utils.py                   # Utility functions
-├── export_formats.py          # COCO, YOLO, Pascal VOC exporters
-├── import_formats.py          # COCO, YOLO importers
-└── [tool dialogs]             # Standalone utility windows
+├── main.py                       # Entry point
+├── annotator_window.py           # ImageAnnotator - thin orchestrator
+├── app_settings.py               # QSettings UI prefs: ui_font_pt, dark_mode (ADR-020)
+├── utils.py                      # Utility functions (calculate_area, …)
+├── __init__.py                   # Public API re-exports
+│
+├── core/                         # constants, annotation_utils, image_utils
+├── controllers/                  # 7 controllers (project, image, sam, dino,
+│                                 #   yolo, annotation, class) + io_controller
+├── widgets/
+│   ├── image_label.py            # ImageLabel canvas widget (dispatcher)
+│   ├── canvas_context.py         # CanvasContext read accessor (ADR-018)
+│   └── tools/                    # Per-tool handlers (ADR-019): rectangle,
+│                                 #   polygon, paint, eraser
+├── inference/                    # sam_utils.py, dino_utils.py
+├── io/                           # export_formats.py, import_formats.py
+├── ui/                           # menu_bar, sidebar, shortcuts, theme, stylesheets
+└── dialogs/                      # Standalone tool dialogs (statistics,
+                                  #   splitter, augmenter, … 16 files)
 ```
 
 ## Key Classes
 
 | Class | File | Responsibility |
 |-------|------|----------------|
-| `ImageAnnotator` | annotator_window.py | Main window, state (`all_annotations`, `class_mapping`, etc.) |
-| `ImageLabel` | image_label.py | Image display, zoom/pan, annotation interaction |
-| `SAMUtils` | sam_utils.py | Load SAM models, run inference |
+| `ImageAnnotator` | annotator_window.py | Thin orchestrator — holds controllers, wires signals, delegates almost everything |
+| `ImageLabel` | widgets/image_label.py | Canvas display, zoom/pan, event dispatch to tool handlers |
+| `CanvasContext` | widgets/canvas_context.py | Narrow read view of main-window state for ImageLabel (ADR-018) |
+| `ToolHandler` (+ 4 subclasses) | widgets/tools/ | Per-tool mouse/key handling (rectangle, polygon, paint, eraser) (ADR-019) |
+| `ProjectController` | controllers/project_controller.py | `.iap` save/load, auto-save, `is_loading_project` guard |
+| `ImageController` | controllers/image_controller.py | TIFF/CZI loading, multi-dim slicing, image/slice switching |
+| `AnnotationController` | controllers/annotation_controller.py | Annotation CRUD, sort, edit-mode, finish_polygon/rectangle |
+| `ClassController` | controllers/class_controller.py | Class add/delete/rename/colour/visibility |
+| `SAMController` | controllers/sam_controller.py | SAM model picker, debounce, in-flight guard (ADR-013) |
+| `DINOController` | controllers/dino_controller.py | DINO single/batch detection, batch review, temp-class workflow |
+| `YOLOController` | controllers/yolo_controller.py | YOLO training menu + prediction wiring |
+| `SAMUtils` | inference/sam_utils.py | Load SAM models, run inference |
+| `DINOUtils` | inference/dino_utils.py | Grounding-DINO model load + inference |
 
 See [Building Block View](docs/05_building_block_view.md) for detailed class documentation.
 
@@ -68,7 +89,9 @@ See [Building Block View](docs/05_building_block_view.md) for detailed class doc
 2. Set `image_label.current_tool` on click
 3. Handle mouse events in `ImageLabel` (mousePressEvent, mouseMoveEvent)
 4. Render in `ImageLabel.paintEvent()`
-5. Call `main_window.add_annotation()` to commit
+5. Commit via `self.annotationCommitted.emit(annotation_dict)` — the
+   orchestrator routes it to `AnnotationController.add_annotation_to_list`
+   (see ADR-018)
 
 ### Working with Annotations
 
@@ -141,7 +164,7 @@ See [Runtime View](docs/06_runtime_view.md#multi-dimensional-image-loading) for
 | Dark mode contrast | No hardcoded `background:` / `color:` in widget `setStyleSheet(...)` | Hardcoded greys override `soft_dark_stylesheet.py` and punch bright boxes into the sidebar. Add a global rule first, then write the widget. See [No Hardcoded Colors Rule](docs/08_crosscutting_concepts.md#dark-mode--no-hardcoded-colors-rule). |
 | DINO review state | `image_label.temp_annotations` is a single field, **not** per-image — must be re-synced from `dino_batch_results` on every image/slice switch via `_refresh_dino_temp_for_current` | Otherwise the first image's masks bleed onto every subsequent slice during navigation. See [DINO Temp Annotations](docs/08_crosscutting_concepts.md#dino-temp-annotations--single-field-many-images). |
 | DINO batch over stacks | Use `_collect_dino_batch_work_items()` to flatten regular images + every loaded slice; don't iterate `self.all_images` directly | Multi-dim images appear in `all_images` as a single entry — slices live in `self.image_slices[base_name]` and were silently skipped. |
-| DINO Enter/Escape during review | Application-wide `_DINOReviewEventFilter`, gated on pending temp_annotations + no modal + no text input | `QListWidget` consumes Enter for `itemActivated` before `ImageLabel.keyPressEvent` sees it. See [ADR-015](docs/09_architecture_decisions.md#adr-015-application-wide-event-filter-for-dino-review-shortcuts). |
+| DINO Enter/Escape during review | Application-wide `DINOReviewEventFilter`, gated on pending temp_annotations + no modal + no text input | `QListWidget` consumes Enter for `itemActivated` before `ImageLabel.keyPressEvent` sees it. See [ADR-015](docs/09_architecture_decisions.md#adr-015-application-wide-event-filter-for-dino-review-shortcuts). |
 | Auto-accept dropdown | Honored by **both** `run_dino_detection_single` and `run_dino_detection_batch` | Easy to forget in the single path because the combo is labeled "batch". |
 | GPU model unload | `model.cpu()` → `gc.collect()` → `torch.cuda.empty_cache()` + `ipc_collect()` + `synchronize()` — full reclaim requires app restart due to per-process CUDA context | Setting refs to None alone leaves circular refs pinned and shows zero Task Manager drop. See [Releasing Model GPU Memory](docs/08_crosscutting_concepts.md#releasing-model-gpu-memory). |
 | Export image-path lookup | Exact-key match first, substring fallback only | `"bee.jpg" in "honeybee.jpg"` is True — substring-only matching writes the wrong file. See [Export Format Filename Matching](docs/08_crosscutting_concepts.md#export-format-filename-matching). |
@@ -161,17 +184,18 @@ See [Runtime View](docs/06_runtime_view.md#multi-dimensional-image-loading) for
 | 6 | Commit: `feat: Description` or `fix: Description` | Clear, descriptive messages |
 | 7 | Push & create PR | `git push origin feature/branch` |
 
-### Testing Checklist (Manual — No Automated Tests)
+### Testing Checklist
 
 Before opening a PR, verify at minimum:
 
-1. **Launch the app** — no import errors, main window renders
-2. **Golden path** — perform the new feature's primary workflow end-to-end
-3. **Edge cases** — empty state, cancel/escape, large images, missing model files
-4. **Dark mode** — toggle and check rendering of new UI elements
-5. **Save/load roundtrip** — if the feature touches `.iap` project files, save, close, reopen, verify state restored
-6. **Adjacent features** — verify no regression in SAM, annotation tools, export formats
-7. **Inference features** — if touching `sam_utils.py` or `dino_utils.py`, verify the model loads end-to-end (no silent load failure), returns masks/boxes, and the UI stays responsive during inference (timers, redraws, progress dialog cancels keep firing — see ADR-013)
+1. **Smoke tests pass** — `pytest tests/integration/test_smoke.py -v`. This includes the AST-based `test_annotator_window_inline_imports_are_resolvable` which catches stale relative imports inside function bodies after any module move (see ADR-016). A launch that "looks clean" is NOT sufficient — inline imports fail only when the function is called at runtime.
+2. **Launch the app** — no import errors, main window renders
+3. **Golden path** — perform the new feature's primary workflow end-to-end
+4. **Edge cases** — empty state, cancel/escape, large images, missing model files
+5. **Dark mode** — toggle and check rendering of new UI elements
+6. **Save/load roundtrip** — if the feature touches `.iap` project files, save, close, reopen, verify state restored
+7. **Adjacent features** — verify no regression in SAM, annotation tools, export formats
+8. **Inference features** — if touching `sam_utils.py` or `dino_utils.py`, verify the model loads end-to-end (no silent load failure), returns masks/boxes, and the UI stays responsive during inference (timers, redraws, progress dialog cancels keep firing — see ADR-013)
 
 ### arc42 Documentation Update Rules
 
@@ -213,6 +237,8 @@ See [Risks and Technical Debt](docs/11_risks_and_technical_debt.md) for full lis
 | Global | Action |
 |--------|--------|
 | Ctrl+N/O/S | New/Open/Save Project |
+| Ctrl+Shift+= / Ctrl+Shift+- | UI font bigger/smaller (8-24pt, persisted via QSettings) |
+| Ctrl+Shift+0 | Reset UI font size |
 | F1 | Help |
 
 | Canvas | Action |

README.md

@@ -128,9 +128,8 @@ You should see `True` and your GPU name. For other platforms or driver combinati
    - To use SAM2-assisted annotation:
      - Select a model from the "Pick a SAM Model" dropdown. It's recommended to use smaller models like SAM2 tiny or SAM2 small. SAM2 large is not recommended as it may crash the application on systems with limited resources.
      - Note: When you select a model for the first time, the application needs to download it. This process may take a few seconds to a minute, depending on your internet connection speed. Subsequent uses of the same model will be faster as it will already be cached locally, in your working directory.
-     - Click the "SAM-Assisted" button to activate the tool.
-     - Draw a rectangle around objects of interest to allow SAM2 to automatically detect objects.
-     - Note that SAM2 provides various outputs with different scores, and only the top-scoring region will be displayed. If the desired result isn't achieved on the first try, draw again.
+     - Click the "SAM-box" button and draw a rectangle around an object of interest, or click the "SAM-points" button and left-click points inside the object (right-click adds negative points to exclude regions).
+     - SAM2 displays the top-scoring mask as a temporary prediction — press Enter to accept it or Esc to discard it. If the desired result isn't achieved on the first try, draw the box again or adjust the points.
      - For low-quality images where SAM2 may not auto-detect objects, manual tools may be necessary.
      - When SAM2 auto-detect partial objects, use polygon or paint brush tools to manually define the remaining region and use the Merge tool to combine both annotations into one.
      - When SAM2 over-annotates objects, extending the annotation beyond object's boundaries, use the Eraser tool to clean up the edges.

docs/05_building_block_view.md

@@ -28,10 +28,32 @@
 ```
 src/digitalsreeni_image_annotator/
 ├── main.py                        # Entry point, initializes QApplication
-├── annotator_window.py            # ImageAnnotator - main window
-├── image_label.py                 # ImageLabel - custom display widget
-├── sam_utils.py                   # SAMUtils - SAM model management
-└── utils.py                       # Utility functions
+	├── annotator_window.py            # ImageAnnotator - main window orchestrator
+	├── app_settings.py                # QSettings-backed UI prefs (font size, dark mode) — ADR-020
+	├── utils.py                       # Cross-cutting utilities
+	├── core/                          # Constants, annotation utils, image utils
+	│   ├── constants.py
+	│   └── annotation_utils.py
+	├── widgets/
+	│   ├── image_label.py             # ImageLabel - canvas widget; dispatcher
+	│   ├── canvas_context.py          # CanvasContext - narrow read view (ADR-018)
+	│   └── tools/                     # Per-tool handlers (ADR-019)
+	│       ├── base.py                # ToolHandler base
+	│       ├── rectangle_tool.py
+	│       ├── polygon_tool.py
+	│       ├── paint_tool.py
+	│       └── eraser_tool.py
+	├── controllers/                   # Project/Image/SAM/DINO/YOLO/Annotation/Class
+	├── inference/                     # sam_utils.py, dino_utils.py
+	│   ├── sam_utils.py
+	│   └── dino_utils.py
+	├── io/                            # export_formats.py, import_formats.py
+	│   ├── export_formats.py
+	│   └── import_formats.py
+	├── ui/                            # menu_bar, sidebar, theme, stylesheets
+	│   ├── default_stylesheet.py
+	│   └── soft_dark_stylesheet.py
+	└── dialogs/                       # Standalone tool dialogs
 ```
 
 ### ImageAnnotator (annotator_window.py)
@@ -56,27 +78,51 @@ current_slice: str                  # Currently displayed slice
 - `export_annotations()`: Export to various formats
 - `import_annotations()`: Import from COCO/YOLO
 
-### ImageLabel (image_label.py)
+### ImageLabel (widgets/image_label.py)
 
-**Responsibility**: Image display and annotation interaction
+**Responsibility**: Canvas widget — image display, navigation
+(zoom/pan), committed-annotation rendering, SAM bbox/points overlays,
+DINO temp-annotation rendering, polygon edit mode (modal). Per-tool
+mouse/key handling lives in `widgets/tools/*` (see ADR-019); ImageLabel
+dispatches events to the active handler.
 
 **Key Attributes**:
 ```python
-current_tool: str                   # Active annotation tool
+current_tool: str                   # Active annotation tool (route via set_active_tool)
 zoom_factor: float                  # Current zoom level
 annotations: dict                   # Displayed annotations
 class_colors: dict                  # Class color mapping
-temp_paint_mask: np.ndarray         # Temporary paint strokes
+temp_paint_mask: np.ndarray         # In-progress paint stroke (owned by PaintBrushTool)
+temp_eraser_mask: np.ndarray        # In-progress eraser stroke (owned by EraserTool)
+current_rectangle: list             # In-progress rectangle (owned by RectangleTool)
+current_annotation: list            # In-progress polygon points (owned by PolygonTool)
 sam_positive_points: list           # SAM positive points
 sam_negative_points: list           # SAM negative points
+editing_polygon: dict | None        # Polygon being edited (modal sub-state)
+_tools: dict[str, ToolHandler]      # Per-tool handlers
+_ctx: CanvasContext                 # Narrow read view of main-window state (ADR-018)
 ```
 
 **Key Methods**:
-- `mousePressEvent()`: Handle mouse clicks for annotation
-- `mouseMoveEvent()`: Handle mouse dragging
-- `paintEvent()`: Render image and annotations
-- `zoom_in()`, `zoom_out()`: Zoom controls
-- `start_painting()`, `start_erasing()`: Brush tools
+- `mousePressEvent()` / `mouseMoveEvent()` / `mouseReleaseEvent()` /
+  `mouseDoubleClickEvent()`: Ctrl-modifier pan/zoom branches first,
+  then SAM/edit-mode branches, then dispatch to
+  `active_tool_handler.on_mouse_X()`.
+- `keyPressEvent()`: Enter / Escape / Delete / brush-size keys. Modal
+  branches (DINO temp, sam_points, sam_box, editing_polygon)
+  consume first; otherwise routed to `handler.on_enter()` /
+  `on_escape()`.
+- `paintEvent()`: image → committed annotations → editing polygon →
+  SAM overlays → all tool handlers' `paint_overlay()` → tool-size
+  indicator → DINO temp annotations.
+- `set_active_tool(name)`: switches `current_tool` and gives the
+  previous handler a chance to clean up via `deactivate()`.
+- `check_unsaved_changes()`: iterates handlers' `has_unsaved_state()`
+  and prompts the user.
+
+**Communication**: emits ~20 Qt signals connected to controller slots
+in `ImageAnnotator._connect_image_label_signals` (ADR-018). Reads
+main-window state through `CanvasContext`.
 
 ### SAMUtils (sam_utils.py)
 
@@ -147,6 +193,33 @@ DINO's xyxy boxes feed directly into `SAMUtils.apply_sam_predictions_batch()`,
 which returns segmentation polygons (xywh bbox is derived from the polygon at
 export time — see [Cross-cutting Concepts](08_crosscutting_concepts.md)).
 
+## Level 3: Controllers
+
+Seven `QObject` controllers plus an `io_controller` helper module
+carve `ImageAnnotator` into single-responsibility owners that the
+orchestrator delegates to. Each `QObject` controller holds `self.mw
+= main_window` and owns one slice of behaviour; the
+`io_controller` is a thin module of UI-wrapper functions around the
+pure `io/` formatters and does not need to hold state. The
+orchestrator keeps pass-through methods so external call sites
+(menus, signal wiring, the test harness) don't need to reach into
+the controller graph.
+
+| Controller | Responsibility |
+|------------|----------------|
+| `ProjectController` | `.iap` save/load, auto-save, backup/restore, missing-image prompts, window-title sync. Owns the `is_loading_project` autosave guard (load/save round-trip safety, v0.8.12). |
+| `ImageController` | Open / load / switch images and slices. TIFF + CZI loaders, the multi-dim `DimensionDialog`, the `[-ndim:]` axis-slice bug fix from the v0.9.0 era. |
+| `AnnotationController` | Annotation CRUD, list sorting, highlight, edit-mode entry/exit, `finish_polygon`, `finish_rectangle`, `replace_annotations` (eraser path). Validates writes before mutating `all_annotations`. |
+| `ClassController` | Class add / delete / rename / colour / visibility. `update_slice_list_colors`, `is_class_visible`. |
+| `SAMController` | SAM box/points tool lifecycle, debounce timer, `_sam_inference_in_flight` re-entrancy guard (ADR-013), model picker. |
+| `DINOController` | Single + batch detection, batch review navigation, temp-annotation accept/reject, custom-model browse, `DINOReviewEventFilter` ownership (ADR-015). |
+| `YOLOController` | Training menu, `TrainingThread`, prediction dialog, result processing. |
+| `io_controller` *(module-level functions, not a class)* | Thin UI wrappers around the pure `io/export_formats.py` and `io/import_formats.py` modules. |
+
+Communication: `ImageLabel` does not import controllers directly —
+it emits Qt signals (ADR-018) that the orchestrator connects to
+controller slots in `_connect_image_label_signals()`.
+
 ## Level 3: Export/Import Subsystem
 
 ### Export Formats (export_formats.py)
@@ -270,7 +343,9 @@ ImageAnnotator (main window)
     └── launches ──> Tool Dialogs (utilities)
 
 ImageLabel
-    ├── references ──> ImageAnnotator (callbacks)
+    ├── emits signals to ──> ImageAnnotator (writes; see ADR-018)
+    ├── reads via ──> CanvasContext (paint/eraser size, current class,
+    │                  class_mapping, is_class_visible, scroll_area, …)
     └── uses ──> utils (area, bbox calculations)
 
 SAMUtils

docs/06_runtime_view.md

@@ -66,7 +66,7 @@ User presses Enter
     └─> update() to show final annotation
 ```
 
-## SAM-Assisted Annotation
+## SAM-Assisted Annotation (SAM-box / SAM-points)
 
 ```
 User selects SAM model