cjm-transcript-correction-tui 0.0.1__py3-none-any.whl

cjm_transcript_correction_tui/__init__.py

@@ -0,0 +1,19 @@
+"""Keyboard-first TUI driver for the transcript-correction workflow — a presentation
+driver bound onto `cjm-transcript-correction-core`'s operation vocabulary (the core
+stays headless; this library owns interaction only). Born on-graph: every region of
+this package is authored as graph nodes and projected to `.py`."""
+
+import os
+
+__version__ = "0.0.1"
+
+# PipeWire routing: conda-forge PortAudio ships an ALSA that cannot see the system
+# pipewire/default PCM (hw-only enumeration -> audio lands on the wrong sink, e.g. a
+# monitor instead of the earbuds the OS routes to). Point it at the system ALSA config
+# HERE, in the package __init__, because canonical emit hoists a module own import
+# block above any module-level code — only the package boundary runs strictly before
+# a submodule imports sounddevice. Pre-set env always wins (setdefault).
+if os.path.exists("/usr/share/alsa/alsa.conf"):
+    os.environ.setdefault("ALSA_CONFIG_PATH", "/usr/share/alsa/alsa.conf")
+if os.path.isdir("/usr/lib/x86_64-linux-gnu/alsa-lib"):
+    os.environ.setdefault("ALSA_PLUGIN_DIR", "/usr/lib/x86_64-linux-gnu/alsa-lib")

cjm_transcript_correction_tui/app.py

