zettcode-plugin-api 0.4.1__tar.gz → 0.4.2__tar.gz

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/.gitignore

@@ -35,3 +35,8 @@ docs/internal/palettes.html
 
 # The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
 packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-plugin-api
-Version: 0.4.1
+Version: 0.4.2
 Summary: The one package a ZettCode plugin depends on: the plugin surface, re-exported
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/src/zettcode/plugin_api/__init__.py

@@ -1,6 +1,6 @@
 """What a plugin imports: the contract, and the one dependency it needs.
 
-A ZettCode plugin is a class published under the ``zettcode.plugins`` entry point, and everything it may touch is
+A ZettCode plugin is a class published under the ``zettcode.plugin`` entry point, and everything it may touch is
 re-exported here: the base classes and hooks of the agent side and of the terminal's rows, the command a handler returns,
 the row model and the presenter it implements, the pet format, the link to the shell, and the few widgets a panel is
 drawn with.
@@ -29,6 +29,20 @@ _EXPORTS = {
     "AgentBuild": "zettcode.engine.plugins",
     "BusyPolicy": ".commands",
     "CONTENT_INDENT": ".presenters",
+    "ContextReport": "zettcode.engine.extensions.context",
+    "ContextShare": "zettcode.engine.extensions.context",
+    "Ledger": "zettcode.engine.storage.ledger",
+    "SessionInfo": "zettcode.engine.storage.metadata",
+    "ContextPageService": ".services",
+    "ContextPageSnapshot": ".services",
+    "ContextPageWriter": ".services",
+    "ContextReportService": ".services",
+    "SessionStoreService": ".services",
+    "UsageLedgerService": ".services",
+    "SESSION_STORE": ".services",
+    "USAGE_LEDGER": ".services",
+    "CONTEXT_PAGE": ".services",
+    "CONTEXT_REPORT": ".services",
     "Canvas": "zettcode.tui",
     "ChangesEntry": ".entries",
     "Command": ".commands",
@@ -54,6 +68,8 @@ _EXPORTS = {
     "HOST_LINK": ".host",
     "Host": "zettcode.tui",
     "HostLink": ".host",
+    "INBOX": "zettcode.engine.inbox",
+    "Inbox": "zettcode.engine.inbox",
     "MarkdownEntry": ".entries",
     "Mention": "zettcode.mention",
     "MentionProvider": "zettcode.mention",
@@ -62,10 +78,12 @@ _EXPORTS = {
     "ModelState": ".state",
     "MouseAction": "zettcode.tui",
     "MouseEvent": "zettcode.tui",
+    "NextPresenter": ".presenters",
     "NoticeLevel": ".entries",
     "Pet": ".pets",
     "PetSource": ".pets",
     "PlainCommandContext": "zettcode.engine.plugins.commands",
+    "PlainCommandHost": "zettcode.engine.plugins.commands",
     "Plugin": "zettcode.engine.plugins",
     "PluginAgentMixin": "zettcode.engine.plugins",
     "PluginContext": "zettcode.engine.plugins",
@@ -81,6 +99,14 @@ _EXPORTS = {
     "PluginTurnMixin": "zettcode.engine.plugins",
     "PluginUiMixin": ".mixins",
     "Plugins": "zettcode.engine.plugins",
+    "LLM": "zettcode.engine.plugins",
+    "ModelAccess": "zettcode.engine.plugins",
+    "PLUGIN_AGENT": "zettcode.engine.plugins",
+    "PLUGIN_COMMANDS": "zettcode.engine.plugins",
+    "PLUGIN_CONFIG": "zettcode.engine.plugins",
+    "PLUGIN_SETTINGS": "zettcode.engine.plugins",
+    "PLUGIN_TUI": "zettcode.engine.plugins",
+    "PLUGIN_WORKSPACE": "zettcode.engine.plugins",
     "Presenter": ".presenters",
     "Presenters": ".presenters",
     "Provider": "zettcode.providers",
@@ -103,6 +129,9 @@ _EXPORTS = {
     "TuiGroup": "zettcode.plugin_tui",
     "TuiPlugin": ".plugin",
     "TuiPlugins": ".plugin",
+    "Trigger": "zettcode.engine.plugins",
+    "TriggerEvent": "zettcode.engine.plugins",
+    "TriggerScope": "zettcode.engine.plugins",
     "TurnCommandResult": "zettcode.engine.plugins.commands",
     "TurnSegment": ".state",
     "UiBuilder": ".state",
@@ -111,6 +140,7 @@ _EXPORTS = {
     "UiSegment": ".state",
     "UiSide": ".state",
     "WaitEntry": ".entries",
+    "Waiting": "zettcode.engine.inbox",
     "Widget": "zettcode.tui",
     "WriteEntry": ".entries",
     "ZettCodeConfig": "zettcode.config",
@@ -125,10 +155,20 @@ _EXPORTS = {
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
     from zettcode.config import ModelConfig, ZettCodeConfig
+    from zettcode.engine.extensions.context import ContextReport, ContextShare
+    from zettcode.engine.inbox import INBOX, Inbox, Waiting
     from zettcode.engine.plugins import (
+        LLM,
+        PLUGIN_AGENT,
+        PLUGIN_COMMANDS,
+        PLUGIN_CONFIG,
+        PLUGIN_SETTINGS,
+        PLUGIN_TUI,
+        PLUGIN_WORKSPACE,
         AgentBuild,
         Contribution,
         ExtensionFactory,
+        ModelAccess,
         Plugin,
         PluginAgentMixin,
         PluginContext,
@@ -143,8 +183,30 @@ if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
         PluginSetupMixin,
         PluginToolMixin,
         PluginTurnMixin,
+        Trigger,
+        TriggerEvent,
+        TriggerScope,
     )
-    from zettcode.engine.plugins.commands import PlainCommandContext, TextCommandResult, TurnCommandResult
+    from zettcode.engine.plugins.commands import (
+        PlainCommandContext,
+        PlainCommandHost,
+        TextCommandResult,
+        TurnCommandResult,
+    )
+    from zettcode.engine.service_contracts import (
+        CONTEXT_PAGE,
+        CONTEXT_REPORT,
+        SESSION_STORE,
+        USAGE_LEDGER,
+        ContextPageService,
+        ContextPageSnapshot,
+        ContextPageWriter,
+        ContextReportService,
+        SessionStoreService,
+        UsageLedgerService,
+    )
+    from zettcode.engine.storage.ledger import Ledger
+    from zettcode.engine.storage.metadata import SessionInfo
     from zettcode.mention import Mention, MentionProvider
     from zettcode.plugin_tui import TuiGroup
     from zettcode.providers import Provider
@@ -191,7 +253,7 @@ if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
     from .panels import bottom_panel, pressed
     from .pets import Pet, PetSource
     from .plugin import TuiPlugin, TuiPlugins
-    from .presenters import CONTENT_INDENT, Presenter, Presenters
+    from .presenters import CONTENT_INDENT, NextPresenter, Presenter, Presenters
     from .rows import Row
     from .state import (
         Activity,
@@ -236,6 +298,20 @@ __all__ = [
     "AgentBuild",
     "BusyPolicy",
     "CONTENT_INDENT",
+    "CONTEXT_PAGE",
+    "CONTEXT_REPORT",
+    "SESSION_STORE",
+    "USAGE_LEDGER",
+    "ContextReport",
+    "ContextShare",
+    "Ledger",
+    "SessionInfo",
+    "ContextPageService",
+    "ContextPageSnapshot",
+    "ContextPageWriter",
+    "ContextReportService",
+    "SessionStoreService",
+    "UsageLedgerService",
     "Canvas",
     "ChangesEntry",
     "Command",
@@ -261,6 +337,8 @@ __all__ = [
     "HOST_LINK",
     "Host",
     "HostLink",
+    "INBOX",
+    "Inbox",
     "MarkdownEntry",
     "Mention",
     "MentionProvider",
@@ -269,10 +347,12 @@ __all__ = [
     "ModelState",
     "MouseAction",
     "MouseEvent",
+    "NextPresenter",
     "NoticeLevel",
     "Pet",
     "PetSource",
     "PlainCommandContext",
+    "PlainCommandHost",
     "Plugin",
     "PluginAgentMixin",
     "PluginContext",
@@ -288,6 +368,14 @@ __all__ = [
     "PluginTurnMixin",
     "PluginUiMixin",
     "Plugins",
+    "LLM",
+    "ModelAccess",
+    "PLUGIN_AGENT",
+    "PLUGIN_COMMANDS",
+    "PLUGIN_CONFIG",
+    "PLUGIN_SETTINGS",
+    "PLUGIN_TUI",
+    "PLUGIN_WORKSPACE",
     "Presenter",
     "Presenters",
     "Provider",
@@ -310,6 +398,9 @@ __all__ = [
     "TuiGroup",
     "TuiPlugin",
     "TuiPlugins",
+    "Trigger",
+    "TriggerEvent",
+    "TriggerScope",
     "TurnCommandResult",
     "TurnSegment",
     "UiBuilder",
@@ -318,6 +409,7 @@ __all__ = [
     "UiSegment",
     "UiSide",
     "WaitEntry",
+    "Waiting",
     "Widget",
     "WriteEntry",
     "ZettCodeConfig",

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/src/zettcode/plugin_api/commands.py

@@ -6,7 +6,7 @@ from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Protocol, TypeAlias
+from typing import TYPE_CHECKING, Literal, TypeAlias
 
 from zettcode.plugin_api.entries import ThinkingEntry
 from zettcode.registry import Provider
@@ -45,7 +45,7 @@ class CommandUi(ABC):
         """Show a one-off toast, replacing any that is still on screen."""
 
 
-class CommandAgent(Protocol):
+class CommandAgent(ABC):
     """What a command may read of the application agent, without importing the terminal that implements it.
 
     A command needs to know which session it is in and where that session works; the rest of the agent is the
