feat: TextTools v0.3.0 polish pass

- Fix default tab (Clean opens first)
- Add Ctrl+F, Ctrl+H, F3 keyboard shortcuts
- Normalize ascii encoding label to utf-8
- Implement encoding conversion button (F-001)
- Add cursor position + char count to status bar
- Implement Save As
- Persist window geometry + splitter positions via QSettings
- Bump version to 0.3.0

Author: chrisdpurcell

CHANGELOG.md

@@ -9,6 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] — 2026-02-21
+
+### Added
+- Default tab is now Clean (was Find/Replace)
+- Keyboard shortcuts: Ctrl+F (find), Ctrl+H (replace), F3 (find next)
+- Encoding conversion button (F-001): re-saves file as UTF-8
+- Cursor position and character count in status bar
+- Save As (was stubbed)
+- Window geometry and splitter positions persist across sessions (QSettings)
+
+### Fixed
+- Encoding label now shows "utf-8" for ASCII files (ASCII is a subset of UTF-8)
+
+---
+
 ## [0.2.0] - 2026-02-21
 
 ### Added

scripts/live_test.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python
+"""Offscreen smoke test for TextTools.
+
+Exercises the full stack (FileService → ViewModel → View widgets) using Qt's
+offscreen platform — no display or Xvfb required.
+
+Run with:
+    uv run python scripts/live_test.py
+
+Exit code: 0 if all checks pass, 1 if any fail.
+
+QT_QPA_PLATFORM=offscreen: renders widgets in memory; all Qt geometry, text
+cursor, and signal APIs work identically to a real display, but nothing is
+shown on screen. More stable than Xvfb for headless testing because there is
+no input method context to trip over.
+"""
+
+import os
+import sys
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+# Must be set before QApplication is created — do not move below imports.
+os.environ["QT_QPA_PLATFORM"] = "offscreen"
+os.environ["QT_IM_MODULE"] = "none"
+
+# Add project root to sys.path so `src` is importable without install.
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from PySide6.QtWidgets import QApplication  # noqa: E402
+
+from src.main import create_application  # noqa: E402
+
+_pass = 0
+_fail = 0
+
+
+def check(label: str, condition: bool, detail: str = "") -> None:
+    global _pass, _fail
+    if condition:
+        print(f"  PASS  {label}")
+        _pass += 1
+    else:
+        note = f" — {detail}" if detail else ""
+        print(f"  FAIL  {label}{note}")
+        _fail += 1
+
+
+def section(title: str) -> None:
+    print(f"\n{title}")
+    print("─" * len(title))
+
+
+def main() -> None:
+    app = QApplication(sys.argv)
+    window = create_application()
+
+    with TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+
+        # ----------------------------------------------------------------- load
+        section("File Loading")
+
+        # Non-ASCII content (é, ñ) is required for the encoding check:
+        # pure ASCII is correctly detected as "ascii" by chardet (ASCII ⊂ UTF-8).
+        f = tmp_path / "hello.txt"
+        f.write_text("café résumé — live test", encoding="utf-8")
+        window._file_name_edit.setText(str(f))
+        window._viewmodel.load_file(str(f))
+        app.processEvents()
+
+        check(
+            "Editor populated after load",
+            window._plain_text_edit.toPlainText() == "café résumé — live test",
+        )
+        check(
+            "Encoding label shows utf-8",
+            window._encoding_label.text().lower() == "utf-8",
+        )
+        check(
+            "Title bar shows filename",
+            "hello.txt" in window.ui.windowTitle(),
+        )
+        check(
+            "Title bar has no star (clean after load)",
+            "*" not in window.ui.windowTitle(),
+        )
+        check(
+            "Status bar mentions filename",
+            "hello.txt" in window.ui.statusBar().currentMessage(),
+        )
+
+        # ----------------------------------------------------------------- save
+        section("Save")
+
+        out = tmp_path / "out.txt"
+        window._file_name_edit.setText(str(out))
+        window._plain_text_edit.setPlainText("saved content")
+        window._on_save_clicked()
+        app.processEvents()
+
+        check(
+            "File written to disk",
+            out.exists(),
+        )
+        check(
+            "File content matches editor",
+            out.exists() and out.read_text(encoding="utf-8") == "saved content",
+        )
+        check(
+            "Title loses star after save",
+            "*" not in window.ui.windowTitle(),
+        )
+
+        # -------------------------------------------------------------- cleaning
+        section("Text Cleaning (real TextProcessingService)")
+
+        dirty = tmp_path / "dirty.txt"
+        dirty.write_text("hello   \nworld   \n\n", encoding="utf-8")
+        window._file_name_edit.setText(str(dirty))
+        window._viewmodel.load_file(str(dirty))
+        app.processEvents()
+
+        window._trim_cb.setChecked(True)
+        app.processEvents()
+
+        trimmed = window._plain_text_edit.toPlainText()
+        check(
+            "Trim whitespace strips trailing spaces and blank lines",
+            trimmed == "hello\nworld",
+            f"got: {trimmed!r}",
+        )
+
+        window._trim_cb.setChecked(False)
+        app.processEvents()
+
+        # Reload clean content for the next two checks
+        spaces = tmp_path / "spaces.txt"
+        spaces.write_text("a  b   c", encoding="utf-8")
+        window._file_name_edit.setText(str(spaces))
+        window._viewmodel.load_file(str(spaces))
+        app.processEvents()
+
+        window._clean_cb.setChecked(True)
+        app.processEvents()
+
+        collapsed = window._plain_text_edit.toPlainText()
+        check(
+            "Clean whitespace collapses runs of spaces",
+            collapsed == "a b c",
+            f"got: {collapsed!r}",
+        )
+
+        window._clean_cb.setChecked(False)
+        app.processEvents()
+
+        tabs_file = tmp_path / "tabs.txt"
+        tabs_file.write_text("\tindented\n\t\tdouble", encoding="utf-8")
+        window._file_name_edit.setText(str(tabs_file))
+        window._viewmodel.load_file(str(tabs_file))
+        app.processEvents()
+
+        window._remove_tabs_cb.setChecked(True)
+        app.processEvents()
+
+        detabbed = window._plain_text_edit.toPlainText()
+        check(
+            "Remove tabs strips leading indent",
+            detabbed == "indented\ndouble",
+            f"got: {detabbed!r}",
+        )
+
+        window._remove_tabs_cb.setChecked(False)
+        app.processEvents()
+
+        # --------------------------------------------------------------- find
+        section("Find")
+
+        search = tmp_path / "search.txt"
+        search.write_text("the quick brown fox", encoding="utf-8")
+        window._file_name_edit.setText(str(search))
+        window._viewmodel.load_file(str(search))
+        app.processEvents()
+
+        window._find_edit.setText("brown")
+        window._on_find_clicked()
+        selected = window._plain_text_edit.textCursor().selectedText()
+        check(
+            "Find selects matching text",
+            selected == "brown",
+            f"got: {selected!r}",
+        )
+
+        # Wrap test: move cursor to end, search for earlier word
+        cursor = window._plain_text_edit.textCursor()
+        cursor.movePosition(cursor.MoveOperation.End)
+        window._plain_text_edit.setTextCursor(cursor)
+        window._find_edit.setText("quick")
+        window._on_find_clicked()
+        selected = window._plain_text_edit.textCursor().selectedText()
+        check(
+            "Find wraps from end of document",
+            selected == "quick",
+            f"got: {selected!r}",
+        )
+
+        # --------------------------------------------------------- replace all
+        section("Replace All")
+
+        rep = tmp_path / "rep.txt"
+        rep.write_text("cat cat cat", encoding="utf-8")
+        window._file_name_edit.setText(str(rep))
+        window._viewmodel.load_file(str(rep))
+        app.processEvents()
+
+        window._find_edit.setText("cat")
+        window._replace_edit.setText("dog")
+        window._on_replace_all_clicked()
+        app.processEvents()
+
+        result = window._plain_text_edit.toPlainText()
+        check(
+            "Replace All updates all occurrences",
+            result == "dog dog dog",
+            f"got: {result!r}",
+        )
+
+        # ------------------------------------------------------- encoding convert
+        section("Encoding Conversion")
+
+        # rep.txt was loaded as UTF-8; clicking Convert on an already-UTF-8
+        # file must show the "already UTF-8" status message (not save again).
+        window._convert_button.click()
+        app.processEvents()
+        check(
+            "Convert on UTF-8 file shows already-UTF-8 status",
+            "already utf-8" in window.ui.statusBar().currentMessage().lower(),
+        )
+
+    # ----------------------------------------------------------------------- summary
+    total = _pass + _fail
+    print(f"\n{'=' * 42}")
+    if _fail == 0:
+        print(f"All {total} checks passed.")
+    else:
+        print(f"{_pass}/{total} passed — {_fail} FAILED.")
+    print("=" * 42)
+
+    window.ui.close()
+    app.quit()
+    sys.exit(1 if _fail else 0)
+
+
+if __name__ == "__main__":
+    main()

