setiastrosuitepro 1.6.0__py3-none-any.whl

setiastro/saspro/bundles.py

@@ -0,0 +1,61 @@
+# pro/bundles.py
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional
+from PyQt6.QtCore import QObject, pyqtSignal
+
+@dataclass
+class ViewBundle:
+    id: str
+    name: str
+    doc_uids: List[str] = field(default_factory=list)  # store stable doc UIDs
+
+class BundleManager(QObject):
+    changed = pyqtSignal()
+    def __init__(self, dm):
+        super().__init__()
+        self.dm = dm
+        self._by_id: Dict[str, ViewBundle] = {}
+
+    def add(self, b: ViewBundle):
+        self._by_id[b.id] = b
+        self.changed.emit()
+
+    def remove(self, bid: str):
+        self._by_id.pop(bid, None)
+        self.changed.emit()
+
+    def get(self, bid: str) -> Optional[ViewBundle]:
+        return self._by_id.get(bid)
+
+    def all(self) -> list[ViewBundle]:
+        return list(self._by_id.values())
+
+    def add_doc(self, bid: str, doc_uid: str):
+        b = self._by_id.get(bid)
+        if not b: return
+        if doc_uid not in b.doc_uids:
+            b.doc_uids.append(doc_uid)
+            self.changed.emit()
+
+    def remove_doc(self, bid: str, doc_uid: str):
+        b = self._by_id.get(bid)
+        if not b: return
+        if doc_uid in b.doc_uids:
+            b.doc_uids.remove(doc_uid)
+            self.changed.emit()
+
+    def docs(self, bid: str):
+        b = self._by_id.get(bid)
+        if not b: return []
+        out = []
+        for uid in b.doc_uids:
+            d = getattr(self.dm, "find_document_by_uid", None)
+            if callable(d):
+                doc = d(uid)
+            else:
+                # fallback: linear scan over open docs if you don't have an index
+                doc = next((x for x in getattr(self.dm, "documents", []) if getattr(x, "uid", None) == uid), None)
+            if doc:
+                out.append(doc)
+        return out

setiastro/saspro/bundles_dock.py

