termcore 0.2.0__tar.gz → 0.4.0__tar.gz

{termcore-0.2.0 → termcore-0.4.0}/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.0] – 2026-11-06
+
+### Added
+
+- `tui/theme_overrides.py`: `apply_color_overrides`, which layers single colours from an application's config over a theme. A base colour (`primary`, `surface`, `error`, ...) replaces the theme's field, any other name the CSS variable Textual generates under it (`footer-background`, `text-muted`, ...). An unknown name or an unparseable value is logged and skipped, so a typo does not stop the app; `color_override_problems` returns a message for each so the application can show it, and `known_color_names` and `unknown_color_names` list the valid and the unknown names
+- `ThemeLoader.set_color_overrides`, which applies those overrides to every theme the loader registers, Textual's built-in ones included, so they survive a theme switch. Without overrides the built-in themes stay as Textual ships them
+- `ThemeLoader.get_theme`, returning a registered or built-in theme by name with the overrides applied, without a running app
+- `cli/cli_theme.py`: `CliTheme`, the colours of the four message panels, with `set_cli_theme` and `cli_theme_from_textual`. A CLI that hands it the TUI's theme shows errors, warnings, successes and notes in that theme's colours; the defaults keep the previous red, yellow, green and cyan
+- `tests/test_theme_only_colours.py`, which fails on a colour value anywhere in the package outside the themes' `theme.py` files and `cli/cli_theme.py`: in Python strings, `DEFAULT_CSS` blocks and stylesheets alike. Textual's and Rich's own parsers decide what a colour is
+
+### Changed
+
+- **Breaking.** `CustomBindings` is now `Keymap`, and the module `tui/custom_bindings.py` is now `tui/keymap.py`. The old name described the class by its relation to Textual's own `BINDINGS` rather than by what it does: it is the map from a scope and key to a binding
+- `print_error`, `print_warning`, `print_success` and `print_info` read their colour from the active `CliTheme` instead of a fixed one; the look is unchanged until an application sets a theme
+- The six bundled themes with a stylesheet (`classic-black-v1`, `classic-black-v2`, `classic-black-saturated`, `compact-gray`, `mnml-black`, `mnml-deepblack`) no longer hold a colour value in it. The cursor colour is the new theme variable `input-cursor-foreground`, so a config override reaches it too
+- `compact-gray` draws the text of an `Option` in the theme's `$error` instead of a fixed `red`, which is a slightly different red
+
+## [0.3.0] – 2026-07-22
+
+### Added
+
+- `Textfile.write_atomic`, which writes through a synced temporary file and a rename. `AppStateStorage`, `ThemeLoader` and any consumer rewriting a file whole now keep their old content when a write is interrupted; a plain write truncates first, so a crash between truncating and writing loses everything rather than the last change
+- `setup_logging` takes a `log_dir`, so an application that resolves its own paths does not have a second resolver behind its back. Its default now follows `XDG_STATE_HOME` instead of hard-coding `~/.local/state`
+- `AppHeader` posts `TabSelected` when a tab label is clicked. The header does not switch anything itself - it does not own the content - and only inactive tabs carry the click, because Textual restyles anything clickable with its link colour and that would flatten the active tab to the same grey as the rest
+
+- `tui/binding_groups.py`: `BindingGroup`, the labelled row of shortcuts that the footer and the help overlay both render from, plus `active_actions` to snapshot what is bound on a screen and `dispatch_name` to strip the `app.` prefix a Screen adds
+- `CustomBindings.get_groups`, returning every declared group in the order the YAML file declares it. It replaces both row maps, and the defect they invited disappears with them: there is no longer a pair of calls that can be mismatched
+- A `group` entry in the binding YAML. A scope may now hold groups, single bindings, or both; consecutive single bindings share one unlabelled row. Grouping is optional and adds no ceremony where it is not wanted
+- `tui/help_screen.py`: `HelpScreen`, the overlay section 1.8 of the style guide asks for - every shortcut, grouped, with a fuzzy search over them and a `ctrl+t` toggle between all bindings and the ones currently active. Matching uses Textual's own `Matcher` rather than a hand-written one
+- `tui/help_rows.py`: the filtering and row order behind the overlay, testable without an application
+- A second file of scope display names, passed to `CustomBindings` as `scopes_file`. Scope names such as `tasks_tab` are identifiers; this maps them to the words people read. `scope_title` resolves one, `BindingGroup.scope_title` carries it, and a title naming no scope is reported - nothing else would ever notice it
+- `display_scope`, which falls back to the raw scope name where no title was declared. The fallback is meant to look unfinished rather than invent a heading nobody chose
+- `tui/custom_widgets/footer_rows.py`: the footer's arithmetic - label column width, key width and wrapping - split out so it can be tested without an application and so `multiline_footer.py` stays inside the file-size limit
+- `tui/custom_widgets/app_header.py`: `AppHeader`, a header carrying the application name in its own column and the tabs after it, wrapping onto further rows whose brand cell is blank but as wide. Textual's `Header` is fixed at one line (three with `-tall`) with three hard-wired slots, and `Tabs` scrolls rather than wraps, so neither could serve
+- `tui/custom_widgets/tab_rows.py`: the header's packing, testable without an application
+- `tui/custom_widgets/status_bar.py`: `StatusBar`, one line with standing information on the left and a passing message on the right. Textual has no status widget; `App.notify` covers only the passing half, as a box that expires on a timer
+- A `key` field in the scopes file, and `scope_key`, `get_tab_scopes` and `get_tab_bindings` to read it. Declaring a key is what makes a scope a tab: the key selects it, the header prints it, and the order of the file is the order of the bar
+- The first tests for `MultiLineFooter`, which had none: row order, separator count, label alignment, wrapping at a narrow width, and that clicking a key still runs its action
+
+### Changed
+
+- **Breaking.** The `row` field is gone, and with it `CustomBindings.get_row_map`, `get_screen_row_map` and the `row_map` parameter of `MultiLineFooter`. A group is now one row, so a second way to assign rows could only contradict the first
+- **Breaking.** `CustomBindings.sorted_by_key` is gone, along with the alphabetical sorting it enabled. The order of the YAML file is now the order of the footer, without exception
+- **Breaking.** `MultiLineFooter` no longer takes `auto_wrap`. Passing `groups` selects the grouped layout; omitting it wraps on width, which is what the old default did
+- **Breaking.** `handle_check_action`'s keyword argument `active_group` is now `active_scope`. The word "group" now means a footer row throughout, and what it used to mean - a top-level key of the YAML file - is called a scope
+- The help overlay groups on two levels: the scope heads the section, the group is the level below it, and a scope holding a single group prints no group heading at all. The footer keeps its one-dimensional layout - the two surfaces answer different questions, which is why clibase gives them separate tables as well
+- **Breaking.** The scopes file maps each scope to a mapping of `title` and optional `key`, where it previously mapped straight to the title. One shape covers both a plain heading and a tab
+- **Breaking.** `HelpScope` is now `HelpCoverage` and `HelpRequest.scope` is `coverage`. With the overlay grouping by scope, the old name meant two things at once, which is exactly the ambiguity the group/scope split had just removed
+- The footer prints group labels in a left column of shared width, keys separated by ` · `. A group too wide to fit wraps onto continuation rows whose label cell stays blank, so the keys align under the keys rather than under the label
+- The command palette key's width is now reserved, so the last row can no longer wrap into the space it is docked in
+- `setup_logging` installs a file handler only, and now says so. Its docstring claimed "file and console logging" while installing neither a console handler nor wanting one: a console handler writes into the terminal the application is drawing on
+- The docstring layout rule of style guide 3.2.4 is enforced in the test suite as well. `tests/**` ignored the whole `D` group, so the one rule that is about layout rather than about requiring a docstring was off there too; the ignore is now `D1`
+- Text fields are read strictly: a `key`, `action` or `description` that YAML resolved to a boolean is dropped with a warning naming the fix, instead of rendering `False` as a label
+- Widths are measured in terminal cells rather than characters, so a CJK label no longer pushes the footer out of alignment
+
 ## [0.2.0] – 2026-07-19
 
 ### Added
