synapse-cli-agent 0.1.13__py3-none-any.whl

synapse/ui/topbar/__init__.py

@@ -0,0 +1,97 @@
+"""Extensible topbar package.
+
+Public layout/registry API lives in ``core``; built-in components live under
+``components/`` and are registered via ``DEFAULT_COMPONENT_INSTALLERS``.
+
+Add a component
+---------------
+1. Create ``components/foo.py`` with ``install(registry, ctx)``.
+2. Append ``foo.install`` to ``DEFAULT_COMPONENT_INSTALLERS`` in
+   ``components/__init__.py``.
+"""
+
+from __future__ import annotations
+
+from synapse.ui.topbar.components import (
+    DEFAULT_COMPONENT_INSTALLERS,
+    install_default_components,
+    install_default_regions,
+)
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import (
+    DEFAULT_COL_GAP,
+    DEFAULT_REGION_GAP,
+    PackedRegion,
+    TopBarAlign,
+    TopBarComponent,
+    TopBarLayout,
+    TopBarRegion,
+    TopBarRegionSpec,
+    TopBarRegistry,
+    align_in_width,
+    center_in_width,
+    display_width,
+    join_region_parts,
+    layout_from_registry,
+    locate_component_span,
+    normalize_region_id,
+    pack_layout_from_registry,
+    pack_region_list,
+    pack_topbar_regions,
+    render_packed_line,
+    render_region_text,
+    truncate_to_width,
+)
+from synapse.ui.topbar.git_changes_popover import GitChangesPopover
+from synapse.ui.topbar.git_chrome import (
+    GitBranchChrome,
+    GitChangedFile,
+    format_branch_chrome_plain,
+    format_changed_file_plain,
+    probe_git_branch_chrome,
+    probe_git_changed_files,
+    render_branch_chrome,
+    render_changed_file_row,
+)
+from synapse.ui.topbar.tool_output_popover import ToolOutputPopover
+from synapse.ui.topbar.widget import TopBar
+
+__all__ = [
+    "DEFAULT_COL_GAP",
+    "DEFAULT_COMPONENT_INSTALLERS",
+    "DEFAULT_REGION_GAP",
+    "GitBranchChrome",
+    "GitChangedFile",
+    "GitChangesPopover",
+    "PackedRegion",
+    "TopBar",
+    "TopBarAlign",
+    "TopBarComponent",
+    "TopBarContext",
+    "TopBarLayout",
+    "TopBarRegion",
+    "TopBarRegionSpec",
+    "TopBarRegistry",
+    "ToolOutputPopover",
+    "align_in_width",
+    "center_in_width",
+    "display_width",
+    "format_branch_chrome_plain",
+    "format_changed_file_plain",
+    "install_default_components",
+    "install_default_regions",
+    "join_region_parts",
+    "layout_from_registry",
+    "locate_component_span",
+    "normalize_region_id",
+    "pack_layout_from_registry",
+    "pack_region_list",
+    "pack_topbar_regions",
+    "probe_git_branch_chrome",
+    "probe_git_changed_files",
+    "render_branch_chrome",
+    "render_changed_file_row",
+    "render_packed_line",
+    "render_region_text",
+    "truncate_to_width",
+]

synapse/ui/topbar/components/__init__.py

