zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/ui/widgets/transcript.py

@@ -0,0 +1,287 @@
+"""The transcript view: a virtualized window over the conversation model.
+
+The model itself lives in ``app.agent.transcript``, because that is what the
+agent projector writes into; this module only turns it into lines and mouse
+handling, so the dependency arrow points one way (ui reads agent).
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+from collections.abc import Callable
+
+from zettcode.app.agent.conversation.transcript import Transcript
+from zettcode.plugin_api.entries import Entry, EntryKind
+from zettcode.plugin_api.presenters import Presenters
+from zettcode.presenters.presenters import block_for
+from zettcode.tui import (
+    ARROW_DOWN,
+    SEPARATOR,
+    Canvas,
+    Host,
+    LineSource,
+    MouseAction,
+    MouseEvent,
+    Rect,
+    ScrollView,
+    Span,
+    Style,
+    TextLine,
+    Theme,
+)
+from zettcode.tui.render import display_width
+
+#: Badge shown once the reader scrolls away from the newest line. It names the
+#: shortcut so the mouse and the keyboard offer the same way back.
+BADGE_ARROW = ARROW_DOWN
+BADGE_LABEL = f" back to bottom {SEPARATOR} Esc"
+BACK_TO_BOTTOM = BADGE_ARROW + BADGE_LABEL
+
+
+class TranscriptSource(LineSource):
+    """LineSource over the transcript: every entry's block, stacked, rendered at most once.
+
+    A *block* is one entry presented as rows (``presenters.block_for``); this stacks
+    them into the single line source the scrolling view reads, remembering where each
+    one starts so a line index finds its entry without walking the list.
+    """
+
+    def __init__(self, transcript: Transcript, *, theme: Theme, frame: Callable[[], int] = lambda: 0) -> None:
+        """Serve ``transcript`` as lines, caching blocks per width and version.
+
+        Args:
+            transcript: Model to read; its ``version`` invalidates this cache.
+            theme: Palette handed to each entry's presenter.
+            frame: Pulled lazily so the animation frame is only read for the
+                rows that are actually rendered.
+        """
+        self.transcript = transcript
+        self.theme = theme
+        self.frame = frame
+        self._width = 0
+        self._version = -1
+        self._theme: Theme | None = None
+        self._presenters: Presenters | None = None
+        self._starts: list[int] = []
+        self._blocks: list[LineSource] = []
+        self._count = 0
+        self._entry_count = 0
+
+    def count(self, width: int) -> int:
+        """Return how many terminal lines the transcript occupies at ``width``."""
+        self._sync(width)
+        return self._count
+
+    def line(self, index: int, width: int) -> TextLine:
+        """Return one rendered line, resolving its owning entry block first."""
+        self._sync(width)
+        if not self._blocks:
+            return TextLine()
+        position = self._owner(index)
+        return self._blocks[position].line(index - self._starts[position], width)
+
+    def entry_at(self, index: int, width: int) -> Entry | None:
+        """Return the entry that owns a rendered line, for hit testing."""
+        self._sync(width)
+        if not self._blocks:
+            return None
+        return self.transcript.entries[self._owner(index)]
+
+    def user_starts(self, width: int) -> list[int]:
+        """Return the line each message the reader sent begins on, in order.
+
+        A side question is not one of them: it is answered apart from the conversation and is not something the
+        reader would be looking for when they go back through what they asked.
+        """
+        self._sync(width)
+        return [
+            self._starts[position]
+            for position, entry in enumerate(self.transcript.entries[: len(self._starts)])
+            if entry.kind is EntryKind.USER and not getattr(entry, "side", False)
+        ]
+
+    def _owner(self, index: int) -> int:
+        """Return the position of the block that owns a line.
+
+        ``_starts`` holds the first line of every block, so the last start at or
+        before ``index`` names it.
+        """
+        return min(max(0, bisect_right(self._starts, index) - 1), len(self._blocks) - 1)
+
+    def _sync(self, width: int) -> None:
+        """Rebuild the block boundaries when the width or the transcript changed.
+
+        Only the entries the model marked dirty are re-measured. Streaming one
+        answer dirties a single index, so a token lands in O(1) work instead of
+        re-walking every entry ever written; a width, theme, or presenter change
+        still rebuilds the whole list because it invalidates every block.
+        """
+        if (
+            width == self._width
+            and self.transcript.version == self._version
+            and self._theme == self.theme
+            and self._presenters is self.transcript.presenters
+        ):
+            return
+        entries = self.transcript.entries
+        rebuild_all = (
+            width != self._width or self._theme != self.theme or self._presenters is not self.transcript.presenters
+        )
+        dirty = None if rebuild_all else self.transcript.take_dirty()
+        if dirty is None:
+            start = 0
+        else:
+            start = min(dirty, self._entry_count, len(entries))
+        self._width = width
+        self._version = self.transcript.version
+        self._theme = self.theme
+        self._presenters = self.transcript.presenters
+        frame = self.frame()
+        if start == 0:
+            self._starts = []
+            self._blocks = []
+            total = 0
+        else:
+            total = self._starts[start] if start < len(self._starts) else self._count
+            del self._starts[start:]
+            del self._blocks[start:]
+        for entry in entries[start:]:
+            self._starts.append(total)
+            block = block_for(entry, width, self.theme, frame, presenters=self.transcript.presenters)
+            self._blocks.append(block)
+            total += block.count(width)
+        self._count = total
+        self._entry_count = len(entries)
+
+
+class TranscriptView(ScrollView):
+    """Scrollable transcript that toggles entries when they are clicked.
+
+    Shape, one blank row between entries::
+
+        > inspect the project                   <- user prompt: U+276F flush left,
+                                                   text under the composer caret
+          v Thinking  1.2 s                     <- reasoning row; v collapsed,
+            checking the renderer                  U+25BE expanded, animated
+                                                   while running, stamped at end
+          x Read app.py  1.2 s v                <- tool row: glyph, what the call
+              | import os                         did, duration, and U+25B8 when
+                ...                               its bounded output can open
+          Fixed parse.                          <- answer: parsed as Markdown
+
+    Every row starts at the composer's caret column — the width of its ``\u203a ``
+    prompt — so text never sits left of where the user types. A user prompt is
+    the one exception: its own ``\u203a `` draws at column zero, flush with the
+    edge like the composer's, and its text lands on that same shared margin.
+
+    The last two rows are the same entry: a tool row collapses its output to
+    `TOOL_PREVIEW_ROWS` unless it is expanded. A click toggles the entry under
+    the pointer; everything else, the wheel included, is ScrollView's.
+    """
+
+    def __init__(self, transcript: Transcript, *, theme: Theme, wheel_speed: float = 1.0) -> None:
+        """Scroll the transcript and keep its line source in sync with the theme.
+
+        Args:
+            transcript: Model rendered by this view.
+            theme: Initial palette; ``render`` refreshes it from the live theme.
+            wheel_speed: Rows one wheel event scrolls (``transcript.mouse_scroll_speed``).
+        """
+        self.transcript = transcript
+        self.transcript_source = TranscriptSource(transcript, theme=theme, frame=lambda: transcript.frame)
+        super().__init__(self.transcript_source, follow_tail=True, selectable=True, wheel_speed=wheel_speed)
+
+    def render(self, canvas: Canvas) -> None:
+        """Refresh the source theme, then float the return badge over the rows."""
+        self.transcript_source.theme = self.theme
+        super().render(canvas)
+        self._render_badge(canvas)
+
+    @property
+    def scrolled_up(self) -> bool:
+        """Return whether the newest lines are out of view."""
+        return not self.follow_tail
+
+    def jump_to_message(self, direction: int) -> bool:
+        """Scroll so a message the reader sent is the first row: the one above the view, or the one below it.
+
+        Going back, the target is the nearest message that begins above the first visible row, so pressing again
+        walks back one message at a time; with none above, the view goes to the top of the conversation. Going
+        forward, it is the nearest one that begins below the first row, and with none left the view goes back to
+        the newest line and follows it again.
+
+        Args:
+            direction: ``-1`` for the previous message, ``1`` for the next.
+
+        Returns:
+            Whether the view moved, which is false only when there is nothing to move to.
+        """
+        starts = self.transcript_source.user_starts(self.line_width)
+        if direction < 0:
+            above = [start for start in starts if start < self.top]
+            if not above:
+                if self.top == 0:
+                    return False
+                self.scroll_to(0)
+                return True
+            self.scroll_to(above[-1])
+            return True
+        below = [start for start in starts if start > self.top]
+        if below:
+            self.scroll_to(below[0])
+            return True
+        if self.follow_tail:
+            return False
+        self.scroll_end()
+        return True
+
+    def badge_rect(self) -> Rect | None:
+        """Return the cell rectangle of the return badge, or None while at the tail.
+
+        The badge is anchored to the bottom-right corner with the same two-cell
+        margin the header, the status bar, and the composer keep, so it lines up
+        with the rest of the frame instead of the edge.
+        """
+        if not self.scrolled_up or self.rect.empty:
+            return None
+        width = display_width(BACK_TO_BOTTOM) + 2
+        if width > self.rect.width:
+            return None
+        x = max(self.rect.x, self.rect.x + self.rect.width - width - 2)
+        return Rect(x, self.rect.bottom - 1, width, 1)
+
+    def _render_badge(self, canvas: Canvas) -> None:
+        """Paint the return badge in the composer's raised-surface colours."""
+        rect = self.badge_rect()
+        if rect is None:
+            return
+        style = Style(foreground=self.theme.text, background=self.theme.surface_alt)
+        arrow = Style(foreground=self.theme.accent_bright, background=self.theme.surface_alt, bold=True)
+        canvas.draw_spans(
+            rect.x,
+            rect.y,
+            (
+                Span(" ", style),
+                Span(BADGE_ARROW, arrow),
+                Span(BADGE_LABEL, style),
+                Span(" ", style),
+            ),
+            max_width=rect.width,
+        )
+
+    def handle(self, event, host: Host) -> bool:
+        """Run the badge, else toggle the clicked entry, else leave it to ScrollView."""
+        if isinstance(event, MouseEvent) and event.action is MouseAction.DOWN:
+            badge = self.badge_rect()
+            if badge is not None and badge.contains(event.x, event.y):
+                self.scroll_end()
+                host.invalidate()
+                return True
+        if isinstance(event, MouseEvent) and event.action is MouseAction.DOWN and self.rect.contains(event.x, event.y):
+            index = self.top + event.y - self.rect.y
+            entry = self.transcript_source.entry_at(index, self.line_width)
+            if entry is not None and self.transcript.toggle(entry.id):
+                host.invalidate()
+                return True
+        # Everything else, the wheel included, belongs to ScrollView.
+        return super().handle(event, host)