scripts/qt_pilot_launcher.py

@@ -0,0 +1,23 @@
+"""Qt-pilot test launcher — sets QT_IM_MODULE=none before QApplication is created.
+
+Without this, QTest::keyClicks causes a SIGSEGV on headless displays (Xvfb, etc.)
+because there is no input method context. Setting QT_IM_MODULE=none disables the
+input method plugin lookup and prevents the null-pointer dereference.
+
+Use with the qt-pilot MCP tool:
+    launch_app(
+        script_path="scripts/qt_pilot_launcher.py",
+        working_dir="/home/chris/projects/TextTools",
+        python_paths=["/home/chris/projects/TextTools"],
+    )
+"""
+
+import os
+
+# Must be set before QApplication is created — do not move below imports.
+os.environ.setdefault("QT_IM_MODULE", "none")
+
+from src.main import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()

src/services/file_service.py

@@ -80,13 +80,17 @@ def _detect_encoding(raw: bytes) -> str:
 
     Module-level so it can be tested without instantiating FileService.
     Falls back to utf-8 if chardet is unavailable or confidence is too low.
+    Normalizes 'ascii' to 'utf-8' because ASCII is a proper subset of UTF-8
+    and saving as utf-8 is always safe for ASCII content.
     """
     try:
         import chardet  # optional dependency
 
         result = chardet.detect(raw)
         if result["encoding"] and result["confidence"] >= _ENCODING_MIN_CONFIDENCE:
-            return result["encoding"]
+            detected = result["encoding"].lower()
+            # ASCII is a valid subset of UTF-8; normalize to avoid confusing the UI.
+            return "utf-8" if detected == "ascii" else result["encoding"]
     except ImportError:
         logger.debug("chardet not installed; defaulting to utf-8")
     return _ENCODING_FALLBACK

src/utils/constants.py

@@ -1,7 +1,7 @@
 """Utility constants for TextTools."""
 
 APP_NAME = "TextTools"
-APP_VERSION = "0.2.0"
+APP_VERSION = "0.3.0"
 
 DEFAULT_WINDOW_WIDTH = 894
 DEFAULT_WINDOW_HEIGHT = 830

src/viewmodels/main_viewmodel.py

@@ -163,3 +163,41 @@ def replace_all(
         self.content_updated.emit(new_content)
         noun = "occurrence" if count == 1 else "occurrences"
         self.status_changed.emit(f"Replaced {count} {noun}")
+
+    @Slot(str)
+    def convert_to_utf8(self, current_text: str) -> None:
+        """Re-save the current document in UTF-8 encoding.
+
+        Args:
+            current_text: Live editor text from the View. Used as the content
+                to save (preserves unsaved edits).
+
+        No-op when no document is loaded or the file is already UTF-8.
+        Encoding comparison normalises dashes so 'utf-8' and 'utf8' both match.
+        """
+        if self._current_document is None:
+            self.status_changed.emit("No document loaded")
+            return
+        # Normalise: strip dashes and lowercase so 'UTF-8', 'utf-8', 'utf8' all match.
+        # UTF-8-SIG is the chardet name for UTF-8 with a BOM — treat it as already UTF-8
+        # to avoid needlessly re-saving BOM files.
+        current_encoding = self._current_document.encoding.lower().replace("-", "")
+        if current_encoding in {"utf8", "utf8sig"}:
+            self.status_changed.emit("File is already UTF-8")
+            return
+        doc = TextDocument(
+            filepath=self._current_document.filepath,
+            content=current_text,
+            encoding="utf-8",
+        )
+        try:
+            self._file_service.save_file(doc)
+            self._current_document = doc
+            self.encoding_detected.emit("utf-8")
+            self.file_saved.emit(doc.filepath)
+            self.status_changed.emit(f"Converted to UTF-8: {doc.filepath}")
+        except (ValueError, PermissionError, OSError) as e:
+            msg = f"Cannot convert file: {e}"
+            logger.error(msg)
+            self.error_occurred.emit(msg)
+            self.status_changed.emit("Error converting file")