@@ -53,17 +53,21 @@ class CommandAgent(Protocol):
     """
 
     @property
+    @abstractmethod
     def session_id(self) -> str:
         """Return the session this shell is working in."""
 
     @property
+    @abstractmethod
     def workspace(self) -> Path:
         """Return the directory the session works in."""
 
-    @property
-    def runtime(self) -> ZettCodeEngine:
-        """Return the runtime: the agent, its configuration and the session store."""
+    #: Set once when the agent is built. It stays a plain attribute because the engine's `AgentBase` declares it
+    #: that way; a property here would need the agent to expose a backer, which is not this contract's to arrange.
+    #: A command reads it and does not assign it.
+    runtime: ZettCodeEngine
 
+    @abstractmethod
     def require_session(self) -> None:
         """Refuse to go on when the active session is another process's.
 
@@ -72,29 +76,35 @@ class CommandAgent(Protocol):
         """
 
 
-class CommandTranscript(Protocol):
+class CommandTranscript(ABC):
     """What a command may add to the conversation: a note, an error, or a row of Markdown."""
 
+    @abstractmethod
     def notice(self, text: str) -> object:
         """Add a line that says something happened."""
 
+    @abstractmethod
     def error(self, text: str) -> object:
         """Add a line that says something failed."""
 
+    @abstractmethod
     def markdown(self, text: str) -> object:
         """Add a row of Markdown, which a command's own answer is."""
 
