cjm-session-scratchpad-qt 0.0.1__tar.gz

cjm_session_scratchpad_qt-0.0.1/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: cjm-session-scratchpad-qt
+Version: 0.0.1
+Summary: The session scratchpad: composition seat v0 of the seat family (DEC 2a062aff + ea85eab7). A model-agnostic Qt surface for composing LLM session messages in markdown — session-key file naming, one-key edit/rendered toggle with position stability, autosave with atomic writes, wrap-selection formatting on the KeymapRegistry lane. Designed for accretion; born on-graph.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-session-scratchpad-qt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: cjm-substrate-qt-kit>=0.0.2
+Requires-Dist: PySide6
+
+# cjm-session-scratchpad-qt
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+The session scratchpad — composition seat v0 of the seat family (DECs 2a062aff + ea85eab7). A model-agnostic Qt surface for composing LLM session messages in markdown: session-key file naming from .cjm/current-session (kills the copy-previous + rename rituals), a one-key edit/rendered toggle held position-stable in both directions by per-block source-line anchors in the owned markdown->HTML pipeline, autosave-only persistence (debounced idle + toggle/focus-loss/close, atomic writes, watcher guard — no dialogs), and wrap-selection formatting verbs on the KeymapRegistry lane. Designed for accretion: live-session feature filings land on-graph and build in later sittings.
+
+## Modules
+
+- **`cjm_session_scratchpad_qt.__init__`** — Session scratchpad — composition seat v0 (DEC 2a062aff + ea85eab7). Model-agnostic by design: any LLM session's message composition surface.
+- **`cjm_session_scratchpad_qt.app`** — The scratchpad shell: composition seat v0 (DECs 2a062aff + ea85eab7).
+- **`cjm_session_scratchpad_qt.appv2`** — The graph-rung scratchpad shell: composition seat v2 (DEC 6e76c120).
+- **`cjm_session_scratchpad_qt.cli`** — CLI entry for the session scratchpad (console script `cjm-session-scratchpad-qt`).
+- **`cjm_session_scratchpad_qt.files`** — Session-aware file resolution (DEC ea85eab7 pts 1-2).
+- **`cjm_session_scratchpad_qt.graph`** — One open graph behind the scratchpad — the workbench GraphSession pattern
+- **`cjm_session_scratchpad_qt.manifest`** — Pending-send manifests + pull-time reconciliation (DEC fc6a0cdc pt 5).
+- **`cjm_session_scratchpad_qt.render`** — The owned markdown -> HTML pipeline (DEC ea85eab7 pt 4).
+- **`cjm_session_scratchpad_qt.textops`** — Wrap-selection formatting operators (scope DEC 2a062aff pt 4) + the v2
+- **`cjm_session_scratchpad_qt.timeline`** — Interleaved timeline derivation — the pure half of the v2 reading view.
+- **`cjm_session_scratchpad_qt.timeline_html`** — Timeline HTML assembly — the pure presentation half of the v2 reading view.
+- **`cjm_session_scratchpad_qt.watcher`** — Transcript-dir change detection — the sleep-first mtime poll's pure half.
+
+## API
+
+### `cjm_session_scratchpad_qt.app`
+
+- `Editor` _class_ — The source pane, with line-addressed viewport access for the toggle.
+- `ScratchpadWindow` _class_ — One session file behind an edit/rendered toggle.
+- `block_line_map` _function_ — Scan a rendered document for the renderer's Lxx anchors:
+- `mono_family` _function_ — The rendered code font: the theme's mono token, else the system
+
+### `cjm_session_scratchpad_qt.appv2`
+
+- `GraphScratchpadWindow` _class_ — One session spine behind a timeline + part-composer.
+- `LanguageBar` _class_ — The fence-language mini-bar: a completer-backed field; Enter applies,
+- `SessionPickerDialog` _class_ — The open-session gesture's chooser: filterable Session list, newest
+
+### `cjm_session_scratchpad_qt.cli`
+
+- `build_parser` _function_
+- `main` _function_
+
+### `cjm_session_scratchpad_qt.files`
+
+- `Target` _class_
+- `atomic_write` _function_ — temp + rename in the target dir: a mid-session agent read never sees
+- `ensure_file` _function_ — Create the file blank if missing (sessions are born blank now);
+- `find_session_key` _function_ — Walk up from `start` for the nearest `.cjm/current-session` pointer.
+- `find_session_root` _function_ — The nearest pointer AND the project directory that owns it:
+- `most_recent` _function_ — Newest markdown file by mtime (the absent-pointer fallback).
+- `parse_key_time` _function_ — A session key is its mint timestamp; None for legacy/free-form names.
+- `resolve_target` _function_ — The launch contract: explicit path wins; otherwise the session
+
+### `cjm_session_scratchpad_qt.graph`
+
+- `ScratchpadSession` _class_ — Sync facade over the projection layer for ONE session's scratchpad:
+- `default_transcript_dir` _function_ — The harness transcript dir for a project: `~/.claude/projects/<slug>`,
+- `part_payload` _function_ — A composer part's mint/journal payload: composer-minted uuid (the
+
+### `cjm_session_scratchpad_qt.manifest`
+
+- `PendingSend` _class_ — One recorded compose-send awaiting its transcript echo.
+- `compose_text` _function_ — The outgoing message: parts joined as paragraphs, outer whitespace trimmed.
+- `load_pending` _function_ — Read manifests; a missing or unreadable sidecar is an empty list.
+- `manifest_path` _function_ — The session's pending-send sidecar.
+- `reconcile` _function_ — Match manifests against pulled user messages by EXACT text.
+- `save_pending` _function_ — Persist manifests atomically (temp + rename; a concurrent read never
+
+### `cjm_session_scratchpad_qt.render`
+
+- `RenderResult` _class_
+- `nearest_anchor` _function_ — The anchor line for a source position: greatest anchor <= line
+- `render_html` _function_ — Render markdown to QTextBrowser-ready HTML with per-block source-line
+
+### `cjm_session_scratchpad_qt.textops`
+
+- `WrapResult` _class_
+- `fence_selection` _function_ — Toggle a code fence around the selected lines. An already-fenced block
+- `toggle_list` _function_ — Toggle list markers on the selected lines: strip when every non-blank
+- `wrap_selection` _function_ — Toggle `marker` around [start, end) of `document`.
+
+### `cjm_session_scratchpad_qt.timeline`
+
+- `TimelineEntry` _class_ — One timeline row, presentation-ready.
+- `build_timeline` _function_ — Derive the interleaved timeline: active-path status + birth-class flags,
+- `timeline_blocks` _function_ — Group consecutive off-path entries for the superseded-branch chip:
+
+### `cjm_session_scratchpad_qt.timeline_html`
+
+- `build_timeline_html` _function_ — The whole timeline document: cards separated by rules, consecutive
+- `card_html` _function_ — One message card: anchored header line (identity + affordances) +
+- `lane_filter` _function_ — The lane views: composition = composer-born, transcript = pulled.
+- `linkify_ids` _function_ — Wrap full node/source ids appearing as text in jump:// links —
+- `test_clock_renders_local_time` _function_
+
+### `cjm_session_scratchpad_qt.watcher`
+
+- `DirWatch` _class_ — Cheap (mtime, size) fingerprint over a transcript dir's *.jsonl.
+
+## Dependencies
+
+**Depends on:** `PySide6`, `cjm-substrate-qt-kit`

cjm_session_scratchpad_qt-0.0.1/README.md

@@ -0,0 +1,101 @@
+# cjm-session-scratchpad-qt
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+The session scratchpad — composition seat v0 of the seat family (DECs 2a062aff + ea85eab7). A model-agnostic Qt surface for composing LLM session messages in markdown: session-key file naming from .cjm/current-session (kills the copy-previous + rename rituals), a one-key edit/rendered toggle held position-stable in both directions by per-block source-line anchors in the owned markdown->HTML pipeline, autosave-only persistence (debounced idle + toggle/focus-loss/close, atomic writes, watcher guard — no dialogs), and wrap-selection formatting verbs on the KeymapRegistry lane. Designed for accretion: live-session feature filings land on-graph and build in later sittings.
+
+## Modules
+
+- **`cjm_session_scratchpad_qt.__init__`** — Session scratchpad — composition seat v0 (DEC 2a062aff + ea85eab7). Model-agnostic by design: any LLM session's message composition surface.
+- **`cjm_session_scratchpad_qt.app`** — The scratchpad shell: composition seat v0 (DECs 2a062aff + ea85eab7).
+- **`cjm_session_scratchpad_qt.appv2`** — The graph-rung scratchpad shell: composition seat v2 (DEC 6e76c120).
+- **`cjm_session_scratchpad_qt.cli`** — CLI entry for the session scratchpad (console script `cjm-session-scratchpad-qt`).
+- **`cjm_session_scratchpad_qt.files`** — Session-aware file resolution (DEC ea85eab7 pts 1-2).
+- **`cjm_session_scratchpad_qt.graph`** — One open graph behind the scratchpad — the workbench GraphSession pattern
+- **`cjm_session_scratchpad_qt.manifest`** — Pending-send manifests + pull-time reconciliation (DEC fc6a0cdc pt 5).
+- **`cjm_session_scratchpad_qt.render`** — The owned markdown -> HTML pipeline (DEC ea85eab7 pt 4).
+- **`cjm_session_scratchpad_qt.textops`** — Wrap-selection formatting operators (scope DEC 2a062aff pt 4) + the v2
+- **`cjm_session_scratchpad_qt.timeline`** — Interleaved timeline derivation — the pure half of the v2 reading view.
+- **`cjm_session_scratchpad_qt.timeline_html`** — Timeline HTML assembly — the pure presentation half of the v2 reading view.
+- **`cjm_session_scratchpad_qt.watcher`** — Transcript-dir change detection — the sleep-first mtime poll's pure half.
+
+## API
+
+### `cjm_session_scratchpad_qt.app`
+
+- `Editor` _class_ — The source pane, with line-addressed viewport access for the toggle.
+- `ScratchpadWindow` _class_ — One session file behind an edit/rendered toggle.
+- `block_line_map` _function_ — Scan a rendered document for the renderer's Lxx anchors:
+- `mono_family` _function_ — The rendered code font: the theme's mono token, else the system
+
+### `cjm_session_scratchpad_qt.appv2`
+
+- `GraphScratchpadWindow` _class_ — One session spine behind a timeline + part-composer.
+- `LanguageBar` _class_ — The fence-language mini-bar: a completer-backed field; Enter applies,
+- `SessionPickerDialog` _class_ — The open-session gesture's chooser: filterable Session list, newest
+
+### `cjm_session_scratchpad_qt.cli`
+
+- `build_parser` _function_
+- `main` _function_
+
+### `cjm_session_scratchpad_qt.files`
+
+- `Target` _class_
+- `atomic_write` _function_ — temp + rename in the target dir: a mid-session agent read never sees
+- `ensure_file` _function_ — Create the file blank if missing (sessions are born blank now);
+- `find_session_key` _function_ — Walk up from `start` for the nearest `.cjm/current-session` pointer.
+- `find_session_root` _function_ — The nearest pointer AND the project directory that owns it:
+- `most_recent` _function_ — Newest markdown file by mtime (the absent-pointer fallback).
+- `parse_key_time` _function_ — A session key is its mint timestamp; None for legacy/free-form names.
+- `resolve_target` _function_ — The launch contract: explicit path wins; otherwise the session
+
+### `cjm_session_scratchpad_qt.graph`
+
+- `ScratchpadSession` _class_ — Sync facade over the projection layer for ONE session's scratchpad:
+- `default_transcript_dir` _function_ — The harness transcript dir for a project: `~/.claude/projects/<slug>`,
+- `part_payload` _function_ — A composer part's mint/journal payload: composer-minted uuid (the
+
+### `cjm_session_scratchpad_qt.manifest`
+
+- `PendingSend` _class_ — One recorded compose-send awaiting its transcript echo.
+- `compose_text` _function_ — The outgoing message: parts joined as paragraphs, outer whitespace trimmed.
+- `load_pending` _function_ — Read manifests; a missing or unreadable sidecar is an empty list.
+- `manifest_path` _function_ — The session's pending-send sidecar.
+- `reconcile` _function_ — Match manifests against pulled user messages by EXACT text.
+- `save_pending` _function_ — Persist manifests atomically (temp + rename; a concurrent read never
+
+### `cjm_session_scratchpad_qt.render`
+
+- `RenderResult` _class_
+- `nearest_anchor` _function_ — The anchor line for a source position: greatest anchor <= line
+- `render_html` _function_ — Render markdown to QTextBrowser-ready HTML with per-block source-line
+
+### `cjm_session_scratchpad_qt.textops`
+
+- `WrapResult` _class_
+- `fence_selection` _function_ — Toggle a code fence around the selected lines. An already-fenced block
+- `toggle_list` _function_ — Toggle list markers on the selected lines: strip when every non-blank
+- `wrap_selection` _function_ — Toggle `marker` around [start, end) of `document`.
+
+### `cjm_session_scratchpad_qt.timeline`
+
+- `TimelineEntry` _class_ — One timeline row, presentation-ready.
+- `build_timeline` _function_ — Derive the interleaved timeline: active-path status + birth-class flags,
+- `timeline_blocks` _function_ — Group consecutive off-path entries for the superseded-branch chip:
+
+### `cjm_session_scratchpad_qt.timeline_html`
+
+- `build_timeline_html` _function_ — The whole timeline document: cards separated by rules, consecutive
+- `card_html` _function_ — One message card: anchored header line (identity + affordances) +
+- `lane_filter` _function_ — The lane views: composition = composer-born, transcript = pulled.
+- `linkify_ids` _function_ — Wrap full node/source ids appearing as text in jump:// links —
+- `test_clock_renders_local_time` _function_
+
+### `cjm_session_scratchpad_qt.watcher`
+
+- `DirWatch` _class_ — Cheap (mtime, size) fingerprint over a transcript dir's *.jsonl.
+
+## Dependencies
+
+**Depends on:** `PySide6`, `cjm-substrate-qt-kit`

cjm_session_scratchpad_qt-0.0.1/cjm_session_scratchpad_qt/__init__.py

@@ -0,0 +1 @@
+"""Session scratchpad — composition seat v0 (DEC 2a062aff + ea85eab7). Model-agnostic by design: any LLM session's message composition surface."""

cjm_session_scratchpad_qt-0.0.1/cjm_session_scratchpad_qt/app.py

@@ -0,0 +1,436 @@
+"""The scratchpad shell: composition seat v0 (DECs 2a062aff + ea85eab7).
+
+One window, one file. A QPlainTextEdit editor (theme body font + measure,
+no line-height merges — undo integrity) and a QTextBrowser rendered view
+(the lane's first real exerciser of document_css/heading-scale/measure on
+rich text) behind a one-key toggle that holds the reading position in BOTH
+directions: the renderer's per-block source-line anchors map top-visible
+edit line -> rendered anchor, and rendered top block -> source line. Saving
+is autosave-only — debounced idle, plus toggle / focus-loss / close — with
+atomic writes and a file-watcher guard (clean buffer follows disk, dirty
+buffer banners and holds; no dialogs, ever). Every gesture is a
+KeymapRegistry verb, so the table is the discovery surface and new gestures
+stay cheap (the accretion tenet)."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from cjm_substrate_qt_kit.findbar import FindBar
+from cjm_substrate_qt_kit.keymap import KeymapRegistry
+from cjm_substrate_qt_kit.theme import current_theme, make_font, style_text_pane
+from PySide6.QtCore import QEvent, QFileSystemWatcher, QPoint, QSettings, QTimer
+from PySide6.QtGui import QFontDatabase, QFontMetrics, QTextCursor
+from PySide6.QtWidgets import (QFileDialog, QHBoxLayout, QLabel, QMainWindow, QPlainTextEdit,
+                               QStackedWidget, QStatusBar, QTextBrowser, QVBoxLayout, QWidget)
+
+from .files import atomic_write, ensure_file, SCRATCHPAD_DIR
+from .render import nearest_anchor, render_html
+from .textops import wrap_selection
+
+AUTOSAVE_MS = 1000
+
+
+def mono_family(theme: dict) -> str:
+    """The rendered code font: the theme's mono token, else the system
+    fixed font (the mono token must render well — corpus is code-heavy)."""
+    family = str(theme.get("font-mono-family") or "")
+    if family:
+        return family
+    return QFontDatabase.systemFont(QFontDatabase.SystemFont.FixedFont).family()
+
+
+def block_line_map(doc) -> List[Tuple[int, int]]:
+    """Scan a rendered document for the renderer's Lxx anchors:
+    [(block_number, source_line)] ascending — the render->edit half of the
+    position mapping."""
+    pairs: List[Tuple[int, int]] = []
+    block = doc.begin()
+    while block.isValid():
+        found: Optional[int] = None
+        it = block.begin()
+        while not it.atEnd() and found is None:
+            for name in it.fragment().charFormat().anchorNames():
+                if name.startswith("L") and name[1:].isdigit():
+                    found = int(name[1:])
+                    break
+            it += 1
+        if found is not None:
+            pairs.append((block.blockNumber(), found))
+        block = block.next()
+    return pairs
+
+
+class Editor(QPlainTextEdit):
+    """The source pane, with line-addressed viewport access for the toggle."""
+
+    def top_line(self) -> int:
+        return self.firstVisibleBlock().blockNumber()
+
+    def visible_lines(self) -> int:
+        spacing = self.fontMetrics().lineSpacing() or 1
+        return max(1, self.viewport().height() // spacing)
+
+    def scroll_to_line(self, line: int) -> None:
+        """Put a source line at (approximately) the viewport top; the
+        scrollbar counts VISUAL lines, so wrapped blocks are summed."""
+        doc = self.document()
+        line = max(0, min(line, doc.blockCount() - 1))
+        visual = 0
+        block = doc.firstBlock()
+        for _ in range(line):
+            layout = block.layout()
+            visual += max(1, layout.lineCount() if layout else 1)
+            block = block.next()
+        self.verticalScrollBar().setValue(visual)
+
+
+class ScratchpadWindow(QMainWindow):
+    """One session file behind an edit/rendered toggle."""
+
+    def __init__(self, path: Path, banner: Optional[str] = None,
+                 directory: Optional[Path] = None):
+        super().__init__()
+        self.path = Path(path)
+        self.directory = directory or SCRATCHPAD_DIR
+        self._dirty = False
+        self._hold = False
+        self._loading = False
+        self._bound = False  # no save-before-load until a file is truly bound
+        self._measure_capped = True  # the width option, never a lock
+        self._anchor_lines: List[int] = []
+        self._block_lines: List[Tuple[int, int]] = []
+
+        self.banner = QLabel()
+        self.banner.setWordWrap(True)
+        self.banner.hide()
+        self.editor = Editor()
+        editor_row = QWidget()
+        row = QHBoxLayout(editor_row)
+        row.setContentsMargins(0, 0, 0, 0)
+        row.addStretch(1)
+        row.addWidget(self.editor, 100)  # out-stretch the sides: grow to the measure cap, then center
+        row.addStretch(1)
+        self.editor_container = editor_row
+        self.browser = QTextBrowser()
+        self.browser.setOpenExternalLinks(True)
+        self.stack = QStackedWidget()
+        self.stack.addWidget(self.editor_container)
+        self.stack.addWidget(self.browser)
+        self.findbar = FindBar(self.editor)
+        central = QWidget()
+        column = QVBoxLayout(central)
+        column.setContentsMargins(0, 0, 0, 0)
+        column.setSpacing(0)
+        column.addWidget(self.banner)
+        column.addWidget(self.stack, 1)
+        column.addWidget(self.findbar)
+        self.setCentralWidget(central)
+
+        self.file_label = QLabel()
+        self.file_label.setProperty("role", "content-dim")
+        self.mode_label = QLabel("EDIT")
+        self.save_label = QLabel("")
+        self.save_label.setProperty("role", "content-dim")
+        bar = QStatusBar()
+        bar.addWidget(self.file_label)
+        bar.addPermanentWidget(self.mode_label)
+        bar.addPermanentWidget(self.save_label)
+        self.setStatusBar(bar)
+
+        self._save_timer = QTimer(self)
+        self._save_timer.setSingleShot(True)
+        self._save_timer.setInterval(AUTOSAVE_MS)
+        self._save_timer.timeout.connect(self.save_now)
+        self.editor.textChanged.connect(self._on_edited)
+        self.watcher = QFileSystemWatcher(self)
+        self.watcher.fileChanged.connect(self._on_file_changed)
+
+        self.keymap = KeymapRegistry(self)
+        self._register_verbs()
+        self._build_menus()
+        self.refresh_theme()
+        app = self._application()
+        if app is not None:
+            hints = app.styleHints()
+            if hasattr(hints, "colorSchemeChanged"):
+                hints.colorSchemeChanged.connect(
+                    lambda _s: QTimer.singleShot(0, self.refresh_theme))
+
+        self._settings = QSettings("cjm", "cjm-session-scratchpad-qt")
+        geometry = self._settings.value("geometry")
+        if geometry is not None:
+            self.restoreGeometry(geometry)
+        else:
+            self.resize(980, 760)
+
+        self.bind_path(self.path)
+        if banner:
+            self.show_banner(banner, role="warn")
+
+    # ----- verbs -------------------------------------------------------
+
+    def _register_verbs(self) -> None:
+        add = self.keymap.add
+        add("toggle-view", "Toggle edit/rendered view", "Ctrl+/", self.toggle_view)
+        add("find", "Find in file", "Ctrl+F", self.open_find)
+        add("find-next", "Find next", "F3", self.findbar.next)
+        add("find-previous", "Find previous", "Shift+F3", self.findbar.previous)
+        add("save-now", "Save now (keeps yours on disk conflict)", "Ctrl+S",
+            lambda: self.save_now(force=True))
+        add("reload-disk", "Reload from disk (takes disk version)", "Ctrl+Shift+R",
+            self.reload_from_disk)
+        add("wrap-bold", "Bold selection", "Ctrl+B", lambda: self.wrap("**"))
+        add("wrap-italic", "Italic selection", "Ctrl+I", lambda: self.wrap("*"))
+        add("wrap-code", "Inline-code selection", "Ctrl+`", lambda: self.wrap("`"))
+        add("toggle-measure", "Toggle edit measure cap (narrow/wide)", "Ctrl+Shift+M",
+            self.toggle_measure)
+        add("open-file", "Open file…", "Ctrl+O", self.open_dialog)
+        add("quit", "Quit", "Ctrl+Q", self.close)
+
+    def _build_menus(self) -> None:
+        menus = {"File": ("open-file", "save-now", "reload-disk", "quit"),
+                 "View": ("toggle-view", "toggle-measure", "find", "find-next",
+                          "find-previous"),
+                 "Format": ("wrap-bold", "wrap-italic", "wrap-code")}
+        for title, verbs in menus.items():
+            menu = self.menuBar().addMenu(title)
+            for verb in verbs:
+                menu.addAction(self.keymap.action(verb))
+
+    # ----- file binding ------------------------------------------------
+
+    def bind_path(self, path: Path) -> None:
+        """Bind the window to a file (created blank when new), loading its
+        content without waking the autosave. The flush-first only applies to
+        a REBOUND window — at construction nothing is loaded yet, and saving
+        then would clobber the target with an empty buffer."""
+        if self._bound:
+            self.save_now()
+        self.path = Path(path)
+        created = ensure_file(self.path)
+        text = self.path.read_text(encoding="utf-8")
+        self._loading = True
+        try:
+            self.editor.setPlainText(text)
+        finally:
+            self._loading = False
+        self._dirty = False
+        self._hold = False
+        self._bound = True
+        self._rewatch()
+        self.setWindowTitle(f"{self.path.name} — session scratchpad")
+        self.file_label.setText(str(self.path))
+        self.save_label.setText("new file" if created else "")
+        if self.stack.currentWidget() is self.browser:
+            self._to_edit()
+
+    def open_dialog(self) -> None:
+        name, _filter = QFileDialog.getOpenFileName(
+            self, "Open scratchpad", str(self.directory), "Markdown (*.md);;All files (*)")
+        if name:
+            self.clear_banner()
+            self.bind_path(Path(name))
+
+    # ----- autosave + watcher ------------------------------------------
+
+    def _on_edited(self) -> None:
+        if self._loading:
+            return
+        self._dirty = True
+        self._save_timer.start()
+        self.save_label.setText("editing…")
+
+    def save_now(self, force: bool = False) -> None:
+        """Flush the buffer to disk (atomic). Held after an external change
+        until Ctrl+S (force: keep yours) or Ctrl+Shift+R (take disk)."""
+        if self._hold and not force:
+            return
+        if not self._dirty and not force:
+            return
+        atomic_write(self.path, self.editor.toPlainText())
+        self._dirty = False
+        self._hold = False
+        self._rewatch()
+        self.clear_banner()
+        self.save_label.setText(f"saved {datetime.now():%H:%M:%S}")
+
+    def reload_from_disk(self) -> None:
+        """Take the disk version (the other half of conflict resolution)."""
+        try:
+            disk = self.path.read_text(encoding="utf-8")
+        except OSError:
+            return
+        top = self.editor.top_line()
+        self._loading = True
+        try:
+            self.editor.setPlainText(disk)
+        finally:
+            self._loading = False
+        self.editor.scroll_to_line(top)
+        self._dirty = False
+        self._hold = False
+        self.clear_banner()
+        self.save_label.setText("reloaded from disk")
+        if self.stack.currentWidget() is self.browser:
+            self._to_render()  # a READ view must show the reloaded content, not the stale render
+
+    def _rewatch(self) -> None:
+        """os.replace swaps the inode, which can drop the watch — re-arm."""
+        path = str(self.path)
+        if self.path.exists() and path not in self.watcher.files():
+            self.watcher.addPath(path)
+
+    def _on_file_changed(self, _path: str) -> None:
+        self._rewatch()
+        try:
+            disk = self.path.read_text(encoding="utf-8")
+        except OSError:
+            return
+        if disk == self.editor.toPlainText():
+            return  # our own save (or an identical write) — nothing to do
+        if not self._dirty:
+            self.reload_from_disk()
+            self.show_banner("reloaded — file changed on disk", role="info")
+        else:
+            self._hold = True
+            self.show_banner("changed on disk while editing — autosave held · "
+                             "Ctrl+S keeps yours · Ctrl+Shift+R takes disk",
+                             role="warn")
+
+    # ----- toggle + position mapping -----------------------------------
+
+    def toggle_view(self) -> None:
+        if self.stack.currentWidget() is self.editor_container:
+            self._to_render()
+        else:
+            self._to_edit()
+
+    def _to_render(self) -> None:
+        self.save_now()
+        top = self.editor.top_line()
+        theme = current_theme()
+        result = render_html(self.editor.toPlainText(), theme, mono_family(theme))
+        self._anchor_lines = result.anchor_lines
+        self.browser.setHtml(result.html)
+        style_text_pane(self.browser, theme, live=True)
+        self._block_lines = block_line_map(self.browser.document())
+        anchor = nearest_anchor(self._anchor_lines, top)
+        if anchor is not None:
+            self.browser.scrollToAnchor(f"L{anchor}")
+        self.stack.setCurrentWidget(self.browser)
+        self.findbar.attach(self.browser)
+        self.browser.setFocus()
+        self.mode_label.setText("READ")
+
+    def _to_edit(self) -> None:
+        cursor = self.browser.cursorForPosition(QPoint(0, 0))
+        top_block = cursor.block().blockNumber()
+        line = 0
+        for block_number, source_line in self._block_lines:
+            if block_number > top_block:
+                break
+            line = source_line
+        self.editor.scroll_to_line(line)
+        first = self.editor.top_line()
+        span = self.editor.visible_lines()
+        if not (first <= self.editor.textCursor().blockNumber() <= first + span):
+            moved = self.editor.textCursor()
+            moved.setPosition(self.editor.document().findBlockByNumber(line).position())
+            self.editor.setTextCursor(moved)
+        self.stack.setCurrentWidget(self.editor_container)
+        self.findbar.attach(self.editor)
+        self.editor.setFocus()
+        self.mode_label.setText("EDIT")
+
+    # ----- formatting ---------------------------------------------------
+
+    def wrap(self, marker: str) -> None:
+        """Apply a wrap-selection operator through one edit block (single
+        undo step)."""
+        if self.stack.currentWidget() is not self.editor_container:
+            return
+        cursor = self.editor.textCursor()
+        result = wrap_selection(self.editor.toPlainText(),
+                                cursor.selectionStart(), cursor.selectionEnd(),
+                                marker)
+        edit = self.editor.textCursor()
+        edit.beginEditBlock()
+        edit.setPosition(result.start)
+        edit.setPosition(result.end, QTextCursor.MoveMode.KeepAnchor)
+        edit.insertText(result.text)
+        edit.endEditBlock()
+        after = self.editor.textCursor()
+        after.setPosition(result.anchor)
+        after.setPosition(result.cursor, QTextCursor.MoveMode.KeepAnchor)
+        self.editor.setTextCursor(after)
+
+    def toggle_measure(self) -> None:
+        """The width option, not a lock: flip the edit pane between the
+        measure cap and full width (first live-session filing, 2026-08-19)."""
+        self._measure_capped = not self._measure_capped
+        self.refresh_theme()
+
+    # ----- find ----------------------------------------------------------
+
+    def open_find(self) -> None:
+        pane = (self.browser if self.stack.currentWidget() is self.browser
+                else self.editor)
+        self.findbar.attach(pane)
+        self.findbar.open()
+
+    # ----- banner + theme ------------------------------------------------
+
+    def show_banner(self, text: str, role: str = "warn") -> None:
+        self.banner.setProperty("role", role)
+        self.banner.style().unpolish(self.banner)
+        self.banner.style().polish(self.banner)
+        self.banner.setText("  " + text)
+        self.banner.show()
+
+    def clear_banner(self) -> None:
+        self.banner.hide()
+        self.banner.setText("")
+
+    def refresh_theme(self) -> None:
+        """Land typography on both panes: editor gets body font + measure
+        width (NO line-height merges — undo integrity), browser gets the
+        full reading treatment; a rendered view re-renders for the new
+        inline colors."""
+        theme = current_theme()
+        font = make_font(theme, "body")
+        self.editor.setFont(font)
+        metrics = QFontMetrics(font)
+        was_loading = self._loading
+        self._loading = True  # margin change fires textChanged; not a user edit
+        try:
+            self.editor.document().setDocumentMargin(12.0)
+        finally:
+            self._loading = was_loading
+        width = metrics.averageCharWidth() * int(theme.get("measure") or 68)
+        chrome = (2 * int(self.editor.document().documentMargin())
+                  + self.editor.verticalScrollBar().sizeHint().width() + 8)
+        self.editor.setMaximumWidth(width + chrome if self._measure_capped
+                                    else 16777215)
+        self.editor.setTabStopDistance(4 * metrics.horizontalAdvance(" "))
+        if self.stack.currentWidget() is self.browser:
+            self._to_render()
+        else:
+            style_text_pane(self.browser, theme, live=True)
+
+    # ----- lifecycle ------------------------------------------------------
+
+    @staticmethod
+    def _application():
+        from PySide6.QtWidgets import QApplication
+        return QApplication.instance()
+
+    def changeEvent(self, event) -> None:
+        if event.type() == QEvent.Type.ActivationChange and not self.isActiveWindow():
+            self.save_now()
+        super().changeEvent(event)
+
+    def closeEvent(self, event) -> None:
+        self.save_now()
+        self._settings.setValue("geometry", self.saveGeometry())
+        super().closeEvent(event)