zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/ui/widgets/effort_page.py

@@ -0,0 +1,294 @@
+"""The bottom panel ``/effort`` opens: a rail with a node for every level and a knob that slides along it."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from time import monotonic
+
+from zettcode.plugin_api.panels import pressed
+from zettcode.tui import SEPARATOR, Canvas, Host, MouseAction, MouseEvent, Theme, Widget
+from zettcode.tui.render import Style, blend, display_width, truncate
+
+#: Rows the panel takes: a blank, the title, a blank, the name over the knob, the rail, the labels, what is
+#: in force, the note, and the keys.
+EFFORT_ROWS = 9
+
+#: Seconds the knob takes to travel to the level it was sent to.
+SLIDE_SECONDS = 0.28
+
+#: Columns kept free on each side of the rail so the first and last labels stay inside the panel.
+RAIL_MARGIN = 5
+
+#: Characters of the rail: a lit stretch, the groove it runs in, a node passed, a node ahead, and the knob.
+LIT, GROOVE, PASSED, AHEAD, KNOB = "\u2501", "\u2500", "\u25cf", "\u25cb", "\u25c9"
+
+
+def heat_colour(theme: Theme, heat: float) -> str:
+    """Return the colour of a point on the effort scale, from cheap to dear.
+
+    The ramp runs through the theme's own accents \u2014 green, a brighter green, amber, and the error colour
+    \u2014 rather than through fixed hues, so it follows ``/theme`` and a light palette gets the darker ends of
+    the same story. Position on the scale is the only input: the same level is the same colour whether
+    it is being switched to or away from. The header's gauge and this panel read the same ramp.
+    """
+    stops = (theme.accent, theme.accent_bright, theme.warning, theme.error)
+    scaled = min(max(heat, 0.0), 1.0) * (len(stops) - 1)
+    index = min(int(scaled), len(stops) - 2)
+    return blend(stops[index], stops[index + 1], scaled - index)
+
+
+class EffortPage(Widget):
+    """Choose how much the model reasons by sliding a knob along a rail.
+
+    Shape::
+
+        Reasoning effort                                      medium \u2192 high
+
+                                      high
+        \u25cf\u2501\u2501\u2501\u2501\u2501\u25cf\u2501\u2501\u2501\u2501\u2501\u25cf\u2501\u2501\u2501\u2501\u2501\u25c9\u2500\u2500\u2500\u2500\u2500\u25cb\u2500\u2500\u2500\u2500\u2500\u25cb\u2500\u2500\u2500\u2500\u2500\u25cb
+        off  minimal  low  medium  high  xhigh  max  ultra
+                        now
+        more thought on hard problems
+
+        \u2190 \u2192 move \u00b7 enter select \u00b7 esc cancel
+
+    Left and Right send the knob to the next level and it *travels* there: it eases along the rail, the
+    stretch behind it lights in the colour of the scale (green for the cheap end, warm for the dear end), the
+    nodes it passes light as it reaches them, and the name over it follows. Nothing is changed by moving
+    it: Enter applies the level under the knob and puts the panel away, which is when the header plays its
+    own gauge; Escape puts the panel away and leaves the level as it was. Left and Right stop at the ends of the
+    scale, which is ordered cheapest first: wrapping from ``ultra`` to ``off`` would be the one move in the
+    row that takes a reader across the whole range.
+
+    The motion is the clock's, not a frame count: the knob is placed from the time since it set off, so a slow
+    terminal drops frames instead of slowing the knob down, and under reduced motion it simply jumps.
+
+    Args:
+        levels: The levels, cheapest first.
+        current: The level in force when the panel opens.
+        notes: One line per level, shown under the rail for the level under the knob.
+        on_select: Receives the level Enter applied.
+        on_cancel: Called when the reader backs out.
+    """
+
+    HINT = f"\u2190 \u2192 move {SEPARATOR} enter select {SEPARATOR} esc cancel"
+
+    def __init__(
+        self,
+        levels: Sequence[str],
+        current: str,
+        *,
+        notes: Mapping[str, str] | None = None,
+        on_select: Callable[[str], None],
+        on_cancel: Callable[[], None],
+    ) -> None:
+        """Start with the knob on ``current`` (or the first level when it is not one of ``levels``)."""
+        super().__init__()
+        self.levels = tuple(levels)
+        self.notes = dict(notes or {})
+        self.on_select = on_select
+        self.on_cancel = on_cancel
+        self.start = self.levels.index(current) if current in self.levels else 0
+        self.selected = self.start
+        self._origin = float(self.start)
+        self._set_off = 0.0
+        self._token = f"effort-panel:{id(self)}"
+        self._moving = False
+
+    @property
+    def focusable(self) -> bool:
+        """Take focus when the shell pushes the page, so the keys reach it."""
+        return True
+
+    @property
+    def level(self) -> str:
+        """Return the level under the knob once it arrives."""
+        return self.levels[self.selected] if self.levels else ""
+
+    @property
+    def moving(self) -> bool:
+        """Return whether the knob is still on its way."""
+        return self._moving
+
+    def _now(self) -> float:
+        return self.app.clock() if self.app is not None else monotonic()
+
+    def position(self) -> float:
+        """Return where the knob is on the scale now, in levels from the first: a fraction while it travels."""
+        if not self._moving:
+            return float(self.selected)
+        progress = (self._now() - self._set_off) / SLIDE_SECONDS
+        if progress >= 1.0:
+            return float(self.selected)
+        eased = 1 - (1 - max(0.0, progress)) ** 3
+        return self._origin + (self.selected - self._origin) * eased
+
+    def choose(self, index: int) -> None:
+        """Send the knob to a level by position; the one it is already heading for is left alone."""
+        if not self.levels:
+            return
+        index = max(0, min(len(self.levels) - 1, index))
+        if index == self.selected:
+            return
+        self._origin = self.position()
+        self.selected = index
+        self._set_off = self._now()
+        if self.app is not None and self.app.reduced_motion:
+            self._origin = float(index)
+            self._moving = False
+            return
+        self._moving = True
+        if self.app is not None:
+            self.app.scheduler.animate(self._token)
+
+    def on_unmount(self) -> None:
+        """Release the frame loop, so a panel put away mid-slide stops costing frames."""
+        self._moving = False
+        if self.app is not None:
+            self.app.scheduler.animate(self._token, active=False)
+
+    def on_tick(self) -> bool:
+        """Hand the frame loop back once the knob has arrived; say whether the picture is still changing."""
+        if self._moving and self.position() == float(self.selected):
+            self._moving = False
+            self._origin = float(self.selected)
+            if self.app is not None:
+                self.app.scheduler.animate(self._token, active=False)
+            return True  # the last frame, with the knob on its node
+        return self._moving
+
+    def capture_event(self, event, host: Host) -> bool:
+        """Take Escape before the focused widget can."""
+        if pressed(event) == "escape":
+            self.on_cancel()
+            return True
+        return False
+
+    def handle(self, event, host: Host) -> bool:
+        """Slide with Left and Right (and Home and End), and apply with Enter."""
+        if isinstance(event, MouseEvent):
+            return self._handle_mouse(event)
+        match pressed(event):
+            case "left":
+                self.choose(self.selected - 1)
+            case "right":
+                self.choose(self.selected + 1)
+            case "home":
+                self.choose(0)
+            case "end":
+                self.choose(len(self.levels) - 1)
+            case "enter":
+                self.on_select(self.level)
+            case _:
+                return False
+        return True
+
+    def _handle_mouse(self, event: MouseEvent) -> bool:
+        """Send the knob to the level nearest a click on the rail or its labels."""
+        top = self.rect.y + 3
+        if event.action is not MouseAction.DOWN or not top <= event.y <= top + 3 or not self.levels:
+            return False
+        left, right = self._rail()
+        nearest = min(range(len(self.levels)), key=lambda index: abs(self._column(index, left, right) - event.x))
+        self.choose(nearest)
+        return True
+
+    def _rail(self) -> tuple[int, int]:
+        """Return the first and last column of the rail."""
+        left = self.rect.x + RAIL_MARGIN
+        return left, max(left, self.rect.right - RAIL_MARGIN - 1)
+
+    def _column(self, index: float, left: int, right: int) -> int:
+        """Return the column a (possibly fractional) level sits at."""
+        steps = max(1, len(self.levels) - 1)
+        return left + round(index * (right - left) / steps)
+
+    def render(self, canvas: Canvas) -> None:
+        """Fill the panel, then draw the title, the rail with its knob, the labels, the note and the keys."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        surface = theme.surface_alt
+        canvas.fill(self.rect.x, self.rect.y, self.rect.width, self.rect.height, Style(background=surface))
+        x = self.rect.x + 2
+        room = max(0, self.rect.width - 4)
+        muted = Style(foreground=theme.muted, background=surface)
+        canvas.draw_text(
+            x,
+            self.rect.y + 1,
+            "Reasoning effort",
+            Style(foreground=theme.text, background=surface, bold=True),
+            max_width=room,
+        )
+        if not self.levels:
+            return
+        last = max(1, len(self.levels) - 1)
+        position = self.position()
+        nearest = min(len(self.levels) - 1, max(0, round(position)))
+        if self.selected != self.start:
+            change = f"{self.levels[self.start]} \u2192 {self.level}"
+            canvas.draw_text(
+                self.rect.right - 2 - display_width(change),
+                self.rect.y + 1,
+                change,
+                Style(foreground=heat_colour(theme, self.selected / last), background=surface),
+                max_width=room,
+            )
+        left, right = self._rail()
+        knob = self._column(position, left, right)
+        rail_y = self.rect.y + 4
+        groove = blend(theme.muted, surface, 0.55)
+        # The rail first: lit up to the knob in the colour of where each cell sits on the scale, groove after it.
+        for column in range(left, right + 1):
+            if column <= knob:
+                heat = (column - left) / max(1, right - left)
+                canvas.draw_text(column, rail_y, LIT, Style(foreground=heat_colour(theme, heat), background=surface))
+            else:
+                canvas.draw_text(column, rail_y, GROOVE, Style(foreground=groove, background=surface))
+        for index in range(len(self.levels)):
+            column = self._column(index, left, right)
+            if column < knob:
+                style = Style(foreground=heat_colour(theme, index / last), background=surface, bold=True)
+                canvas.draw_text(column, rail_y, PASSED, style)
+            elif column > knob:
+                canvas.draw_text(
+                    column, rail_y, AHEAD, Style(foreground=blend(theme.muted, surface, 0.2), background=surface)
+                )
+        knob_colour = heat_colour(theme, position / last)
+        canvas.draw_text(
+            knob, rail_y, KNOB, Style(foreground=blend(knob_colour, theme.text, 0.35), background=surface, bold=True)
+        )
+        # The name over the knob follows it, in the colour of the level it is nearest.
+        word = self.levels[nearest]
+        over = min(max(knob - display_width(word) // 2, x), max(x, self.rect.right - 2 - display_width(word)))
+        canvas.draw_text(
+            over, rail_y - 1, word, Style(foreground=heat_colour(theme, nearest / last), background=surface, bold=True)
+        )
+        self._labels(canvas, rail_y + 1, left, right, nearest, muted)
+        now_column = self._column(self.start, left, right) - 1
+        canvas.draw_text(now_column, rail_y + 2, "now", muted, max_width=max(0, self.rect.right - 1 - now_column))
+        note = self.notes.get(self.level, "")
+        if note:
+            canvas.draw_text(x, rail_y + 3, truncate(note, room), muted, max_width=room)
+        canvas.draw_text(x, self.rect.bottom - 1, truncate(self.HINT, room), muted, max_width=room)
+
+    def _labels(self, canvas: Canvas, y: int, left: int, right: int, nearest: int, muted: Style) -> None:
+        """Write each level under its node, skipping the ones that would run into a label already written.
+
+        The level the knob is on is written first and never skipped, then the rest from the left, so on a
+        narrow panel what is left is the knob's neighbourhood rather than an arbitrary run.
+        """
+        theme = self.theme
+        taken: list[tuple[int, int]] = []
+        order = [nearest] + [index for index in range(len(self.levels)) if index != nearest]
+        for index in order:
+            label = self.levels[index]
+            width = display_width(label)
+            start = self._column(index, left, right) - width // 2
+            start = max(self.rect.x + 1, min(start, self.rect.right - 1 - width))
+            if any(start < stop + 1 and first < start + width + 1 for first, stop in taken):
+                continue
+            taken.append((start, start + width))
+            on = index == nearest
+            style = Style(foreground=theme.text if on else theme.muted, background=theme.surface_alt, bold=on)
+            canvas.draw_text(start, y, label, style, max_width=width)

zettcode/app/ui/widgets/follow_up.py

@@ -0,0 +1,168 @@
+"""Messages held to be sent once the running request is over.
+
+A follow-up is the other kind of message a reader can send while the agent is working.
+A steering message is handed to the agent, which adopts it at its next boundary and
+drops the rest of the task; a follow-up waits here, in the reader's hands, and goes out
+as a turn of its own when the request ends. Because it has not been handed to anyone it
+can still be changed, so this container — unlike the steering one — has a highlight,
+and the row under the list says which keys use it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from zettcode.plugin_api.presenters import CONTENT_INDENT
+from zettcode.tui import MARKER, OPTION, SEPARATOR, Canvas, Constraints, Size, Style, Widget
+from zettcode.tui.render import ELLIPSIS, display_width, truncate
+
+#: Right-aligned badge that says a row is a follow-up.
+FOLLOW_UP_BADGE = "follow-up"
+#: What stands before a waiting message: a bullet, because it is an item in a list.
+BULLET = "\u2022"
+#: What the modifier key is called on this machine's keyboard, from :mod:`zettcode.tui`.
+#: The same physical key sends the same bytes everywhere; only its name differs, and a hint
+#: that says "alt" to someone looking at a key marked "option" is a hint they translate.
+#: The row under the list when nothing is highlighted: what the container is, and the
+#: key that reaches the rest.
+HINT_IDLE = f"sent in order after a reply completes {SEPARATOR} {OPTION}+\u2191/\u2193 to select"
+#: The same row when no request is running. The list is still there — a request that was
+#: stopped leaves it alone — and "after this request" would be about nothing.
+HINT_HELD = f"held until your next reply completes {SEPARATOR} {OPTION}+\u2191/\u2193 to select"
+#: The row under the list while one message is highlighted: everything it can do. The arrows
+#: move the highlight, and with the modifier they move the message.
+HINT_SELECTED = (
+    f"\u2191/\u2193 select {SEPARATOR} {OPTION}+\u2191/\u2193 reorder {SEPARATOR} enter edit "
+    f"{SEPARATOR} ^S steer {SEPARATOR} del remove {SEPARATOR} esc done"
+)
+#: Left margin, shared with the transcript and the composer prompt.
+INDENT = CONTENT_INDENT
+#: Columns the marker and the space after it take.
+MARKER_COLUMNS = 2
+#: Cells kept between the message and the badge so they never touch.
+BADGE_GAP = 2
+
+
+def one_line(message: str) -> str:
+    """Return the first line of a message, marked when there were more.
+
+    A row is one line tall, and a message with a line break in it would otherwise draw a
+    control character into the middle of the list. The ellipsis says the rest is there.
+    """
+    lines = message.strip().splitlines()
+    head = lines[0].strip() if lines else ""
+    return f"{head} {ELLIPSIS}" if len(lines) > 1 else head
+
+
+class FollowUpQueue(Widget):
+    """Show the messages waiting for the request to end, one row each, with a highlight.
+
+    Shape::
+
+          \u2022 then run the tests                              follow-up
+        \u25b8 summarize what changed                            follow-up   <- highlighted
+          \u2022 and open a pull request                         follow-up
+          \u2191/\u2193 select \u00b7 option+\u2191/\u2193 reorder \u00b7 enter edit \u00b7 ^S steer \u00b7 del remove \u00b7 esc done
+        ^ marker, body text           right-aligned badge, then the keys
+
+    The rows are in the order they will be sent, the first at the top. The highlighted
+    row is banded and bold, the way a picker marks its choice, and the row under the
+    list changes with it: before anything is highlighted it names the one key that
+    starts, after it lists the rest. An empty queue asks for no rows, so the body slot
+    collapses and the composer keeps its place.
+    """
+
+    def __init__(self) -> None:
+        """Start with nothing waiting and nothing highlighted."""
+        super().__init__()
+        self.messages: tuple[str, ...] = ()
+        self.selected: int | None = None
+        #: Whether nothing is running, so the list waits for the reader's next reply
+        #: rather than for the one in flight.
+        self.held = False
+
+    @property
+    def visible(self) -> bool:
+        """Return whether any messages are waiting."""
+        return bool(self.messages)
+
+    def set_messages(self, messages: Sequence[str], selected: int | None = None, *, held: bool = False) -> bool:
+        """Replace the list and the highlight, and report whether anything changed.
+
+        Args:
+            messages: What is waiting, in the order it will be sent.
+            selected: Index of the highlighted row, or ``None``; one past the end is
+                treated as none, because the shell asks for it when the list shrinks.
+            held: Whether no request is running, which changes what the keys line says
+                the list is waiting for.
+        """
+        updated = tuple(messages)
+        chosen = selected if selected is not None and 0 <= selected < len(updated) else None
+        if updated == self.messages and chosen == self.selected and held == self.held:
+            return False
+        self.messages = updated
+        self.selected = chosen
+        self.held = held
+        self.invalidate()
+        return True
+
+    @property
+    def hint(self) -> str:
+        """Return the keys line for the current state."""
+        if self.selected is not None:
+            return HINT_SELECTED
+        return HINT_HELD if self.held else HINT_IDLE
+
+    def preferred_height(self) -> int:
+        """Return one row per message plus the keys line, or none."""
+        return len(self.messages) + 1 if self.messages else 0
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for the widest row, the keys line included."""
+        widest = max((display_width(one_line(message)) for message in self.messages), default=0)
+        row = INDENT + MARKER_COLUMNS + widest + BADGE_GAP + display_width(FOLLOW_UP_BADGE)
+        note = INDENT + max(display_width(HINT_SELECTED), display_width(HINT_HELD))
+        return constraints.constrain(Size(max(row, note), self.preferred_height()))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the rows, banding the highlighted one, and the keys line under them."""
+        if not self.messages or self.rect.empty:
+            return
+        theme = self.theme
+        canvas.fill(self.rect.x, self.rect.y, self.rect.width, self.rect.height, Style(background=theme.surface), " ")
+        width = self.rect.width
+        badge = display_width(FOLLOW_UP_BADGE)
+        left = INDENT + MARKER_COLUMNS
+        reserved = left + badge + BADGE_GAP
+        # A row too narrow for both drops the badge rather than the message.
+        show_badge = width >= reserved + 4
+        text_width = max(0, width - (reserved if show_badge else left))
+        for row, message in enumerate(self.messages):
+            y = self.rect.y + row
+            if y >= self.rect.y + self.rect.height:
+                return
+            chosen = row == self.selected
+            if chosen:
+                band = Style(foreground=theme.text, background=theme.selection, bold=True)
+                canvas.fill(self.rect.x, y, width, 1, band, " ")
+                marker, body, badge_style = MARKER, band, Style(foreground=theme.muted, background=theme.selection)
+            else:
+                marker = BULLET
+                body = Style(foreground=theme.text)
+                badge_style = Style(foreground=theme.muted)
+            canvas.draw_text(
+                self.rect.x + INDENT, y, marker, Style(foreground=theme.accent, background=body.background, bold=chosen)
+            )
+            canvas.draw_text(self.rect.x + left, y, truncate(one_line(message), text_width), body, max_width=text_width)
+            if show_badge:
+                canvas.draw_text(self.rect.x + width - badge, y, FOLLOW_UP_BADGE, badge_style)
+        note_y = self.rect.y + len(self.messages)
+        if note_y < self.rect.y + self.rect.height:
+            note_width = max(0, width - INDENT)
+            canvas.draw_text(
+                self.rect.x + INDENT,
+                note_y,
+                truncate(self.hint, note_width),
+                Style(foreground=theme.muted),
+                max_width=note_width,
+            )