+    @abstractmethod
     def start_compaction(self) -> ThinkingEntry:
         """Open the row that shows a compaction working."""
 
+    @abstractmethod
     def complete_compaction(self, text: str = "") -> None:
         """Close the running compaction row and stamp its elapsed time."""
 
+    @abstractmethod
     def clear(self) -> None:
         """Forget every row: the conversation starts over on screen, as a new session's does."""
 
 
-class CommandHost(Protocol):
+class CommandHost(ABC):
     """What a command that acts on the application, and not only on the agent, may ask of the shell.
 
     A command that opens a panel, switches the session or changes the model needs more than a place to write:
@@ -110,23 +120,35 @@ class CommandHost(Protocol):
         commands: Every command the shell knows, in the order ``/help`` lists them.
     """
 
-    client: Client
-    commands: tuple[Command, ...]
+    @property
+    @abstractmethod
+    def client(self) -> Client:
+        """Return the SDK client over the application agent."""
 
     @property
+    @abstractmethod
+    def commands(self) -> tuple[Command, ...]:
+        """Return every command the shell knows, in the order ``/help`` lists them."""
+
+    @property
+    @abstractmethod
     def agent(self) -> CommandAgent:
-        """Return the application agent; read-only, so the terminal's own class satisfies it."""
+        """Return the application agent, read-only."""
 
     @property