@@ -0,0 +1,114 @@
+# pro/bundles_dock.py
+from __future__ import annotations
+from PyQt6.QtWidgets import QDockWidget, QListWidget, QListWidgetItem, QMenu, QInputDialog
+from PyQt6.QtCore import Qt, QMimeData, QByteArray
+import json
+
+from setiastro.saspro.dnd_mime import MIME_CMD  # you already use this
+
+class BundlesDock(QDockWidget):
+    def __init__(self, mw, bm, pipelines):
+        super().__init__("Bundles", mw)
+        self.mw = mw
+        self.bm = bm
+        self.pipelines = pipelines
+
+        self.list = QListWidget(self)
+        self.list.setSelectionMode(self.list.SelectionMode.SingleSelection)
+        self.list.setAcceptDrops(True)
+        self.list.setDragEnabled(False)
+        self.setWidget(self.list)
+
+        self.setAllowedAreas(Qt.DockWidgetArea.LeftDockWidgetArea | Qt.DockWidgetArea.RightDockWidgetArea)
+        self._refresh()
+        bm.changed.connect(self._refresh)
+
+        self.list.setContextMenuPolicy(Qt.ContextMenuPolicy.CustomContextMenu)
+        self.list.customContextMenuRequested.connect(self._ctx)
+
+    def _refresh(self):
+        self.list.clear()
+        for b in self.bm.all():
+            it = QListWidgetItem(f"{b.name}  ({len(b.doc_uids)} views)")
+            it.setData(Qt.ItemDataRole.UserRole, b.id)
+            self.list.addItem(it)
+
+    def _ctx(self, pos):
+        it = self.list.itemAt(pos)
+        m = QMenu(self)
+        m.addAction("New Bundle…", self._new_bundle)
+        if it:
+            bid = it.data(Qt.ItemDataRole.UserRole)
+            m.addSeparator()
+            m.addAction("Rename…", lambda: self._rename(bid))
+            m.addAction("Delete", lambda: self._delete(bid))
+            m.addSeparator()
+            m.addAction("Run Pipeline…", lambda: self._pick_and_run(bid))
+        m.exec(self.list.mapToGlobal(pos))
+
+    def _new_bundle(self):
+        name, ok = QInputDialog.getText(self, "New Bundle", "Name:")
+        if not ok or not name.strip(): return
+        import uuid
+        from setiastro.saspro.bundles import ViewBundle
+        self.bm.add(ViewBundle(id=uuid.uuid4().hex, name=name.strip()))
+
+    def _rename(self, bid):
+        b = self.bm.get(bid); 
+        if not b: return
+        name, ok = QInputDialog.getText(self, "Rename Bundle", "Name:", text=b.name)
+        if ok and name.strip():
+            b.name = name.strip()
+            self.bm.changed.emit()
+
+    def _delete(self, bid):
+        self.bm.remove(bid)
+
+    # --- DnD: add docs or run commands ---
+    def dragEnterEvent(self, e):
+        if e.mimeData().hasFormat(MIME_CMD):
+            e.acceptProposedAction(); return
+        # Let your explorer/subwindow provide a doc UID mime if you have one; example below:
+        if e.mimeData().hasFormat("application/x-saspro-doc-uid"):
+            e.acceptProposedAction(); return
+        e.ignore()
+
+    def dropEvent(self, e):
+        it = self.list.itemAt(e.position().toPoint())
+        if not it:
+            e.ignore(); return
+        bid = it.data(Qt.ItemDataRole.UserRole)
+
+        md: QMimeData = e.mimeData()
+        # 1) drop a command/pipeline onto a bundle -> run across all docs in the bundle
+        if md.hasFormat(MIME_CMD):
+            try:
+                payload = json.loads(bytes(md.data(MIME_CMD)).decode("utf-8"))
+            except Exception:
+                e.ignore(); return
+            docs = self.bm.docs(bid)
+            if not docs:
+                e.ignore(); return
+            # Pipeline support via "pipeline:<id>" (see MW patch below)
+            self.mw._run_payload_on_docs(payload, docs)
+            e.acceptProposedAction(); return
+
+        # 2) drop doc(s) onto a bundle -> add
+        if md.hasFormat("application/x-saspro-doc-uid"):
+            uid = bytes(md.data("application/x-saspro-doc-uid")).decode("utf-8")
+            self.bm.add_doc(bid, uid)
+            e.acceptProposedAction(); return
+
+        e.ignore()
+
+    # quick picker to run a pipeline without DnD
+    def _pick_and_run(self, bid):
+        plist = self.pipelines.all()
+        if not plist:
+            return
+        names = [p.name for p in plist]
+        i, ok = QInputDialog.getItem(self, "Run Pipeline", "Pick:", names, 0, False)
+        if not ok: return
+        p = plist[names.index(i)]
+        payload = {"command_id": f"pipeline:{p.id}", "preset": {}}
+        self.mw._run_payload_on_docs(payload, self.bm.docs(bid))

setiastro/saspro/cheat_sheet.py