@@ -92,4 +149,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 *PyPI name reservation – no functional code.*
 
-[0.2.0]: https://github.com/cgroening/py-termcore/compare/v0.1.1...v0.2.0 [0.1.1]: https://github.com/cgroening/py-termcore/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/cgroening/py-termcore/releases/tag/v0.1.0
+[0.4.0]: https://github.com/cgroening/py-termcore/releases/tag/v0.4.0
+[0.3.0]: https://github.com/cgroening/py-termcore/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/cgroening/py-termcore/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/cgroening/py-termcore/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/cgroening/py-termcore/releases/tag/v0.1.0

{termcore-0.2.0 → termcore-0.4.0}/CLAUDE.md

@@ -1,10 +1,10 @@
 # CLAUDE.md
 
-Project-specific instructions for termcore. The global style guide referenced in `~/.claude/CLAUDE.md` remains authoritative; this file only records what is specific to this repository.
+Project-specific instructions for termcore. This file records what is specific to this repository.
 
 ## What this project is
 
-termcore is a library, not an application. It is the foundation under termplate, which section 3.2.9 of the style guide names as the template every Textual-based TUI is checked against.
+termcore is a library, not an application. It is the foundation under termplate, the template every Textual-based TUI is checked against.
 
 That ordering has a consequence worth stating plainly: a defect here reaches every application built on the toolkit, and it reaches them silently, because applications trust a library rather than testing it. Four of the theme bugs that held up termplate lived in this repository and none of them failed loudly – they just rendered the wrong colours. Prefer failing loudly over carrying on, and prefer a test over a comment.
 