+    @abstractmethod
     def transcript(self) -> CommandTranscript:
-        """Return the conversation as drawn; read-only, for the same reason."""
+        """Return the conversation as drawn, read-only."""
 
+    @abstractmethod
     def close_page(self) -> None:
         """Close the page a command presented and return to the composer."""
 
+    @abstractmethod
     def request_layout(self) -> None:
         """Ask for the screen to be laid out again, after a change in what it shows."""
 
+    @abstractmethod
     async def wait_for_frame(self) -> None:
         """Wait until the next frame has reached the terminal.
 
@@ -135,30 +157,39 @@ class CommandHost(Protocol):
         work begins instead of after it.
         """
 
+    @abstractmethod
     def offer(self, command: str) -> None:
         """Put ``command`` and a space in the draft, which opens the menu of the words it takes."""
 
+    @abstractmethod
     def quit(self) -> None:
         """Leave the application."""
 
+    @abstractmethod
     def select_session(self, session_id: str) -> None:
         """Switch to a session picked in a panel: close the panel and resume behind the interface."""
 
+    @abstractmethod
     async def resume_session(self, session_id: str) -> None:
         """Restore a stored session without holding the event loop for the work."""
 
+    @abstractmethod
     async def fork_session(self) -> str:
         """Carry this conversation into a new session and continue there; return the new id."""
 
+    @abstractmethod
     async def rename_session(self, title: str) -> str:
         """Name the active session and return the name as stored."""
 
+    @abstractmethod
     async def run_continue(self) -> None:
         """Carry on the request that was interrupted."""
 
+    @abstractmethod
     async def run_side_question(self, question: str) -> None:
         """Answer a question that is kept out of the conversation."""
 
+    @abstractmethod
     async def prompt(self, text: str, *, shown: str | None = None, cache: str | None = None) -> bool:
         """Run ``text`` as one turn of this conversation, exactly as if the reader had typed it.
 
@@ -189,15 +220,19 @@ class CommandHost(Protocol):
             mid-request says ``when_busy="queue"``, and this then runs when the request in flight has ended.
         """
 
+    @abstractmethod
     def change_model(self, name: ModelInfo | str) -> ModelInfo:
         """Switch models and announce the change in the transcript."""
 
+    @abstractmethod
     def select_model(self, name: ModelInfo) -> None:
         """Apply a model picked in a panel and close the panel."""
 
+    @abstractmethod
     def change_effort(self, name: str) -> str:
         """Switch reasoning effort and announce the change."""
 
+    @abstractmethod
     def change_permission(self, name: str) -> str:
         """Set how much of the shell may run unasked and announce the change."""
 
@@ -208,6 +243,8 @@ class CommandContext:
 
     Attributes:
         argument: Trimmed text after the command name; ``""`` when none.
+        arguments: The same words split on whitespace, so a command taking several values — daemon names, short
+            values without spaces — can read them without parsing ``argument`` itself.
         ui: Surfaces the command may write to while it runs.
         host: The shell, for a command that acts on the application itself; ``None`` where there is no shell,
             such as a handler called directly in a test. Use :meth:`require_host` in a command that needs it.
@@ -216,6 +253,12 @@ class CommandContext:
     argument: str
     ui: CommandUi
     host: CommandHost | None = None
+    arguments: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Derive the list form when the caller did not give one."""
+        if not self.arguments:
+            object.__setattr__(self, "arguments", tuple(self.argument.split()))
 
     def require_host(self) -> CommandHost:
         """Return the shell, or raise ``RuntimeError`` when the command was run without one."""

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/src/zettcode/plugin_api/entries.py

@@ -1,9 +1,9 @@
 """The conversation's entries: plain data, one class for each way a row can look.
 
 An entry says *what happened* — a user asked, a tool ran, the model is thinking —