@@ -0,0 +1,640 @@
+import shutil
+import subprocess
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from cjm_context_graph_layer.journal import sidecar_journal_path
+from cjm_substrate_tui_kit.audio import ChunkPlayer, load_chunk
+from cjm_substrate_tui_kit.state import SidecarState
+from cjm_transcript_correction_core.graph import (commit_boundary_shift_correction,
+                                                  commit_mark_correction, commit_mark_dismissal,
+                                                  commit_prune_amendment, commit_text_correction,
+                                                  record_review_markers, start_session)
+from cjm_transcript_correction_core.models import RECOMMENDED_MARK_CLASSES
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.widgets import Input, Static
+
+from .spine import parse_mark_input, plan_boundary_shift, resolve_mark_class_token, SpineView
+
+
+class CorrectionApp(App):
+    """The correction loop, v0 thinnest slice: document-order segment walk with
+    VAD-chunk auto-play and in-place fidelity edits, over the shared transcription
+    graph through correction-core's operation vocabulary.
+
+    Interaction contract (DEC 54640079 + the walkthrough capture): the surface is a
+    CENTER-PINNED window over the cursor-parameterized effective spine (drive
+    round 4 ratification): the focused card's text line sits at the exact screen
+    center, neighbor cards stack outward and absorb the varying text heights, so
+    the eyes never leave center — segments flow past the pin. Scrolling (keys AND
+    wheel) moves the CURSOR, the paint recomposes around it, nothing moves
+    unbidden, content never overlaps. Focusing a segment auto-plays its VAD chunk
+    from the model-input WAV (immediate-play; churn accepted per the spike). An
+    edit commits a `text_content` Correction (+ its REVIEWED marker) and updates
+    the local effective text — decisions persist, the worklist stays derived.
+    The graph stack opens INSIDE the app (`on_mount`) so the JobQueue lives on
+    Textual's event loop."""
+
+    AUTO_FOCUS = None  # the hidden editor Input must not swallow the walk keys at mount
+
+    SPEEDS = (0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0)  # the [ ] playback-rate ladder (0.5/3.0 = the comprehension bounds, drive-round-7 verdict)
+
+    CSS = """
+    #cards { height: 1fr; overflow: hidden hidden; }
+    """
+
+    BINDINGS = [
+        Binding("j", "next", "next"),
+        Binding("down", "next", "next", show=False),
+        Binding("s", "next", "next", show=False),
+        Binding("k", "prev", "prev"),
+        Binding("up", "prev", "prev", show=False),
+        Binding("w", "prev", "prev", show=False),
+        Binding("r", "replay", "replay"),
+        Binding("left_square_bracket", "speed_down", "slower", key_display="["),
+        Binding("right_square_bracket", "speed_up", "faster", key_display="]"),
+        Binding("e", "edit", "edit text"),
+        Binding("y", "yank", "copy text"),
+        Binding("right", "shift_push", "push word", key_display="→"),
+        Binding("d", "shift_push", "push word", show=False),
+        Binding("left", "shift_pull", "pull word", key_display="←"),
+        Binding("a", "shift_pull", "pull word", show=False),
+        Binding("space", "reviewed", "mark reviewed"),
+        Binding("u", "unreview", "un-review"),
+        Binding("m", "mark_quick", "mark"),
+        Binding("b", "mark_boundary", "mark boundary"),
+        Binding("M", "mark_editor", "mark+class"),
+        Binding("n", "next_mark", "next mark"),
+        Binding("N", "prev_mark", "prev mark"),
+        Binding("p", "next_prune", "next prune"),
+        Binding("P", "prev_prune", "prev prune"),
+        Binding("escape", "cancel", "cancel/stop", show=False, priority=True),
+        Binding("q", "quit_app", "quit"),
+    ]
+
+    def __init__(self, graph_db_path: str,                # The shared transcription graph db
+                 *, source: Optional[str] = None,         # Source id or title substring
+                 manifests_dir: str = ".cjm/manifests",   # Capability manifests directory
+                 rendition: Optional[str] = None,         # Rendition selector (None = auto)
+                 actor: str = "human",                    # Actor recorded on corrections
+                 autoplay: bool = True,                   # Auto-play the focused chunk
+                 audio_device: Optional[object] = None,   # Output device (None = system default)
+                 resume: bool = True,                     # Reopen at the source's last-focused segment
+                 shift_floor_s: float = 0.0):             # Min seconds between held-key boundary shifts (0 = ungoverned; the commit guard is the real governor)
+        super().__init__()
+        self._open_kwargs = dict(source=source, manifests_dir=manifests_dir,
+                                 rendition=rendition)
+        self._graph_db_path = graph_db_path
+        # Every correction write appends through to the db's sidecar journal (DEC ccbab9f5).
+        self._journal_path = sidecar_journal_path(graph_db_path)
+        self.view: Optional[SpineView] = None
+        self.player: Optional[ChunkPlayer] = None
+        self.cursor = 0
+        self.actor = actor
+        self.autoplay = autoplay
+        self.speed = 1.0                   # playback rate ([ ] preset ladder; sidecar-persisted preference)
+        self.audio_device = audio_device
+        self.session_id: Optional[str] = None
+        self._marks: Dict[int, str] = {}   # cursor position -> local decision echo
+        self._mark_class = "suspect"       # last-used ⚑ class (m/b repeat it; sidecar-persisted)
+        self._input_mode = "edit"          # what the hidden Input commits ("edit" | "mark")
+        self._shift_busy = False           # in-flight boundary-shift commit (key-repeat throttle)
+        self._last_shift = 0.0             # last completed shift (monotonic; paint-rate floor)
+        self._shift_floor = float(shift_floor_s)  # tune with tests_manual/keyrate_probe.py
+        self.resume = resume
+        self._state_saved = 0.0            # last sidecar bookmark write (monotonic; 1s throttle)
+
+    def compose(self) -> ComposeResult:
+        yield Static("", id="cards")
+        yield Static("loading spine…", id="status")
+        editor = Input(id="editor")
+        editor.display = False
+        yield editor
+
+    async def on_mount(self) -> None:
+        self.view = await SpineView.open(self._graph_db_path, **self._open_kwargs)
+        self.player = ChunkPlayer(device=self.audio_device)
+        sess = await start_session(self.view.queue, self.view.graph_id,
+                                   [self.view.source_id],
+                                   journal_path=self._journal_path)
+        self.session_id = sess.id
+        state = load_tui_state(self._graph_db_path)
+        try:
+            # Speed is a PREFERENCE, not a position — restored even with resume=False.
+            self.speed = float(state.get("_speed") or 1.0)
+        except (TypeError, ValueError):
+            self.speed = 1.0
+        mc = str(state.get("_mark_class") or "suspect")
+        self._mark_class = mc if mc[:1].isalnum() else "suspect"   # heal a junk-class sidecar
+        if self.resume:
+            saved = state.get(self.view.source_id)
+            if saved and self.view.size:
+                self.cursor = max(0, min(self.view.size - 1, int(saved.get("cursor", 0))))
+        self._render()
+        if self.autoplay:
+            self._play_cursor()
+
+    def on_resize(self, event) -> None:
+        if self.view is not None:
+            self._render()
+
+    def _card_lines(self, pos: int, width: int) -> Tuple[List[Text], int]:
+        """One segment card as styled screen lines + the offset of its first body line.
+
+        FIXED GUTTER, ONE TEXT LANE (presentation agenda item 1): index/time/marks
+        live in a fixed-width left column and ALWAYS recede (dim — the eye must be
+        unable to accidentally read a timestamp); segment text gets its own
+        consistently-indented lane, so walking scans a single vertical column of
+        pure prose. Focus emphasis carries over: cursor±1 lane text bright, far
+        field dim, the focused card a full-width reverse band."""
+        view = self.view
+        seg = view.segments[pos]
+        gut_w = self._gutter_w
+        lane_w = max(10, width - gut_w)
+        mark = {"reviewed": "✓", "corrected": "✎"}.get(self._marks.get(pos, ""), "·")
+        # Gutter styling must ride SPANS, not the Text base style: lane text is
+        # appended onto these same row objects, and a base style would bleed
+        # into it (the round-2 drive regression — first two lane lines dimmed).
+        g1 = Text()
+        g1.append(f"#{seg.index} {mark}", style="dim")
+        if seg.id in view.pruned_ids:
+            g1.append(" ✂", style="red")
+        if seg.id in view.marked_ids:
+            g1.append(" ⚑", style="yellow")
+        g2 = Text()
+        g2.append(f"{seg.start_time:.1f}–{seg.end_time:.1f}s"
+                  if seg.start_time is not None else "(no audio)", style="dim")
+        body = Text(seg.text) if seg.text else Text("(empty)", style="dim")
+        if abs(pos - self.cursor) > 1 and seg.text:
+            body.stylize("dim")
+        lane = body.wrap(self.console, lane_w)
+        lines: List[Text] = []
+        a = view.aseg_index(pos)
+        if a is not None and (pos == 0 or view.aseg_index(pos - 1) != a):
+            lines.append(Text(f"━━━ audio segment {a} ━━━", style="yellow"))
+        body_offset = len(lines)
+        gutter = [g1, g2]
+        for i in range(max(len(gutter), len(lane))):
+            row = gutter[i] if i < len(gutter) else Text("")
+            row.pad_right(max(0, gut_w - row.cell_len))
+            if i < len(lane):
+                row.append_text(lane[i])
+            lines.append(row)
+        if pos == self.cursor:
+            for ln in lines:
+                ln.pad_right(max(0, width - ln.cell_len))
+                ln.stylize("reverse")
+        return lines, body_offset
+
+    @property
+    def _gutter_w(self) -> int:
+        """The source-wide gutter width: sized ONCE from the last segment (the widest
+        index + time span), so the text lane's indent never wobbles while walking."""
+        last = self.view.segments[-1]
+        t_w = (len(f"{last.end_time:.1f}–{last.end_time:.1f}s")
+               if last.end_time is not None else 0)
+        return max(t_w, len("(no audio)"), len(f"#{last.index}") + 6) + 2  # +6: the ✓/✂/⚑ glyph rail
+
+    def _render(self) -> None:
+        """Center-pinned paint (drive round 4): the focused card's FIRST TEXT LINE
+        is pinned to the vertical center of the card area; neighbor cards stack
+        outward from it (one blank separator row) and absorb the height variance,
+        clipping at the screen edges. The pin never moves — the spine flows past it."""
+        view = self.view
+        if not view.size:
+            self.query_one("#status", Static).update(f"{view.source_title}  ·  empty spine")
+            return
+        width = max(20, self.size.width)
+        height = max(3, self.size.height - 1)   # the status line keeps the last row
+        rows: List[Optional[Text]] = [None] * height
+
+        def place(lines: List[Text], top: int) -> None:
+            for i, ln in enumerate(lines):
+                if 0 <= top + i < height:
+                    rows[top + i] = ln
+
+        f_lines, f_off = self._card_lines(self.cursor, width)
+        top_f = height // 2 - f_off             # body line 0 lands dead center
+        place(f_lines, top_f)
+        pos, bottom = self.cursor - 1, top_f - 2
+        while pos >= 0 and bottom >= 0:
+            lines, _ = self._card_lines(pos, width)
+            place(lines, bottom - len(lines) + 1)
+            bottom -= len(lines) + 1
+            pos -= 1
+        pos, top = self.cursor + 1, top_f + len(f_lines) + 1
+        while pos < view.size and top < height:
+            lines, _ = self._card_lines(pos, width)
+            place(lines, top)
+            top += len(lines) + 1
+            pos += 1
+        self.query_one("#cards", Static).update(
+            Text("\n").join(ln if ln is not None else Text("") for ln in rows))
+        done = sum(1 for v in self._marks.values() if v)
+        self.query_one("#status", Static).update(
+            f"{view.source_title}  ·  segment {self.cursor + 1}/{view.size}"
+            f"  ·  marked {done}  ·  ×{self.speed:g}  ·  session {str(self.session_id or '')[:8]}"
+            f"  ·  j/k·w/s walk · ←→/a/d shift · r replay · \\[/] speed · e edit · y copy"
+            f" · space/u ±reviewed · m/b/M ⚑mark · n/N⚑ p/P✂ jump · q quit")
+
+    def _play_cursor(self) -> None:
+        c = self.view.chunk(self.cursor)
+        if c is None:
+            self.player.stop()
+            return
+        self.player.play(load_chunk(c.wav_path, c.start_s, c.end_s, speed=self.speed))
+
+    def _move(self, delta: int) -> None:
+        new = max(0, min(self.view.size - 1, self.cursor + delta))
+        if new == self.cursor:
+            return
+        self.cursor = new
+        now = time.monotonic()
+        if now - self._state_saved > 1.0:   # bookmark survives crashes, not just quits
+            save_tui_state(self._graph_db_path, self.view.source_id, new)
+            self._state_saved = now
+        self._render()
+        if self.autoplay:
+            self._play_cursor()
+
+    def action_next(self) -> None:
+        self._move(1)
+
+    def action_prev(self) -> None:
+        self._move(-1)
+
+    def on_mouse_scroll_down(self, event) -> None:  # wheel = the same cursor move as keys
+        self._move(1)
+
+    def on_mouse_scroll_up(self, event) -> None:
+        self._move(-1)
+
+    def action_replay(self) -> None:
+        self._play_cursor()
+
+    def _step_speed(self, delta: int) -> None:
+        """Step the playback rate along the preset ladder, re-sound the chunk at the
+        new rate (immediate audible confirmation), persist the preference (sidecar —
+        view state like the cursor bookmark, never a graph write)."""
+        i = min(range(len(self.SPEEDS)), key=lambda j: abs(self.SPEEDS[j] - self.speed))
+        self.speed = self.SPEEDS[max(0, min(len(self.SPEEDS) - 1, i + delta))]
+        save_tui_state(self._graph_db_path, self.view.source_id, self.cursor,
+                       speed=self.speed)
+        self._render()
+        self._play_cursor()
+
+    def action_speed_down(self) -> None:
+        self._step_speed(-1)
+
+    def action_speed_up(self) -> None:
+        self._step_speed(1)
+
+    def action_yank(self) -> None:
+        """Copy the focused segment's effective text to the system clipboard —
+        sharing a segment must not require a screenshot or re-typing.
+
+        A clipboard TOOL (wl-copy/xclip/xsel) is the primary path: OSC 52 is
+        fire-and-forget and VTE terminals commonly reject it (drive round 5),
+        so it stays only as the fallback for tool-less hosts."""
+        seg = self.view.segments[self.cursor]
+        via = self._copy_system(seg.text)
+        if via is None:
+            self.copy_to_clipboard(seg.text)   # OSC 52 — may be ignored by the terminal
+            via = "osc52, terminal-dependent"
+        self.query_one("#status", Static).update(
+            f"copied segment #{seg.index} text ({len(seg.text)} chars, {via})")
+
+    def _copy_system(self, text: str) -> Optional[str]:
+        """Pipe text to the first available system clipboard tool; None = no tool took it."""
+        for cmd in (["wl-copy"], ["xclip", "-selection", "clipboard"],
+                    ["xsel", "--clipboard", "--input"]):
+            if shutil.which(cmd[0]) is None:
+                continue
+            try:
+                subprocess.run(cmd, input=text.encode(), check=True, timeout=2)
+                return cmd[0]
+            except (OSError, subprocess.SubprocessError):
+                continue
+        return None
+
+    def action_edit(self) -> None:
+        editor = self.query_one("#editor", Input)
+        self._input_mode = "edit"
+        editor.value = self.view.segments[self.cursor].text
+        editor.display = True
+        editor.focus()
+
+    async def on_input_submitted(self, event) -> None:
+        if self._input_mode == "mark":
+            await self._submit_mark(event.value)
+            return
+        seg = self.view.segments[self.cursor]
+        new_text = event.value
+        if new_text != seg.text:
+            await commit_text_correction(
+                self.view.queue, self.view.graph_id, self.view.source_id,
+                seg.id, new_text, self.session_id,
+                old_text=seg.text, actor=self.actor,
+                journal_path=self._journal_path)
+            seg.text = new_text          # local echo of the new effective text
+            self._marks[self.cursor] = "corrected"
+        # A text-bearing PRUNED position must leave the prune set (the same
+        # rescue as boundary shifts): the prune otherwise drops the position —
+        # WITH its restored text — from the downstream effective view. Fires
+        # on re-submit too (recovery path for edits made before this guard).
+        if new_text.strip() and seg.id in self.view.pruned_ids:
+            prior = self.view.prune_correction_for(seg.id)
+            if prior is not None:
+                amended = await commit_prune_amendment(
+                    self.view.queue, self.view.graph_id, prior, [seg.id],
+                    self.session_id, actor=self.actor,
+                    journal_path=self._journal_path)
+                self.view.unprune_local(prior["id"], amended)
+                self._marks[self.cursor] = "corrected"
+        self._close_editor()
+        self._render()
+
+    def _close_editor(self) -> None:
+        editor = self.query_one("#editor", Input)
+        editor.display = False
+        self.set_focus(None)
+        self._input_mode = "edit"
+
+    async def action_reviewed(self) -> None:
+        seg = self.view.segments[self.cursor]
+        await record_review_markers(self.view.queue, self.view.graph_id,
+                                    self.session_id, [(seg.id, "reviewed")],
+                                    journal_path=self._journal_path)
+        self._marks.setdefault(self.cursor, "reviewed")
+        self._move(1)
+
+    async def action_unreview(self) -> None:
+        """u: undo an accidental space — appends an 'unreviewed' RE-DECISION
+        (review markers are events; the read is latest-wins), so the segment
+        returns to undecided for this session. Committed corrections are NOT
+        touched: undo those by supersession (re-edit / the opposite shift)."""
+        seg = self.view.segments[self.cursor]
+        await record_review_markers(self.view.queue, self.view.graph_id,
+                                    self.session_id, [(seg.id, "unreviewed")],
+                                    journal_path=self._journal_path)
+        was = self._marks.get(self.cursor)
+        if was == "reviewed":
+            self._marks.pop(self.cursor, None)
+        self._render()
+        note = ("" if was != "corrected"
+                else " (corrections stay — supersede via re-edit / opposite shift)")
+        self.query_one("#status", Static).update(f"un-reviewed #{seg.index}{note}")
+
+    async def _shift_boundary(self, direction: str) -> None:
+        """One [ / ] press: move ONE word across the boundary AFTER the cursor.
+
+        Commits a boundary_shift Correction (word-level payload, layer 0.0.8
+        semantics); when the RECEIVING segment is prune-covered, also commits
+        the unprune amendment (the falsified-D14 rescue — without it the
+        projection drops the moved text with the pruned position). Key-repeat
+        is DROPPED while a commit is in flight, so a held key can only shift
+        as fast as the screen shows it (first-drive feedback, 2026-07-12)."""
+        now = time.monotonic()
+        if self._shift_busy or now - self._last_shift < self._shift_floor:
+            return  # busy commit OR inside the paint-rate floor — drop the repeat
+        self._shift_busy = True
+        try:
+            await self._shift_boundary_now(direction)
+        finally:
+            self._last_shift = time.monotonic()
+            self._shift_busy = False
+
+    async def _shift_boundary_now(self, direction: str) -> None:
+        view, i = self.view, self.cursor
+        status = self.query_one("#status", Static)
+        if i + 1 >= view.size:
+            status.update("boundary shift: no segment after the cursor")
+            return
+        if view.aseg_index(i) != view.aseg_index(i + 1):
+            status.update("boundary shift: ✋ audio-segment seam — text stays within its audio segment")
+            return
+        left, right = view.segments[i], view.segments[i + 1]
+        plan = plan_boundary_shift(left.text, right.text, direction)
+        if plan is None:
+            status.update(f"boundary shift: nothing to {direction}")
+            return
+        moved, new_left, new_right = plan
+        await commit_boundary_shift_correction(
+            view.queue, view.graph_id, view.source_id, left.id, right.id,
+            moved, direction, self.session_id, actor=self.actor,
+            journal_path=self._journal_path)
+        receiver = right if direction == "push" else left
+        if receiver.id in view.pruned_ids:
+            prior = view.prune_correction_for(receiver.id)
+            if prior is not None:
+                amended = await commit_prune_amendment(
+                    view.queue, view.graph_id, prior, [receiver.id],
+                    self.session_id, actor=self.actor,
+                    journal_path=self._journal_path)
+                view.unprune_local(prior["id"], amended)
+        left.text, right.text = new_left, new_right   # local echo (same math as the layer)
+        self._marks[i] = "corrected"
+        self._marks[i + 1] = "corrected"
+        self._render()
+
+    async def action_shift_push(self) -> None:
+        await self._shift_boundary("push")
+
+    async def action_shift_pull(self) -> None:
+        await self._shift_boundary("pull")
+
+    def _jump_glyph(self, direction: int, ids: set, what: str) -> None:
+        """n/N (⚑), p/P (✂): cursor to the next/previous segment in a glyph id
+        set (wraps) — resolution passes walk glyphs directly instead of
+        scanning thousands of segments (drive find: had to dig for a ✂)."""
+        view = self.view
+        if not ids:
+            self.query_one("#status", Static).update(f"no {what} segments on this source")
+            return
+        for step in range(1, view.size + 1):
+            j = (self.cursor + direction * step) % view.size
+            if view.segments[j].id in ids:
+                self._move(j - self.cursor)
+                return
+
+    def action_next_mark(self) -> None:
+        self._jump_glyph(1, self.view.marked_ids, "⚑ marked")
+
+    def action_prev_mark(self) -> None:
+        self._jump_glyph(-1, self.view.marked_ids, "⚑ marked")
+
+    def action_next_prune(self) -> None:
+        self._jump_glyph(1, self.view.pruned_ids, "✂ pruned")
+
+    def action_prev_prune(self) -> None:
+        self._jump_glyph(-1, self.view.pruned_ids, "✂ pruned")
+
+    def _mark_class_menu(self) -> List[str]:
+        """Selectable classes for the M picker: the recommended slate first, then
+        classes carried by this source's OPEN marks — dismissing a class's last
+        open mark removes it (junk cleanup); proven classes persist by promotion
+        into RECOMMENDED_MARK_CLASSES (open vocab, DEC 2a231843)."""
+        return list(RECOMMENDED_MARK_CLASSES) + [
+            c for c in self.view.seen_mark_classes if c not in RECOMMENDED_MARK_CLASSES]
+
+    async def action_mark_quick(self) -> None:
+        """m: mark the focused segment with the last-used class and keep walking —
+        the held-back-corrections gesture (DEC 42854519) must cost one keystroke."""
+        seg = self.view.segments[self.cursor]
+        await self._commit_mark({"kind": "segment", "segment_id": seg.id},
+                                self._mark_class, None)
+
+    async def action_mark_boundary(self) -> None:
+        """b: mark the boundary AFTER the cursor (the shift gesture's coordinates).
+
+        Unlike shifts, audio-segment seams are NOT refused — a suspect seam is
+        exactly what a boundary mark is for."""
+        view, i = self.view, self.cursor
+        if i + 1 >= view.size:
+            self.query_one("#status", Static).update("boundary mark: no segment after the cursor")
+            return
+        await self._commit_mark({"kind": "boundary",
+                                 "boundary_after": view.segments[i].id,
+                                 "right_segment_id": view.segments[i + 1].id},
+                                self._mark_class, None)
+
+    def action_mark_editor(self) -> None:
+        """M: class-picker mark — `class-or-# ["snippet"] [note...]`: a leading
+        digit picks from the numbered class menu (recommended slate + this
+        source's journaled classes); a snippet found in the segment text becomes
+        a SPAN anchor; a punctuation-led token dismisses ALL open marks at the
+        cursor."""
+        editor = self.query_one("#editor", Input)
+        self._input_mode = "mark"
+        editor.value = f"{self._mark_class} "
+        editor.display = True
+        editor.focus()
+        menu = self._mark_class_menu()
+        self.query_one("#status", Static).update(
+            'mark: class-or-# ["snippet"] [note] · - dismiss · '
+            + " ".join(f"{i + 1}:{c}" for i, c in enumerate(menu)))
+
+    async def _submit_mark(self, raw: str) -> None:
+        seg = self.view.segments[self.cursor]
+        self._close_editor()
+        tokens = raw.split()
+        if not tokens:
+            self._render()
+            return
+        first = tokens[0].strip('`"\'')
+        if first.startswith("-") or not first:
+            # Dismissal gesture, tolerant of formatting fumbles ('`-`', '- oops'):
+            # a punctuation-led token must never mint a junk class and hijack the
+            # last-used class (drive find, 2026-07-19). ALL open marks at the
+            # cursor go — the ⚑ must actually clear (boundary marks from a
+            # neighbor's b press anchor this segment too).
+            marks = self.view.marks_for(seg.id)
+            if not marks:
+                self._render()
+                self.query_one("#status", Static).update(f"no open mark on #{seg.index}")
+                return
+            for m in marks:
+                await commit_mark_dismissal(
+                    self.view.queue, self.view.graph_id, self.view.source_id,
+                    m["id"], self.session_id, actor=self.actor,
+                    journal_path=self._journal_path)
+                self.view.dismiss_mark_local(m["id"])
+            classes = ", ".join(str((m.get("payload") or {}).get("mark_class")) for m in marks)
+            self._render()
+            self.query_one("#status", Static).update(
+                f"dismissed {len(marks)} mark(s) on #{seg.index} [{classes}]")
+            return
+        raw, err = resolve_mark_class_token(raw, self._mark_class_menu())
+        if err:
+            self._render()
+            self.query_one("#status", Static).update(f"mark: {err}")
+            return
+        parsed = parse_mark_input(raw, seg.text)
+        if parsed is None:
+            self._render()
+            return
+        mark_class, span, note = parsed
+        if span is not None:
+            start, end, snapshot = span
+            anchor = {"kind": "span", "segment_id": seg.id, "char_start": start,
+                      "char_end": end, "text_snapshot": snapshot}
+        else:
+            anchor = {"kind": "segment", "segment_id": seg.id}
+        await self._commit_mark(anchor, mark_class, note)
+
+    async def _commit_mark(self, anchor: Dict[str, Any], mark_class: str,
+                           note: Optional[str]) -> None:
+        """Commit one mark Correction + local echo (the ⚑ paints immediately).
+
+        A mark records attention, not a decision: no review marker, no text
+        change, the cursor stays put — mark and keep walking."""
+        try:
+            mark_id = await commit_mark_correction(
+                self.view.queue, self.view.graph_id, self.view.source_id,
+                anchor, mark_class, self.session_id, actor=self.actor, note=note,
+                journal_path=self._journal_path)
+        except ValueError as e:
+            self._render()
+            self.query_one("#status", Static).update(f"mark refused: {e}")
+            return
+        self._mark_class = mark_class
+        save_tui_state(self._graph_db_path, self.view.source_id, self.cursor,
+                       mark_class=mark_class)
+        self.view.add_mark_local({"id": mark_id, "correction_type": "mark",
+                                  "payload": {"operation": "mark", "anchor": dict(anchor),
+                                              "mark_class": mark_class}})
+        self._render()
+        seg = self.view.segments[self.cursor]
+        suffix = f" — {note}" if note else ""
+        self.query_one("#status", Static).update(
+            f"⚑ #{seg.index} [{mark_class}] ({anchor['kind']}){suffix}")
+
+    def action_cancel(self) -> None:
+        editor = self.query_one("#editor", Input)
+        if editor.display:
+            self._close_editor()
+            self._render()
+        else:
+            self.player.stop()
+
+    async def action_quit_app(self) -> None:
+        if self.view is not None:
+            save_tui_state(self._graph_db_path, self.view.source_id, self.cursor,
+                           speed=self.speed)
+        if self.player is not None:
+            self.player.close()
+        if self.view is not None:
+            await self.view.close()
+        self.exit()
+
+
+def load_tui_state(
+    graph_db_path: str,  # The graph db whose sidecar state file to read
+) -> Dict[str, Any]:  # {source_id: {"cursor": int, "ts": float}}; empty when absent/corrupt
+    """Read the per-graph TUI sidecar state (last-focused positions)."""
+    return SidecarState(f"{graph_db_path}.tui-state.json").load()
+
+
+def save_tui_state(
+    graph_db_path: str,  # The graph db whose sidecar state file to write
+    source_id: str,      # Source whose position is being remembered
+    cursor: int,         # Last-focused segment position
+    speed: Optional[float] = None,  # Playback-rate preference (db-wide `_speed`; None = leave as-is)
+    mark_class: Optional[str] = None,  # Last-used ⚑ class (db-wide `_mark_class`; None = leave as-is)
+) -> None:
+    """Merge one source's last-focused position into the sidecar state file.
+
+    VIEW state, not knowledge — it lives in a local sidecar next to the db,
+    never as a graph write (the cursor is where the eye was, not a decision).
+    Write failures are silently tolerated: losing a bookmark must never break
+    the correction loop."""
+    store = SidecarState(f"{graph_db_path}.tui-state.json")
+    state = store.load()
+    state[source_id] = {"cursor": int(cursor), "ts": time.time()}
+    if speed is not None:
+        state["_speed"] = float(speed)
+    if mark_class is not None:
+        state["_mark_class"] = str(mark_class)
+    store.write(state)