zettcode/app/ui/widgets/update_page.py

@@ -0,0 +1,65 @@
+"""The bottom panel that offers a newer release."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from zettcode.tui import SEPARATOR, ListItem, ListPage
+from zettcode.update import SIMPLE_INDEX, display_command
+
+#: Row values the page hands back through :meth:`UpdatePage.chosen`.
+UPGRADE = "upgrade"
+SKIP = "skip"
+LATER = "later"
+
+
+class UpdatePage(ListPage):
+    """The available version, and the three things a reader can do about it.
+
+    Shape::
+
+        ZettCode 0.1.3 is available, you have 0.1.2
+          > Upgrade now        uv tool upgrade zettcode
+            Skip this version  not asked about 0.1.3 again
+            Not now            asked again next time
+        enter select \u00b7 esc not now
+
+    The command is part of the row, not a footnote: an upgrade installs into
+    the environment this process was started from, and seeing which one is
+    about to run is what makes that safe to accept. The two ways of saying no
+    are kept apart on purpose — one is about this version, the other about this
+    moment — and Escape takes the gentler one. The page only reports the choice;
+    the shell acts on it.
+    """
+
+    def __init__(
+        self,
+        latest: str,
+        current: str,
+        command: Sequence[str],
+        *,
+        on_choice: Callable[[str], None],
+    ) -> None:
+        """Build the panel for one offered version.
+
+        Args:
+            latest: Version the index reported, shown in the title.
+            current: Version running now, shown beside it.
+            command: Argv the upgrade would run, shown under its row.
+            on_choice: Receives :data:`UPGRADE`, :data:`SKIP` or :data:`LATER`;
+                Escape asks again next time.
+        """
+        super().__init__(
+            [
+                ListItem(UPGRADE, "Upgrade now", display_command(command)),
+                ListItem(SKIP, "Skip this version", f"not asked about {latest} again"),
+                ListItem(LATER, "Not now", "asked again next time"),
+            ],
+            title=f"ZettCode {latest} is available, you have {current}",
+            # The row is too narrow for the URL the upgrade installs from, and that URL is the point of the change
+            # this panel announces: it goes where the width is, under the title, and the row keeps the command.
+            subtitle=f"installs from PyPI ({SIMPLE_INDEX})",
+            footer=f"enter select {SEPARATOR} esc not now",
+            on_select=lambda item: on_choice(str(item.value)),
+            on_cancel=lambda: on_choice(LATER),
+        )

zettcode/app/ui/widgets/welcome.py

@@ -0,0 +1,24 @@
+"""The banner the shell writes into the transcript on startup.
+
+It is data, not a widget: ``WelcomePresenter`` combines the shared pixel mark
+with themed labels when it renders the ``welcome`` entry.
+
+The compact mark retains the website's solid face, square eyes, side ears, and
+warm heart. Its labels form one block next to it, instead of leaving the hint
+detached underneath. Half blocks keep the pixels square in tall terminal cells.
+The version follows the name on the title line, two spaces after it, which is
+where the presenter looks for it to draw it quietly.
+"""
+
+from zettcode.presenters.brand import LOGO_LINES
+from zettcode.version import __version__
+
+WELCOME = "\n".join(
+    f"  {line.text}"
+    + {
+        1: f"   ZettCode  v{__version__}",
+        2: "   A focused coding agent",
+        4: "   Type a task, or /help for commands.",
+    }.get(index, "")
+    for index, line in enumerate(LOGO_LINES)
+)

zettcode/collector.py

@@ -0,0 +1,54 @@
+"""Holding the cyclic garbage collector off while a burst of long-lived objects is built.
+
+Reading a session creates hundreds of thousands of objects that will live as long as
+the session does and that nothing will ever collect: parsed records, their envelopes,
+the rows built from them. The collector cannot know that. Each time the allocation
+count crosses its threshold it walks what was allocated since the last pass, and on a
+burst this size it does so over and over — about a tenth of the whole resume, in a
+measurement with the collector switched off for the same work.
+
+Pausing it for the length of the burst costs nothing that matters here: none of those
+objects is cyclic garbage, and the pause is a few hundred milliseconds. It is a count,
+not a flag, because the command line's build and an in-app resume can overlap, and the
+collector must come back on only when the last holder lets go — and only if it was on
+to begin with.
+"""
+
+from __future__ import annotations
+
+import gc
+import threading
+from collections.abc import Generator
+from contextlib import contextmanager
+
+_lock = threading.Lock()
+_holders = 0
+_was_enabled = False
+
+
+def held() -> bool:
+    """Return whether a burst is holding the collector off right now.
+
+    The shell switches the collector with what the reader is doing (:mod:`zettcode.app.ui.gc_policy`),
+    and must not switch it back on in the middle of a burst that is being built with it off: that
+    would hand the burst the very passes the pause exists to skip.
+    """
+    return _holders > 0
+
+
+@contextmanager
+def collector_paused() -> Generator[None, None, None]:
+    """Keep the cyclic collector off for the body, and restore it as it was afterwards."""
+    global _holders, _was_enabled
+    with _lock:
+        if _holders == 0:
+            _was_enabled = gc.isenabled()
+            gc.disable()
+        _holders += 1
+    try:
+        yield
+    finally:
+        with _lock:
+            _holders -= 1
+            if _holders == 0 and _was_enabled:
+                gc.enable()