-and nothing about how that is drawn. The drawing is ``presenters.py``, which looks
-an entry up by its :class:`EntryKind`; the list of entries, and what the agent
-does to it, is ``transcript.py``.
+and nothing about how that is drawn. The drawing is ``presenters.py``, whose chain each presenter takes part in
+through ``handle``, claiming a row by its :class:`EntryKind` or, for a tool, by its name; the list of entries, and
+what the agent does to it, is ``transcript.py``.
 
 Two base classes carry what the concrete ones share. :class:`Entry` is identity
 and a place for the presenter to leave its rendered rows; :class:`TimedEntry`
@@ -222,7 +222,7 @@ class ToolEntry(TimedEntry):
 
     A tool whose row shows something of its own has an entry of its own that adds it
     (:class:`ReadEntry`, :class:`WriteEntry`, :class:`EditEntry`); they are all ``tool`` rows,
-    folded and timed alike, and the presenter registry finds the one that draws each by its class.
+    folded and timed alike, and the presenter for each claims it by the tool's own name.
     Which class a call gets is decided by the render handler that describes it
     (:class:`~.rendering.ToolRow`), so nothing here, and nothing in the transcript, names a tool.
     """

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/src/zettcode/plugin_api/presenters.py

@@ -1,8 +1,10 @@
 """What a plugin implements to draw a row: the base class, and how a drawn block is cached.
 
-A presenter turns one kind of entry into lines. The built-in ones live in `zettcode.presenters`; a plugin registers its
+A presenter turns one kind of row into lines. The built-in ones live in `zettcode.presenters`; a plugin registers its
 own through `ctx.tui.register_presenter`, and the row it draws is the same kind of object, so this — the base class and
-the rule for when a row is drawn again — is part of the plugin contract, not part of the terminal.
+the rule for when a row is drawn again — is part of the plugin contract, not part of the terminal. A presenter takes
+part in the registry's chain through its own `handle(entry, next)`: it returns itself to claim the row, or calls
+`next(entry)` to leave it to the presenters after it.
 
 The registry (`Presenters`) is here and not with the built-in rows because `Presenter.block` takes it as its `owner`:
 the base class names the registry in its own signature, so moving the registry out would make the base class import its
@@ -15,14 +17,14 @@ the width, the palette, the registry and what the row looks like, so a frame tha
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from dataclasses import fields as dataclass_fields
 from typing import Any, ClassVar, Generic, TypeVar
 
 from zettcode.tui import LineSource, Span, StaticLines, Style, TextLine, Theme
 from zettcode.tui.render import inset_line, layout_rich_lines, wrap_words
 
-from .entries import Entry, EntryKind
+from .entries import Entry
 
 #: Columns a row's content is inset by, past the gutter marker.
 CONTENT_INDENT = 2
@@ -30,6 +32,9 @@ CONTENT_INDENT = 2
 #: The entry a presenter accepts; each subclass pins it to one entry type.
 E = TypeVar("E", bound=Entry)
 
+#: The rest of the chain: asks the presenters after this one who draws the entry.
+NextPresenter = Callable[[Entry], "Presenter[Any]"]
+
 
 #: The entry fields that are not part of how a row looks: its identity, and the
 #: slots the cache itself lives in.
@@ -55,15 +60,9 @@ def _look_fields(entry_type: type) -> tuple[str, ...]:
 class Presenter(Generic[E], ABC):
     """Turns one kind of entry into rows.
 
-    The type parameter is the entry the presenter handles, and :attr:`kind` is the
-    kind that routes it there, so :meth:`lines` receives exactly that entry.
+    The type parameter is the entry the presenter handles: :meth:`handle` claims it, then :meth:`lines` draws it.
 
     Attributes:
-        kind: The kind of entry this presenter presents; one presenter per kind.
-        entry_type: The entry class this presenter is for, when it is for one family of a kind
-            rather than the kind as a whole: the presenter of an edit row is the one for
-            ``EditEntry``, though an edit row is a ``tool`` row like any other. The registry looks
-            for the entry's own class first (and its parents') and the kind second.
         gutter: Whether the rows open with a marker the presenter draws in the
             gutter's own column — the user's arrow, the wait row's sparkle, a
             tool's outcome. Every other row is inset past the gutter, so every
@@ -75,11 +74,18 @@ class Presenter(Generic[E], ABC):
             kind, or to beat another plugin, raises this.
     """
 