@@ -0,0 +1,168 @@
+# pro/cheat_sheet.py
+"""
+Keyboard shortcut cheat sheet dialog.
+
+Displays all keyboard shortcuts and mouse gestures in a tabbed dialog.
+"""
+
+from PyQt6.QtWidgets import (
+    QDialog, QVBoxLayout, QHBoxLayout, QTabWidget, QWidget,
+    QTableWidget, QTableWidgetItem, QHeaderView, QPushButton,
+    QApplication, QMessageBox
+)
+from PyQt6.QtGui import QAction, QShortcut, QKeySequence
+
+
+def _qs_to_str(seq: QKeySequence) -> str:
+    """Convert a QKeySequence to a human-readable string."""
+    return seq.toString(QKeySequence.SequenceFormat.NativeText).strip()
+
+
+def _clean_text(text: str) -> str:
+    """Remove common Unicode decoration from text."""
+    if not text:
+        return ""
+    # Remove common ellipsis, arrows, etc.
+    return text.replace("…", "").replace("→", "->").replace("←", "<-").strip()
+
+
+def _uniq_keep_order(items):
+    """Return unique items preserving order."""
+    seen = set()
+    out = []
+    for x in items:
+        if x in seen:
+            continue
+        seen.add(x)
+        out.append(x)
+    return out
+
+
+def _seqs_for_action(act: QAction):
+    """Get non-empty key sequences for an action."""
+    seqs = [s for s in act.shortcuts() or []] or ([act.shortcut()] if act.shortcut() else [])
+    return [s for s in seqs if not s.isEmpty()]
+
+
+def _where_for_action(act: QAction) -> str:
+    """Determine where an action is available (Menus/Toolbar or Window)."""
+    if act.parent():
+        pn = act.parent().__class__.__name__
+        if pn.startswith("QMenu") or pn.startswith("QToolBar"):
+            return "Menus/Toolbar"
+    return "Window"
+
+
+def _describe_action(act: QAction) -> str:
+    """Get a human-readable description for an action."""
+    return _clean_text(act.statusTip() or act.toolTip() or act.text() or act.objectName() or "Action")
+
+
+def _describe_shortcut(sc: QShortcut) -> str:
+    """Get a human-readable description for a shortcut."""
+    return _clean_text(sc.property("hint") or sc.whatsThis() or sc.objectName() or "Shortcut")
+
+
+def _where_for_shortcut(sc: QShortcut) -> str:
+    """Determine where a shortcut is available."""
+    par = sc.parent()
+    return par.__class__.__name__ if par is not None else "Window"
+
+
+class CheatSheetDialog(QDialog):
+    """
+    Dialog showing all keyboard shortcuts and mouse gestures.
+    
+    Displays two tabs:
+    - Keyboard shortcuts (from QActions)
+    - Mouse/drag gestures
+    """
+    
+    def __init__(self, parent, keyboard_rows, gesture_rows):
+        super().__init__(parent)
+        self.setWindowTitle("Keyboard Shortcut Cheat Sheet")
+        self.resize(780, 520)
+        
+        self._keyboard_rows = keyboard_rows
+        self._gesture_rows = gesture_rows
+
+        tabs = QTabWidget(self)
+
+        # --- Keyboard tab ---
+        pg_keys = QWidget(tabs)
+        v1 = QVBoxLayout(pg_keys)
+        tbl_keys = QTableWidget(0, 3, pg_keys)
+        tbl_keys.setHorizontalHeaderLabels(["Shortcut", "Action", "Where"])
+        tbl_keys.verticalHeader().setVisible(False)
+        tbl_keys.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        tbl_keys.setSelectionBehavior(QTableWidget.SelectionBehavior.SelectRows)
+        tbl_keys.setSelectionMode(QTableWidget.SelectionMode.SingleSelection)
+        tbl_keys.horizontalHeader().setSectionResizeMode(0, QHeaderView.ResizeMode.ResizeToContents)
+        tbl_keys.horizontalHeader().setSectionResizeMode(1, QHeaderView.ResizeMode.Stretch)
+        tbl_keys.horizontalHeader().setSectionResizeMode(2, QHeaderView.ResizeMode.ResizeToContents)
+        v1.addWidget(tbl_keys)
+
+        # Populate keyboard shortcuts
+        for s, action, where in keyboard_rows:
+            r = tbl_keys.rowCount()
+            tbl_keys.insertRow(r)
+            tbl_keys.setItem(r, 0, QTableWidgetItem(s))
+            tbl_keys.setItem(r, 1, QTableWidgetItem(action))
+            tbl_keys.setItem(r, 2, QTableWidgetItem(where))
+
+        # --- Mouse/Drag tab ---
+        pg_mouse = QWidget(tabs)
+        v2 = QVBoxLayout(pg_mouse)
+        tbl_mouse = QTableWidget(0, 3, pg_mouse)
+        tbl_mouse.setHorizontalHeaderLabels(["Gesture", "Context", "Effect"])
+        tbl_mouse.verticalHeader().setVisible(False)
+        tbl_mouse.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        tbl_mouse.setSelectionBehavior(QTableWidget.SelectionBehavior.SelectRows)
+        tbl_mouse.setSelectionMode(QTableWidget.SelectionMode.SingleSelection)
+        tbl_mouse.horizontalHeader().setSectionResizeMode(0, QHeaderView.ResizeMode.ResizeToContents)
+        tbl_mouse.horizontalHeader().setSectionResizeMode(1, QHeaderView.ResizeMode.ResizeToContents)
+        tbl_mouse.horizontalHeader().setSectionResizeMode(2, QHeaderView.ResizeMode.Stretch)
+        v2.addWidget(tbl_mouse)
+
+        # Populate mouse gestures
+        for gesture, context, effect in gesture_rows:
+            r = tbl_mouse.rowCount()
+            tbl_mouse.insertRow(r)
+            tbl_mouse.setItem(r, 0, QTableWidgetItem(gesture))
+            tbl_mouse.setItem(r, 1, QTableWidgetItem(context))
+            tbl_mouse.setItem(r, 2, QTableWidgetItem(effect))
+
+        tabs.addTab(pg_keys, "Base Keyboard")
+        tabs.addTab(pg_mouse, "Additional & Mouse & Drag")
+
+        # Buttons
+        btns = QHBoxLayout()
+        btns.addStretch(1)
+
+        b_copy = QPushButton("Copy")
+        b_copy.clicked.connect(self._copy_all)
+        b_close = QPushButton("Close")
+        b_close.clicked.connect(self.accept)
+        btns.addWidget(b_copy)
+        btns.addWidget(b_close)
+
+        top = QVBoxLayout(self)
+        top.addWidget(tabs)
+        top.addLayout(btns)
+
+    def _copy_all(self):
+        """Copy all shortcuts to clipboard as plain text."""
+        lines = []
+        lines.append("== Keyboard ==")
+        for s, a, w in self._keyboard_rows:
+            lines.append(f"{s:20}  {a}  [{w}]")
+        lines.append("")
+        lines.append("== Mouse & Drag ==")
+        for g, c, e in self._gesture_rows:
+            lines.append(f"{g:24}  {c:18}  {e}")
+        QApplication.clipboard().setText("\n".join(lines))
+        QMessageBox.information(self, "Copied", "Cheat sheet copied to clipboard.")
+
+
+# Legacy alias for backward compatibility
+_CheatSheetDialog = CheatSheetDialog