@@ -0,0 +1,150 @@
+"""Built-in topbar components.
+
+Extension pattern
+-----------------
+1. Add ``components/my_widget.py`` with::
+
+       ID = "my_widget"
+
+       def install(registry, ctx) -> None:
+           registry.register_fn(ID, render, region=..., order=..., priority=...)
+
+2. Append ``my_widget.install`` to :data:`DEFAULT_COMPONENT_INSTALLERS` below.
+
+No other topbar core files need to change.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from synapse.ui.topbar.components import branch, title, tool_output, usage, workspace
+from synapse.ui.topbar.core import (
+    DEFAULT_COL_GAP,
+    TopBarAlign,
+    TopBarRegion,
+    TopBarRegistry,
+)
+
+if TYPE_CHECKING:
+    from synapse.ui.topbar.context import TopBarContext
+
+ComponentInstaller = Callable[[TopBarRegistry, "TopBarContext"], None]
+
+# Order here is install order only (layout uses each component's region/order).
+# To add a component: create a module, then append its ``install`` here.
+DEFAULT_COMPONENT_INSTALLERS: list[ComponentInstaller] = [
+    workspace.install,
+    title.install,
+    branch.install,
+    tool_output.install,
+    usage.install,
+]
+
+
+def install_default_regions(
+    registry: TopBarRegistry,
+    *,
+    left_bg: str | None = None,
+    center_bg: str | None = None,
+    right_bg: str | None = None,
+    left_fg: str | None = None,
+    center_fg: str | None = None,
+    right_fg: str | None = None,
+) -> None:
+    """Ensure classic left / center / right region slots exist.
+
+    Optional ``*_bg`` / ``*_fg`` paint each region as a distinct color band
+    (Rich styles: ``fg on bg``). Omit to keep the widget-level topbar chrome.
+    """
+    registry.register_region(
+        TopBarRegion.LEFT.value,
+        order=10,
+        flex=0,
+        align=TopBarAlign.LEFT,
+        priority=40,
+        gap_after=DEFAULT_COL_GAP,
+        fg=left_fg,
+        bg=left_bg,
+    )
+    registry.register_region(
+        TopBarRegion.CENTER.value,
+        order=20,
+        flex=1,
+        align=TopBarAlign.CENTER,
+        priority=10,
+        min_width=4,
+        gap_after=DEFAULT_COL_GAP,
+        fg=center_fg,
+        bg=center_bg,
+    )
+    registry.register_region(
+        "tool_output",
+        order=25,
+        flex=0,
+        min_width=0,
+        max_width=18,
+        align=TopBarAlign.CENTER,
+        priority=20,
+        gap_after=DEFAULT_COL_GAP,
+    )
+    registry.register_region(
+        TopBarRegion.RIGHT.value,
+        order=30,
+        flex=0,
+        align=TopBarAlign.RIGHT,
+        priority=100,
+        gap_after=0,
+        fg=right_fg,
+        bg=right_bg,
+    )
+
+
+def install_default_components(
+    registry: TopBarRegistry,
+    ctx: TopBarContext | None = None,
+    /,
+    *,
+    workspace: Callable[[], str] | None = None,
+    title: Callable[[], str] | None = None,
+    branch: Callable | None = None,
+    usage: Callable[[], str] | None = None,
+    tool_output: Callable[[], str] | None = None,
+    workspace_mark: str = "≡",
+    branch_mark: str = "⎇",
+    installers: list[ComponentInstaller] | None = None,
+) -> None:
+    """Install default regions + component modules.
+
+    Prefer passing :class:`TopBarContext`. Keyword providers remain for tests
+    and call sites that have not migrated yet.
+    """
+    from synapse.ui.topbar.context import TopBarContext as _Ctx
+
+    if ctx is None:
+        if workspace is None or title is None or branch is None or usage is None:
+            raise TypeError(
+                "install_default_components requires ctx= or workspace/title/branch/usage="
+            )
+        ctx = _Ctx(
+            workspace=workspace,
+            title=title,
+            branch=branch,
+            usage=usage,
+            tool_output=tool_output or (lambda: ""),
+            workspace_mark=workspace_mark,
+            branch_mark=branch_mark,
+        )
+
+    install_default_regions(registry)
+    for install in installers or DEFAULT_COMPONENT_INSTALLERS:
+        install(registry, ctx)
+
+
+__all__ = [
+    "DEFAULT_COMPONENT_INSTALLERS",
+    "ComponentInstaller",
+    "install_default_components",
+    "install_default_regions",
+]

synapse/ui/topbar/components/branch.py

@@ -0,0 +1,41 @@
+"""Topbar component: git branch chrome (left, after workspace)."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import TopBarRegion, TopBarRegistry
+
+ID = "branch"
+REGION = TopBarRegion.LEFT
+ORDER = 20  # immediately right of workspace
+PRIORITY = 50
+MIN_WIDTH = 6
+
+
+def install(registry: TopBarRegistry, ctx: TopBarContext) -> None:
+    """Register the git branch status component.
+
+    ``ctx.branch`` may return plain text or a pre-styled ``rich.text.Text``
+    (dirty/ahead/behind colors). Plain strings get the default branch mark.
+    """
+
+    def render() -> str | Text:
+        raw = ctx.branch()
+        if isinstance(raw, Text):
+            return raw if raw.plain.strip() else ""
+        name = str(raw or "").strip()
+        if not name:
+            return ""
+        mark = (ctx.branch_mark or "").strip()
+        return f"{mark} {name}" if mark else name
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/topbar/components/title.py