-    kind: ClassVar[EntryKind]
-    entry_type: ClassVar[type[Entry] | None] = None
     gutter: ClassVar[bool] = False
     priority: ClassVar[int] = 0
 
+    @abstractmethod
+    def handle(self, entry: Entry, next: NextPresenter) -> Presenter[Any]:
+        """Return the presenter that draws ``entry``, handing it to ``next`` when this one does not claim it.
+
+        This is the chain's one decision: every presenter is asked in turn, and each answers for itself. A
+        presenter returns ``self`` to claim the entry, or calls ``next(entry)`` to pass it on. The registry orders
+        the chain and starts it, but never matches an entry itself.
+        """
+
     @abstractmethod
     def lines(self, entry: E, width: int, theme: Theme, frame: int) -> list[TextLine]:
         """Return the rows this entry paints at the available width."""
@@ -202,71 +208,49 @@ class Indented(LineSource):
 
 
 class Presenters:
-    """The presenters of one transcript: one for each kind of entry, and for the families inside a kind.
-
-    A presenter is found by the entry's class first, walking up its parents, and by its kind
-    second. Most kinds have one presenter and no family (a notice is a notice), and ``tool`` has
-    one for tools in general and one for each tool whose entry carries more than the rest.
-
-    When more than one presenter could draw the same rows, the one with the higher
-    :attr:`Presenter.priority` wins, and an equal priority goes to the later registration. That is
-    what makes a transcript's own presenters the default: they are registered first, at priority 0,
-    so anything a plugin registers for the same rows wins without having to outrank them.
-    :meth:`replacing` appends, which is the same thing for a caller holding a registry rather than a
-    plugin container.
-
-    A presenter for a whole kind is a claim on every row of that kind, so it beats the families
-    registered before it at its priority: a plugin that draws every tool row draws every tool row.
-    A family registered after it, or at a higher priority, is a refinement and keeps its own.
+    """The chain of presenters one transcript asks, strongest claim first, with a fallback last.
+
+    Every presenter in the chain is asked through :meth:`Presenter.handle`: it decides whether it draws the entry
+    and hands it to the next presenter when it does not. The chain is ordered by :attr:`Presenter.priority` and then
+    by registration order, later first. The registry only starts the chain; it never matches an entry itself.
     """
 
     def __init__(self, presenters: Iterable[Presenter[Any]]) -> None:
-        """Register presenters in order; for one kind or class, the strongest claim wins."""
-        self._by_kind: dict[EntryKind, tuple[int, int, Presenter[Any]]] = {}
-        self._by_type: dict[type[Entry], tuple[int, int, Presenter[Any]]] = {}
-        for order, presenter in enumerate(presenters):
-            rank = (presenter.priority, order)
-            if presenter.entry_type is not None:
-                current = self._by_type.get(presenter.entry_type)
-                if current is None or rank >= current[:2]:
-                    self._by_type[presenter.entry_type] = (*rank, presenter)
-            else:
-                current = self._by_kind.get(presenter.kind)
-                if current is None or rank >= current[:2]:
-                    self._by_kind[presenter.kind] = (*rank, presenter)
+        """Build the chain; a later registration wins at equal priority."""
+        self._registered = tuple(presenters)
+        ordered = sorted(enumerate(self._registered), key=lambda pair: (pair[1].priority, pair[0]), reverse=True)
+        self._chain: tuple[Presenter[Any], ...] = tuple(presenter for _, presenter in ordered)
 
     @property
     def presenters(self) -> tuple[Presenter[Any], ...]:
-        """Return the presenters that draw something: the kinds' first, then the families'.
+        """Return the presenters in registration order, which is what a new registry is built from."""
+        return self._registered
 