setiastro/saspro/clahe.py

@@ -0,0 +1,342 @@
+# pro/clahe.py
+from __future__ import annotations
+import numpy as np
+import cv2
+
+from PyQt6.QtCore import Qt, QTimer
+from PyQt6.QtGui import QImage, QPixmap, QIcon
+from PyQt6.QtWidgets import (
+    QDialog, QVBoxLayout, QHBoxLayout, QGroupBox, QGridLayout,
+    QLabel, QPushButton, QSlider, QGraphicsScene,
+    QGraphicsPixmapItem, QMessageBox
+)
+
+# Import centralized widgets
+from setiastro.saspro.widgets.graphics_views import ZoomableGraphicsView
+from setiastro.saspro.widgets.image_utils import extract_mask_resized as _get_active_mask_resized
+from setiastro.saspro.widgets.themed_buttons import themed_toolbtn
+
+
+# ----------------------- Core -----------------------
+def apply_clahe(image: np.ndarray, clip_limit: float = 2.0, tile_grid_size: tuple = (8, 8)) -> np.ndarray:
+    # ... (unchanged)
+    if image is None:
+        raise ValueError("image is None")
+    arr = np.asarray(image, dtype=np.float32)
+    arr = np.clip(arr, 0.0, 1.0)
+    was_hw1 = (arr.ndim == 3 and arr.shape[2] == 1)
+    if arr.ndim == 3 and arr.shape[2] == 3:
+        lab = cv2.cvtColor((arr * 255.0).astype(np.uint8), cv2.COLOR_RGB2LAB)
+        l, a, b = cv2.split(lab)
+        clahe = cv2.createCLAHE(clipLimit=float(clip_limit), tileGridSize=tuple(tile_grid_size))
+        cl = clahe.apply(l)
+        limg = cv2.merge((cl, a, b))
+        enhanced = cv2.cvtColor(limg, cv2.COLOR_LAB2RGB).astype(np.float32) / 255.0
+        return np.clip(enhanced, 0.0, 1.0)
+    mono = arr.squeeze()
+    clahe = cv2.createCLAHE(clipLimit=float(clip_limit), tileGridSize=tuple(tile_grid_size))
+    cl = clahe.apply((mono * 255.0).astype(np.uint8)).astype(np.float32) / 255.0
+    cl = np.clip(cl, 0.0, 1.0)
+    if was_hw1:
+        cl = cl[..., None]
+    return cl
+
+# Note: _get_active_mask_resized imported from setiastro.saspro.widgets.image_utils
+
+def apply_clahe_to_doc(doc, preset: dict | None):
+    """
+    Apply CLAHE to doc.image using a preset.
+
+    Backward compatible:
+      - old presets: {"clip_limit": 2.0, "tile": 8}  # tile count across min dimension
+      - new presets: {"clip_limit": 2.0, "tile_px": 128}  # tile size in pixels
+    """
+    if doc is None or getattr(doc, "image", None) is None:
+        raise RuntimeError("Document has no image.")
+
+    img = np.asarray(doc.image)
+
+    # --- preset decode (supports old + new) ---
+    p = preset or {}
+    clip = float(p.get("clip_limit", 2.0))
+
+    # Resolve tile_grid_size for OpenCV
+    if "tile_px" in p:
+        tile_px = int(p.get("tile_px", 128))
+        h, w = img.shape[:2]
+        s = float(min(h, w))
+        tile_px = max(8, tile_px)
+        n = int(round(s / float(tile_px)))
+        n = max(2, min(n, 128))
+        tile_grid = (n, n)
+    else:
+        # legacy: treat "tile" as OpenCV tileGridSize count (tiles across)
+        tile = int(p.get("tile", 8))
+        tile = max(2, min(tile, 128))
+        tile_grid = (tile, tile)
+
+    out = apply_clahe(img, clip_limit=clip, tile_grid_size=tile_grid)
+    out = np.clip(out, 0.0, 1.0).astype(np.float32, copy=False)
+
+    # Blend with active mask if present
+    H, W = out.shape[:2]
+    m = _get_active_mask_resized(doc, H, W)
+    if m is not None:
+        base = np.asarray(doc.image, dtype=np.float32)
+        if base.dtype.kind in "ui":
+            maxv = float(np.iinfo(base.dtype).max)
+            base = base / max(1.0, maxv)
+        else:
+            base = np.clip(base, 0.0, 1.0)
+
+        if out.ndim == 3:
+            if base.ndim == 2:
+                base = base[:, :, None].repeat(out.shape[2], axis=2)
+            elif base.ndim == 3 and base.shape[2] == 1:
+                base = base.repeat(out.shape[2], axis=2)
+            M = np.repeat(m[:, :, None], out.shape[2], axis=2).astype(np.float32)
+            out = np.clip(base * (1.0 - M) + out * M, 0.0, 1.0)
+        else:
+            if base.ndim == 3 and base.shape[2] == 1:
+                base = base.squeeze(axis=2)
+            out = np.clip(base * (1.0 - m) + out * m, 0.0, 1.0)
+
+    # Commit
+    if hasattr(doc, "set_image"):
+        doc.set_image(out, step_name="CLAHE")
+    elif hasattr(doc, "apply_numpy"):
+        doc.apply_numpy(out, step_name="CLAHE")
+    else:
+        doc.image = out
+
+# ----------------------- Dialog -----------------------
+class CLAHEDialogPro(QDialog):
+    def __init__(self, parent, doc, icon: QIcon | None = None):
+        super().__init__(parent)
+        self.setWindowTitle("CLAHE")
+        if icon:
+            try: self.setWindowIcon(icon)
+            except Exception as e:
+                import logging
+                logging.debug(f"Exception suppressed: {type(e).__name__}: {e}")
+
+        self.doc = doc
+        self.orig = np.clip(np.asarray(doc.image, dtype=np.float32), 0.0, 1.0)
+        disp = self.orig
+        if disp.ndim == 2: disp = disp[..., None].repeat(3, axis=2)
+        elif disp.ndim == 3 and disp.shape[2] == 1: disp = disp.repeat(3, axis=2)
+        self._disp_base = disp
+
+        v = QVBoxLayout(self)
+
+        # ---- Params (unchanged) ----
+        grp = QGroupBox("CLAHE Parameters"); grid = QGridLayout(grp)
+        self.s_clip = QSlider(Qt.Orientation.Horizontal); self.s_clip.setRange(1, 40); self.s_clip.setValue(20)
+        self.lbl_clip = QLabel("2.0")
+        self.s_clip.valueChanged.connect(lambda val: self.lbl_clip.setText(f"{val/10.0:.1f}"))
+        self.s_clip.valueChanged.connect(self._debounce_preview)
+
+        # tile size slider (pixels) — intuitive control
+        self.s_tile = QSlider(Qt.Orientation.Horizontal)
+        self.s_tile.setRange(8, 512)          # 4 is pointless; you clamp to >=8 anyway
+        self.s_tile.setSingleStep(8)
+        self.s_tile.setPageStep(64)
+        self.s_tile.setValue(128)             # nice default
+        self.s_tile.setToolTip("CLAHE tile size in pixels (larger = coarser, smaller = finer).")
+
+        self.lbl_tile = QLabel("128 px")
+        self.lbl_tile.setToolTip(self.s_tile.toolTip())
+
+        self.s_tile.valueChanged.connect(lambda v: self.lbl_tile.setText(f"{v} px"))
+        self.s_tile.valueChanged.connect(self._debounce_preview)
+
+        grid.addWidget(QLabel("Tile Size (px):"), 1, 0)
+        grid.addWidget(self.s_tile, 1, 1)
+        grid.addWidget(self.lbl_tile, 1, 2)
+
+
+
+        grid.addWidget(QLabel("Clip Limit:"), 0, 0); grid.addWidget(self.s_clip, 0, 1); grid.addWidget(self.lbl_clip, 0, 2)
+
+        v.addWidget(grp)
+
+        # ---- Preview with zoom/pan ----
+        self.scene = QGraphicsScene(self)
+        self.view  = ZoomableGraphicsView(self.scene)
+        self.view.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.pix   = QGraphicsPixmapItem()
+        self.scene.addItem(self.pix)
+        v.addWidget(self.view, 1)
+
+        # ---- Zoom bar ----
+        # ---- Zoom bar (themed) ----
+        z = QHBoxLayout()
+        z.addStretch(1)
+
+        self.btn_zoom_in  = themed_toolbtn("zoom-in", "Zoom In")
+        self.btn_zoom_out = themed_toolbtn("zoom-out", "Zoom Out")
+        self.btn_zoom_fit = themed_toolbtn("zoom-fit-best", "Fit to Preview")
+
+        self.btn_zoom_in.clicked.connect(self.view.zoom_in)
+        self.btn_zoom_out.clicked.connect(self.view.zoom_out)
+        self.btn_zoom_fit.clicked.connect(lambda: self.view.fit_to_item(self.pix))
+
+        z.addWidget(self.btn_zoom_in)
+        z.addWidget(self.btn_zoom_out)
+        z.addWidget(self.btn_zoom_fit)
+
+        v.addLayout(z)
+
+
+        # ---- Buttons (unchanged) ----
+        row = QHBoxLayout()
+        self.btn_apply = QPushButton("Apply");  self.btn_apply.clicked.connect(self._apply)
+        self.btn_reset = QPushButton("Reset");  self.btn_reset.clicked.connect(self._reset)
+        self.btn_close = QPushButton("Cancel"); self.btn_close.clicked.connect(self.reject)
+        row.addStretch(1); row.addWidget(self.btn_apply); row.addWidget(self.btn_reset); row.addWidget(self.btn_close)
+        v.addLayout(row)
+
+        self._timer = QTimer(self); self._timer.setSingleShot(True); self._timer.timeout.connect(self._update_preview)
+
+        self._set_pix(self._disp_base)
+        self._update_preview()
+        # initial fit
+        self.view.fit_to_item(self.pix)
+
+    def _debounce_preview(self): self._timer.start(250)
+
+    def _set_pix(self, rgb):
+        arr = (np.clip(rgb, 0, 1) * 255).astype(np.uint8)
+        h, w, _ = arr.shape
+        q = QImage(arr.data, w, h, 3*w, QImage.Format.Format_RGB888)
+        self.pix.setPixmap(QPixmap.fromImage(q))
+        self.scene.setSceneRect(self.pix.boundingRect())
+
+    def _update_preview(self):
+        clip = self.s_clip.value() / 10.0
+        tile_px = int(self.s_tile.value())
+
+        try:
+            tile_grid = self._tile_grid_from_px(tile_px, self._disp_base.shape[:2])
+
+            out = apply_clahe(
+                self._disp_base,
+                clip_limit=float(clip),
+                tile_grid_size=tile_grid
+            )
+
+            # Respect active mask (preview works on _disp_base size)
+            H, W = out.shape[:2]
+            m = _get_active_mask_resized(self.doc, H, W)
+            if m is not None:
+                if out.ndim == 3:
+                    M = np.repeat(m[:, :, None], out.shape[2], axis=2).astype(np.float32)
+                else:
+                    M = m.astype(np.float32)
+
+                base = self._disp_base.astype(np.float32, copy=False)
+                out = np.clip(base * (1.0 - M) + out * M, 0.0, 1.0)
+
+            self._set_pix(out)
+            self._preview = out
+
+        except Exception as e:
+            QMessageBox.warning(self, "CLAHE", f"Preview failed:\n{e}")
+
+
+    def _apply(self):
+        try:
+            clip = float(self.s_clip.value() / 10.0)
+            tile_px = int(self.s_tile.value())
+
+            tile_grid = self._tile_grid_from_px(tile_px, self.orig.shape[:2])
+
+            out = apply_clahe(
+                self.orig,
+                clip_limit=clip,
+                tile_grid_size=tile_grid
+            )
+            out = np.clip(out, 0.0, 1.0).astype(np.float32, copy=False)
+
+            # Mask-respectful commit
+            H, W = out.shape[:2]
+            m = _get_active_mask_resized(self.doc, H, W)
+            if m is not None:
+                base = np.asarray(self.doc.image, dtype=np.float32)
+
+                # Normalize base into [0..1] for blending
+                if base.dtype.kind in "ui":
+                    maxv = float(np.iinfo(base.dtype).max)
+                    base = base / max(1.0, maxv)
+                else:
+                    base = np.clip(base, 0.0, 1.0)
+
+                if out.ndim == 3:
+                    if base.ndim == 2:
+                        base = base[:, :, None].repeat(out.shape[2], axis=2)
+                    elif base.ndim == 3 and base.shape[2] == 1:
+                        base = base.repeat(out.shape[2], axis=2)
+
+                    M = np.repeat(m[:, :, None], out.shape[2], axis=2).astype(np.float32)
+                    out = np.clip(base * (1.0 - M) + out * M, 0.0, 1.0)
+                else:
+                    if base.ndim == 3 and base.shape[2] == 1:
+                        base = base.squeeze(axis=2)
+                    out = np.clip(base * (1.0 - m) + out * m, 0.0, 1.0)
+
+                out = out.astype(np.float32, copy=False)
+
+            # Commit to document
+            if hasattr(self.doc, "set_image"):
+                self.doc.set_image(out, step_name="CLAHE")
+            elif hasattr(self.doc, "apply_numpy"):
+                self.doc.apply_numpy(out, step_name="CLAHE")
+            else:
+                self.doc.image = out
+
+            # ── Register as last_headless_command for replay ─────────────
+            try:
+                main = self.parent()
+                if main is not None:
+                    preset = {
+                        "clip_limit": float(clip),
+                        "tile_px": int(tile_px),   # NEW, intuitive
+                        # (optional debug)
+                        # "tile": int(tile_grid[0]),
+                    }
+                    payload = {"command_id": "clahe", "preset": dict(preset)}
+                    setattr(main, "_last_headless_command", payload)
+
+                    try:
+                        if hasattr(main, "_log"):
+                            main._log(
+                                f"[Replay] Registered CLAHE as last action "
+                                f"(clip_limit={preset['clip_limit']}, tile_px={preset['tile_px']})"
+                            )
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+            # ─────────────────────────────────────────────────────────────
+
+            self.accept()
+
+        except Exception as e:
+            QMessageBox.critical(self, "CLAHE", f"Failed to apply:\n{e}")
+
+    def _tile_grid_from_px(self, tile_px: int, hw: tuple[int, int]) -> tuple[int, int]:
+        """
+        Convert desired tile size (pixels) into OpenCV tileGridSize=(n,n)
+        where n is number of tiles across the *min dimension*.
+        """
+        h, w = hw
+        s = float(min(h, w))
+        tile_px = max(8, int(tile_px))
+        n = int(round(s / float(tile_px)))
+        n = max(2, min(n, 128))
+        return (n, n)
+
+    def _reset(self):
+        self.s_clip.setValue(20); self.s_tile.setValue(8)
+        self._set_pix(self._disp_base)
+        self.view.fit_to_item(self.pix)