@@ -0,0 +1,24 @@
+"""Topbar component: session title (center)."""
+
+from __future__ import annotations
+
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import TopBarRegion, TopBarRegistry
+
+ID = "title"
+REGION = TopBarRegion.CENTER
+ORDER = 10
+PRIORITY = 10  # shrink first when narrow
+MIN_WIDTH = 4
+
+
+def install(registry: TopBarRegistry, ctx: TopBarContext) -> None:
+    """Register the session title component."""
+    registry.register_fn(
+        ID,
+        lambda: (ctx.title() or "").strip(),
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/topbar/components/tool_output.py

@@ -0,0 +1,24 @@
+"""Topbar component: effective tool-output compression savings."""
+
+from __future__ import annotations
+
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import TopBarRegistry
+
+ID = "tool_output"
+REGION = "tool_output"
+ORDER = 10
+PRIORITY = 45
+MIN_WIDTH = 0
+
+
+def install(registry: TopBarRegistry, ctx: TopBarContext) -> None:
+    """Register the compact tool-output savings label in its own region."""
+    registry.register_fn(
+        ID,
+        lambda: ctx.tool_output() or "",
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/topbar/components/usage.py

@@ -0,0 +1,24 @@
+"""Topbar component: token usage (right)."""
+
+from __future__ import annotations
+
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import TopBarRegion, TopBarRegistry
+
+ID = "usage"
+REGION = TopBarRegion.RIGHT
+ORDER = 10
+PRIORITY = 60  # keep when narrow
+MIN_WIDTH = 8
+
+
+def install(registry: TopBarRegistry, ctx: TopBarContext) -> None:
+    """Register the in/cache/out + occupancy usage component."""
+    registry.register_fn(
+        ID,
+        lambda: ctx.usage() or "",
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/topbar/components/workspace.py

@@ -0,0 +1,32 @@
+"""Topbar component: workspace path (left)."""
+
+from __future__ import annotations
+
+from synapse.ui.topbar.context import TopBarContext
+from synapse.ui.topbar.core import TopBarRegion, TopBarRegistry
+
+ID = "workspace"
+REGION = TopBarRegion.LEFT
+ORDER = 10
+PRIORITY = 40
+MIN_WIDTH = 8
+
+
+def install(registry: TopBarRegistry, ctx: TopBarContext) -> None:
+    """Register the workspace label component."""
+
+    def render() -> str:
+        label = (ctx.workspace() or "").strip()
+        if not label:
+            return ""
+        mark = (ctx.workspace_mark or "").strip()
+        return f"{mark}  {label}" if mark else label
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/topbar/context.py

@@ -0,0 +1,32 @@
+"""Host context passed into topbar component installers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from rich.text import Text
+
+# Providers may return plain text or pre-styled Rich Text.
+LabelFn = Callable[[], str]
+RichLabelFn = Callable[[], str | Text]
+
+
+def _empty_label() -> str:
+    return ""
+
+
+@dataclass(slots=True)
+class TopBarContext:
+    """Data sources for built-in (and custom) topbar components.
+
+    App/host fills these callables; each component module only reads what it needs.
+    """
+
+    workspace: LabelFn
+    title: LabelFn
+    branch: RichLabelFn
+    usage: LabelFn
+    tool_output: RichLabelFn = _empty_label
+    workspace_mark: str = "≡"
+    branch_mark: str = "⎇"