-        A family a kind's presenter has outranked is left out: it would never be asked for a row.
-        """
-        live = [presenter for _, _, presenter in self._by_kind.values()]
-        live.extend(
-            presenter
-            for priority, order, presenter in self._by_type.values()
-            if self._by_kind.get(presenter.kind) is None or (priority, order) > self._by_kind[presenter.kind][:2]
-        )
-        return tuple(live)
+    @property
+    def chain(self) -> tuple[Presenter[Any], ...]:
+        """Return the presenters in the order the chain asks them."""
+        return self._chain
 
     def replacing(self, *presenters: Presenter[Any]) -> Presenters:
-        """Return a registry that draws the given kinds, and families, with the given presenters."""
-        return Presenters((*self.presenters, *presenters))
+        """Return a registry that appends the given presenters to this chain."""
+        return Presenters((*self._registered, *presenters))
 
     def for_entry(self, entry: Entry) -> Presenter[Any]:
-        """Return the presenter for an entry: the strongest claim on its class or kind, else say so."""
-        family: tuple[int, int, Presenter[Any]] | None = None
-        for cls in type(entry).__mro__:
-            found = self._by_type.get(cls)
-            if found is not None:
-                family = found
-                break
-        kind = self._by_kind.get(entry.kind)
-        if family is not None and (kind is None or family[:2] > kind[:2]):
-            return family[2]
-        if kind is None:
+        """Ask the chain, presenter by presenter, which one draws the entry, else raise.
+
+        The registry only starts the chain: each presenter's :meth:`Presenter.handle` decides whether it claims
+        the entry and hands it to the next when it does not.
+        """
+        chain = self._chain
+        if not chain:
             raise ValueError(f"No presenter for a {entry.kind.value} row")
-        return kind[2]
+
+        def ask(current: Entry, index: int) -> Presenter[Any]:
+            if index == len(chain):
+                raise ValueError(f"No presenter for a {current.kind.value} row")
+            return chain[index].handle(current, lambda entry: ask(entry, index + 1))
+
+        return ask(entry, 0)
 
     def lines(self, entry: Entry, width: int, theme: Theme, frame: int) -> list[TextLine]:
         """Return the rows an entry paints, rendered now and not cached."""

zettcode_plugin_api-0.4.2/src/zettcode/plugin_api/services.py

@@ -0,0 +1,33 @@
+"""Re-exports the page-facing service contracts the engine defines.
+
+The engine owns the names and the ABCs (they are implemented by engine objects, and the engine cannot import this
+package); this module is the one a plugin imports, so a page depends on the contract rather than on the engine path.
+"""
+
+from __future__ import annotations
+
+from zettcode.engine.service_contracts import (
+    CONTEXT_PAGE,
+    CONTEXT_REPORT,
+    SESSION_STORE,
+    USAGE_LEDGER,
+    ContextPageService,
+    ContextPageSnapshot,
+    ContextPageWriter,
+    ContextReportService,
+    SessionStoreService,
+    UsageLedgerService,
+)
+
+__all__ = [
+    "CONTEXT_PAGE",
+    "CONTEXT_REPORT",
+    "SESSION_STORE",
+    "USAGE_LEDGER",
+    "ContextPageService",
+    "ContextPageSnapshot",
+    "ContextPageWriter",
+    "ContextReportService",
+    "SessionStoreService",
+    "UsageLedgerService",
+]

{zettcode_plugin_api-0.4.1 → zettcode_plugin_api-0.4.2}/src/zettcode/plugin_api/state.py

@@ -33,7 +33,7 @@ UiRegion: TypeAlias = Literal["header", "status"]
 #: registration method it calls, or the builtin segment it replaces, does.
 UiSide: TypeAlias = Literal["left", "right"]
 
-#: What one segment paints: a styled line, a plain string, a :class:`~zettcode.statusline.Row` of
+#: What one segment paints: a styled line, a plain string, a :class:`~zettcode.plugin_api.rows.Row` of
 #: named parts the reader may switch off, or nothing. The alias quotes its members because
 #: :class:`TextLine` is imported only for the checker; an alias evaluates eagerly, so the names must stay strings.
 UiSegmentValue: TypeAlias = "TextLine | Row | str | None"