@@ -37,17 +37,18 @@ The public API of each package is re-exported through `from .module import *` in
 
 ## The defect this repository keeps producing
 
-Mutable class attributes shared by every instance. It has been found and fixed four times: `ThemeLoader._theme_names` and `_theme_data`, the four registries in `CustomBindings`, `CustomDataTable.flexible_columns` and `AppStateStorage._json_dict`. Each time the symptom was different and none of them raised.
+Mutable class attributes shared by every instance. It has been found and fixed four times: `ThemeLoader._theme_names` and `_theme_data`, the four registries in `Keymap`, `CustomDataTable.flexible_columns` and `AppStateStorage._json_dict`. Each time the symptom was different and none of them raised.
 
 Declare instance attributes annotated at class level and assign them in `__init__`, as section 3.2.5 says. `RUF012` catches the annotated-with-a-value form; it does not catch every shape, so this stays worth looking for by hand.
 
 ## Conventions particular to this repo
 
-- No boolean parameter selects behaviour anywhere in the public API. Section 1.1.2 is enforced by `FBT`, and the established answers are two named functions (`next_index` and `clamped_index`, `timing` and `timing_ns`), a classmethod factory (`ThemeLoader.custom_only`, `CustomBindings.sorted_by_key`) or an enum (`DateFormat`). Pick whichever fits the parameter; a format selector is an enum, a behaviour switch is two functions.
+- No boolean parameter selects behaviour anywhere in the public API. Section 1.1.2 is enforced by `FBT`, and the established answers are two named functions (`next_index` and `clamped_index`, `timing` and `timing_ns`), a classmethod factory (`ThemeLoader.custom_only`) or an enum (`DateFormat`, `HelpScope`). Pick whichever fits the parameter; a format selector is an enum, a behaviour switch is two functions. A fourth answer appeared with `MultiLineFooter(groups=...)`: where the two behaviours differ only in whether data was supplied, the presence of that data selects the mode and no extra parameter is needed.
 - Domain exceptions live in `termcore/io/errors.py`. A library that calls `sys.exit()` or prints an error leaves its caller no way to react – `AppStateStorage` did both until recently.
 - Diagnostics go to a module logger with lazy `%`-formatting, never to `print`. `termcore/cli/output.py` is the one module where printing is the product, and it carries a per-file ignore saying so.
 - Every SQL statement binds its values as parameters, and every identifier passes `_quoted_table` or `_quoted_column`, which check it against the schema of the open database before quoting it. The `# noqa: S608` markers state exactly what the rule cannot see. There is no other way to build a statement here.
 - A theme is identified by the `name` in its `theme.py` plus its registration prefix; the directory it lives in carries no meaning. Theme modules are imported by file path, never as a package – importing them by folder name made the first folder loaded in a process shadow every later one of the same name.
+- Every colour comes from a theme. Colour values live only in the themes' `theme.py` files and in the defaults of `termcore/cli/cli_theme.py`; stylesheets and `DEFAULT_CSS` use `$variables`, and a colour Textual has no variable for becomes a theme variable. `tests/test_theme_only_colours.py` enforces it. Single colours a user changes come in through `ThemeLoader.set_color_overrides`, never through a new code path.
 - Textual reads annotations at runtime, so type-only imports stay at module level under `termcore/tui/`. The per-file ignore for `TC002` and `TC003` in `pyproject.toml` is that rule, not an oversight.
 - hatchling ships everything inside the package directory, so runtime data (`py.typed`, the theme `.css` and `theme.py` files) needs no `package-data` entry. Every package directory does need an `__init__.py`, or it becomes an implicit namespace package that a stricter packaging tool would drop.
 - termplate is the only consumer. A breaking change is pulled through it in the same pass, and its suite has to be green before the change is finished.

{termcore-0.2.0 → termcore-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: termcore
-Version: 0.2.0
+Version: 0.4.0
 Summary: Terminal utilities for CLI, TUI, IO and general use
 Project-URL: Homepage, https://github.com/cgroening/py-termcore
 Project-URL: Repository, https://github.com/cgroening/py-termcore
@@ -76,15 +76,27 @@ clear_lines(4)
 
 | Function | Description |
 |----------|-------------|
-| `print_error(message)` | Red panel with ✗ prefix |
-| `print_warning(message)` | Yellow panel with ⚠ prefix |
-| `print_success(message)` | Green panel with ✓ prefix |
-| `print_info(message)` | Cyan panel with ℹ prefix |
+| `print_error(message)` | Error panel (theme colour, red by default) with ✗ prefix |
+| `print_warning(message)` | Warning panel (yellow by default) with ⚠ prefix |
+| `print_success(message)` | Success panel (green by default) with ✓ prefix |
+| `print_info(message)` | Info panel (cyan by default) with ℹ prefix |
 | `print_panel(message, color)` | Panel with bold colored text |
 | `print_custom_panel(formatted_message, panel_color)` | Panel with pre-formatted Rich markup |
 | `clear_lines(count)` | Move cursor up `count` lines and clear everything below |
 | `get_console()` | Returns the shared Rich `Console` instance |
 
+### Panel colours
+
+The four message panels take their colours from a `CliTheme` (defaults: red, yellow, green, cyan). An application that also has a TUI hands the CLI the TUI's theme, so both show the same colours:
+
+```python
+from termcore import ThemeLoader, cli_theme_from_textual, set_cli_theme
+
+theme = ThemeLoader("themes").get_theme("TERMCORE_xplore-blue")
+if theme is not None:
+    set_cli_theme(cli_theme_from_textual(theme))  # error, warning, success, primary
+```
+
 ## termcore.tui – Textual TUI Helpers
 
 ### ThemeLoader
@@ -127,6 +139,20 @@ Theme name prefixes:
 
 Both prefixes can be customized via the `ThemeLoader` constructor.
 
+### Single colours from the config
+
+A user who likes a theme but wants one colour different sets that colour instead of writing a theme. `set_color_overrides` takes `name -> colour` and layers it over every theme the loader registers, Textual's built-in ones included, so the change survives a theme switch:
+
+```python
+loader.set_color_overrides({
+    "primary": "#ff8800",            # a base colour of the theme
+    "footer-background": "#101010",  # any variable Textual generates
+})
+loader.register_themes_in_textual_app(app)
+```
+
+The names are a theme's base colours (`primary`, `secondary`, `accent`, `foreground`, `background`, `surface`, `panel`, `boost`, `warning`, `error`, `success`) plus every CSS variable Textual derives from them (`known_color_names()` lists them for the installed Textual). An unknown name or a value Textual cannot parse is logged and skipped; `color_override_problems` returns a message for each, so an application can show them (`unknown_color_names` lists only the names). `get_theme(name)` returns a theme with the overrides applied, without a running app.
+
 ### QuestionScreen
 
 A Textual `ModalScreen` that presents a yes/no dialog and returns a `bool`.
@@ -184,73 +210,174 @@ yield CustomSelectionList(
 )
 ```
 
+### AppHeader
+
+The header every terminal interface needs: the application name in a column of its own, then the tabs with the key that selects each, wrapping onto further rows when they do not fit. Textual's `Header` cannot do it - it is fixed at `height: 1` (3 with `-tall`) with three hard-wired slots and a `nowrap` title - and neither can `Tabs`, which is `height: 2` with `overflow: hidden` and scrolls instead of wrapping.
+
+```python
+from termcore.tui.custom_widgets.app_header import AppHeader, HeaderTab
+
+yield AppHeader(
+    "mdtask",
+    [HeaderTab(scope, bindings.scope_key(scope), bindings.scope_title(scope))
+     for scope in bindings.get_tab_scopes()],
+    active="tasks_tab",
+)
+```
+
+```text
+ mdtask   [1] Tasks │ [2] Software │ [3] Allgemein │ [4] Notes
+          [5] Quick Notes │ [6] Focus │ [7] Checklists
+```
+
+The continuation rows leave the brand cell blank but exactly as wide, so the tabs form a column. The active tab is bold at normal brightness and the others are dimmed; the separator is drawn only between tabs on the same row, never at either end of one. Set `active` to move the highlight and `set_tabs` to replace the bar.
+
+`TabbedContent` keeps its panes - hide only its own bar with `TabbedContent > ContentTabs { display: none; }` and drive `TabbedContent.active` from the key bindings `Keymap.get_tab_bindings` builds.
+
+### StatusBar
+
+One line of status: standing information on the left, a passing message on the right. Textual has no status widget - `App.notify` covers only the passing half, and only as a box docked bottom right that expires on a timer.
+
+```python
+from termcore.tui.custom_widgets.status_bar import StatusBar
+
+bar = self.query_one(StatusBar)
+bar.info = "3 tasks · 1 done · 2 open"
+bar.message = "theme: classic-black"
+```
+
+```text
+ 3 tasks · 1 done · 2 open                    theme: classic-black
+```
+
+It does not dock itself, on purpose: Textual places everything docked to one edge in the same place, so a docked status bar would sit underneath the footer it belongs above. Put it last among the flowing widgets, above the docked footer, and give the content above it `height: 1fr`.
+
+Clearing `message` is the caller's job. The convention is the next key press, which Textual dispatches before the key's own action, so an action is free to set a new message right afterwards:
+
+```python
+def on_key(self, _event: events.Key) -> None:
+    self.query_one(StatusBar).message = ""
+```
+
 ### MultiLineFooter
 
-A drop-in replacement for Textual's built-in `Footer` that supports multiple rows of key bindings. Two modes are available:
+A drop-in replacement for Textual's built-in `Footer` that supports multiple rows of key bindings. Which of its two modes applies follows from whether groups are passed:
 
-- **`auto_wrap=True`** (default) – bindings wrap automatically when the row is full.
-- **`auto_wrap=False`** – bindings are assigned to rows explicitly via `row_map`.
+- **without `groups`** – the keys wrap onto a new row whenever the current one is full.
+- **with `groups`** – each declared group becomes one row, its label printed in a column on the left and its keys separated by ` · `. A group too wide for the terminal wraps onto continuation rows whose label cell stays blank, so the keys line up under the keys rather than under the label.
 
 ```python
+from termcore.tui.keymap import Keymap
 from termcore.tui.custom_widgets.multiline_footer import MultiLineFooter
 
-# Auto-wrap (default)
+bindings = Keymap("bindings.yaml")
+
+# Wrap on width
 yield MultiLineFooter()
 
-# Manual row assignment
-yield MultiLineFooter(
-    auto_wrap=False,
-    row_map={
-        'quit': 0,
-        'save': 0,
-        'toggle_dark': 1,
-        'help': 1,
-    },
-)
+# One row per group, in the order the YAML file declares them
+yield MultiLineFooter(groups=bindings.get_groups())
+```
+
+```text
+Tasks:       a Add · d Done
+Appearance:  w Previous Theme · s Next Theme
+App:         ? Help · q Quit
 ```
 
-### CustomBindings
+`get_groups()` returns every declared group, not only the ones belonging to the current screen. A group whose bindings are not active right now renders no row at all, so the same call serves every screen.
+
+### HelpScreen
+
+The overlay every terminal interface needs: every shortcut, grouped, with a fuzzy search over them. It reads the same groups the footer does, so a binding cannot appear in one and be missing from the other.
+
+Where the footer lays those groups out in one dimension, the overlay uses two. Its outer heading is the scope - the tab or screen a shortcut works on, which is what someone opening a help screen is asking about - and the group is the inner one. A scope holding a single group prints no group heading, since repeating "Tasks" under "Tasks" tells nobody anything.
+
+```python
+from termcore.tui.binding_groups import active_actions
+from termcore.tui.help_screen import HelpScreen
+
+def action_help(self) -> None:
+    # Snapshot before the push: afterwards `self.screen` is the modal.
+    active = active_actions(self.screen)
+    self.push_screen(HelpScreen(bindings.get_groups(), active))
+```
+
+```text
+TASKS
+  a            Add
+  d            Done
+GLOBAL
+  Appearance
+    w          Previous Theme
+  App
+    q          Quit
+```
+
+It opens listing every declared shortcut. `ctrl+t` narrows the list to the bindings that would actually fire where the overlay was opened, which is what the snapshot above feeds; `escape` and `?` close it. Matching is Textual's own `Matcher`, the fuzzy search behind its command palette, so `ntm` finds "next theme".
+
+### Keymap
 
 Loads keyboard bindings from a YAML file and exposes them as Textual `Binding` objects. Supports global bindings, tab-specific bindings, and screen-specific bindings.
 
-**Group naming conventions:**
+Two words are kept apart and are not interchangeable. A **scope** is a top-level key of the file: it decides when a binding is visible and how its action is named. A **group** is one labelled footer row inside a scope: it decides only how the footer and the help overlay lay the bindings out. Grouping is optional.
 
-| Group name | Scope | Action prefix |
-|------------|-------|---------------|
+**Scope naming conventions:**
+
+| Scope name | Visibility | Action prefix |
+|------------|------------|---------------|
 | `_global` | Always visible | none (used as-is) |
 | `<name>_tab` | Shown when that tab is active | `<name>_tab_` |
 | `<name>_screen` | Shown on that screen | none (used as-is) |
 
+The order of the file is the order of the footer, without exception. Nothing is re-sorted on the way out, so a scope moved in the file moves its rows - which is why `_global` usually belongs at the bottom.
+
 **YAML example (`bindings.yaml`):**
 
 ```yaml
+tasks_tab:
+  - group: Tasks
+    bindings:
+      - key: a
+        action: add_task
+        description: Add
+      - key: d
+        action: mark_done
+        description: Done
+  - key: z            # no group: its own row, no label
+    action: zoom
+    description: Zoom
+
 _global:
-  - key: q
-    action: quit
-    description: Quit
-    priority: true
-    row: 1
+  - group: App
+    bindings:
+      - key: q
+        action: quit
+        description: Quit
+        priority: true
+```
 
-tasks_tab:
-  - key: a
-    action: add_task
-    description: Add
-    row: 0
+An entry carrying `bindings` is a group; an entry carrying `key` is a single binding. Both may be mixed inside one scope, and consecutive single bindings share one unlabelled row.
+
+**Scope display names (`scopes.yaml`):**
+
+Scope names are identifiers, not labels. A second file maps them to the names people see - the headings of the help overlay, and in an app that reads them, the labels of the tabs:
 
-add_screen:
-  - key: escape
-    action: cancel
-    description: Cancel
-    row: 0
+```yaml
+tasks_tab: "Tasks"
+add_screen: "Add dialog"
+_global: "Global"
 ```
 
+A scope with no entry there is shown under its raw name, which is meant to look unfinished rather than be quietly invented. A title naming no scope is reported, because nothing else would ever notice it. `bindings.scope_title(scope)` resolves one, and every `BindingGroup` carries the title of its own scope.
+
 **Usage:**
 
 ```python
-from termcore.tui.custom_bindings import CustomBindings
+from termcore.tui.keymap import Keymap
 
-bindings = CustomBindings("bindings.yaml")                 # file order
-bindings = CustomBindings.sorted_by_key("bindings.yaml")   # sorted by key
+bindings = Keymap("bindings.yaml")   # file order, always
+bindings = Keymap("bindings.yaml", "scopes.yaml")  # with titles
 
 # In your App or Screen:
 # On the App: globals dispatch as declared
@@ -261,13 +388,14 @@ BINDINGS = bindings.get_bindings(tab_name="tasks_tab")  # one tab + global
 BINDINGS = bindings.get_screen_bindings()               # every tab + global
 BINDINGS = bindings.get_screen_bindings("add")          # that screen + global
 
-# Row map for MultiLineFooter(auto_wrap=False):
-row_map = bindings.get_row_map()         # pair with get_bindings
-row_map = bindings.get_screen_row_map()  # pair with get_screen_bindings
+# Footer rows and help overlay, both from the same call:
+groups = bindings.get_groups()
 
 # In check_action to hide tab bindings that don't belong to the active tab:
 def check_action(self, action, parameters):
-    return bindings.handle_check_action(action, parameters, active_group=self.active_tab)
+    return bindings.handle_check_action(
+        dispatch_name(action), parameters, active_scope=self.active_tab
+    )
 ```
 
 ## termcore.io – IO Utilities
@@ -492,7 +620,7 @@ uv venv
 source .venv/bin/activate
 uv pip install -e ".[dev]"
 
-ruff check .     # linting; the rule set is the style guide's baseline
+ruff check .     # linting; rule set in pyproject.toml
 basedpyright     # strict type checking
 pytest           # tests, with coverage
 ```