gentle-shell-bridge 0.3.0 → 0.3.2

package/docs/contract.md

@@ -7,7 +7,7 @@ What a plugin can rely on. The mechanism behind it is in
 
 ```ts
 const dispose: () => void = registerRows(provider);
-```
+```text
 
 Registers a row provider with the process-global bridge and returns a disposer
 unsubscribing exactly that provider — no other provider's rows and no bridge state are
@@ -35,7 +35,7 @@ interface RowProvider {
   name?: string;                               // optional: this plugin's INTEGRATIONS row (§8)
   rows(ctx: RowContext): CustomizeRow[];       // evaluated lazily, per menu build
 }
-```
+```text
 
 - `rows()` runs each time the menu is built, never at registration. That is what makes
   `current()` honest: the plugin reads its live state at build time, so the bullet matches
@@ -91,7 +91,7 @@ const toggle = (value: string) => ({
 });
 
 rows: () => [toggle("activity"), toggle("output")], // one rendered line
-```
+```text
 
 The renderer draws one line, `Name  ● current  ○ other`, and handles the keys itself: ←/→ moves
 the cursor inside the line and applies a value only when that row does not defer, Enter applies
@@ -151,7 +151,7 @@ Bash design                     OK    a row name: the host's own vocabulary
 Bash card → Bash rendering      BAD   arrow and a repeated qualifier: reads as a breadcrumb
 Bash card: rendering            BAD   colon
 Section: bash-card.status       BAD   prefix plus a dotted id
-```
+```text
 
 The bridge enforces the shape instead of trusting authors; it is never a silent rewrite:
 
@@ -304,7 +304,7 @@ told once, on Pi's cross-extension bus.
 Object.freeze({
   schema: "gentle-shell-bridge/api", // identity, so a foreign payload is never mistaken for ours
   version: 1,                        // the major; a breaking change is a NEW symbol key
-  VERSION: "0.3.0",                  // the publishing release; informational only
+  VERSION: "0.3.2",                  // the publishing release; informational only
   registerRows,
   registerSection,
   registerCardStyle,                 // since 0.2.0; optional on an older published object
@@ -313,7 +313,7 @@ Object.freeze({
   requestRepaint,                    // since 0.3.0; optional on an older published object
   createStore,
 });
-```
+```text
 
 Publication is **first wins**: a compatible object already in the slot is kept and never replaced,
 and the slot is never reset. A consumer gates on the schema string, `version === 1` and the three
@@ -359,7 +359,7 @@ pi.on("session_start", (_event, ctx) => {
     );
   }
 });
-```
+```text
 
 Or import the package and call `onBridgeApi(handler, pi.events)`, which does both forms for you: the
 handler runs immediately when the object is already published (and no listener is taken), otherwise
@@ -374,7 +374,7 @@ const register = (api: BridgeApi): void => {
 
 // Works in both orders: this package loaded first, or the plugin did.
 const dispose = onBridgeApi(register, pi.events);
-```
+```text
 
 `bridgeApi()` never waits, defers or retries: it answers about the slot as it is right now.
 
@@ -387,7 +387,7 @@ When this package publishes its object, it emits one event on Pi's cross-extensi
 pi.events.on("gentle-shell-bridge:ready", (payload) => {
   // { schema: "gentle-shell-bridge/api", version: 1, VERSION: "0.3.0" }
 });
-```
+```text
 
 - **Name:** `gentle-shell-bridge:ready`. Payload: `{ schema, version, VERSION }` — the same identity,
   major and release the published object carries, frozen. Informational only: the payload says
@@ -432,7 +432,7 @@ const dispose = api.registerRows({
   category: "Cards",
   rows: () => [toggle("activity"), toggle("output")], // consecutive rows → one line
 });
-```
+```text
 
 Nothing may sit between the two values or the renderer draws two lines. `current()` is evaluated
 when the menu is built, `action()` runs before the host's own repaint, and `preview()` replaces the
@@ -454,7 +454,7 @@ const dispose = api.registerSection({
   defaultVisible: true,         // absent means true
   order: 10,                    // optional integer
 });
-```
+```text
 
 The bridge generates the `Sections` rows for it: two consecutive rows sharing one label,
 values `shown` / `hidden`, with a live `current()` and a persist-first `action()`. The label — not
@@ -472,7 +472,7 @@ or writes that file.
 const store = api.createStore("loon");
 store.set("bannerSource", "activity");
 const value = store.get("bannerSource", "activity"); // caller's fallback when absent or unreadable
-```
+```text
 
 The document is `{ "schemaVersion": 1, "values": { … } }` at
 `<gentle config home>/gentle-shell-bridge/<pluginId>.json`. `values` is an envelope, so a plugin
@@ -548,7 +548,7 @@ const dispose: () => void = registerSection({
   defaultVisible: true,             // absent means true
   order: 10,                        // optional integer
 });
-```
+```text
 
 - `id` — registering an existing id **replaces** the previous section in place; a second
   card never appears. It is the toggle's identity (replacement, disposer and the persisted
@@ -582,7 +582,7 @@ A row is a plain **string** or a structured **row object**:
 
 ```ts
 { label: string; meta?: string; glyph?: string; tone?: Tone; onClick?: () => void }
-```
+```text
 
 - a plain string is drawn **byte for byte**: the author's characters, clipped to the width, no
   indent, no padding, no styling. Every section written before structured rows existed looks
@@ -626,7 +626,7 @@ child, and the conversation gets `columns - 53`. One decision IS made from a par
 
 ```text
 const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
-```
+```text
 (`lib/shell-sidebar-layout.ts:410`) — a single rail row wider than the content width drops the whole
 rail, and the conversation then takes every column: the layout's widths changed because of what a
 part returned.
@@ -706,7 +706,7 @@ label the user reads, never an id and never a prefix:
 ```text
 stats             ● shown  ○ hidden     ← the host's own row
 music             ● shown  ○ hidden     ← a plugin's section (id "loon.music", title "MUSIC")
-```
+```text
 
 For every registered section the bridge emits **two consecutive rows** in category `Sections`,
 sharing one label as their `choice.setting` (the host prints the setting as the line's name) with
@@ -752,7 +752,7 @@ one namespaced file:
     "collapsed": { "loon.music": true }
   }
 }
-```
+```text
 
 `sections` maps a section id to `true` (shown) / `false` (hidden); a missing id falls back to
 `defaultVisible`. `collapsed` maps a section id to `true` (folded) / `false` (open); a missing id is
@@ -781,7 +781,7 @@ const dispose: () => void = registerCardStyle({
   frame: { top, line, bottom }, // the three functions below; nothing else is called
   preview: () => ({ title: "Cute", sample: "○ cute  ╭─ welcome ─╮" }), // optional, literal
 });
-```
+```text
 
 The id never appears in a row: the host's line reads `Card style  ○ neon ● float ○ cute`, and the
 style's own row is labelled `cute` (or the author's `rowLabel`), exactly like a host row's visible
@@ -794,7 +794,7 @@ text. `label` stays the line's value — the text the host renders and the uniqu
 top(ctx: { width: number; title?: string; hint?: string }): string;
 line(ctx: { text: string; width: number; first: boolean }): string;
 bottom(ctx: { width: number }): string;
-```
+```text
 
 `width` is the width the host rendered at. `title` is the heading the host printed, without its
 glyph and without the right-aligned hint; `hint` is that hint when its style runs prove it is one
@@ -812,7 +812,7 @@ setting, so the user sees ONE line in the host's own position:
 
 ```text
 Card style  ○ neon ● float ○ cute
-```
+```text
 
 The host's own rows keep the host's `current()` and `action()`, wrapped in exactly two ways:
 `current()` reports `false` while a registered style is selected (one bullet at a time), and
@@ -868,7 +868,7 @@ The selection is the bridge's state, not the plugin's:
 
 ```json
 { "schemaVersion": 1, "values": { "cardStyle": "loon.cute" } }
-```
+```text
 
 `cardStyle` is a style id or `native`. A missing file, an unreadable one, an unknown
 `schemaVersion` or a non-string value reads as `native`. A stored id whose style was disposed
@@ -928,7 +928,7 @@ const dispose: () => void = registerTransform({
     return rows;
   },
 });
-```
+```text
 
 ### What the transform receives
 
@@ -1009,7 +1009,7 @@ keeps its report byte for byte:
 transforms: 2 registered
   - loon.bash-cards (order 10): applied, 13 lines, 4 candidates, 1 recognised, 1 rewritten, shapes: float 1
   - loon.strict (registration order): failed (definitions are missing), 13 lines, 0 candidates, 0 recognised, 0 rewritten
-```
+```text
 
 `applied` means the frame changed, `skipped` means the transform was called and left the rows as they
 were, `failed` carries its message, and `not run` means it was registered after the last frame. The
@@ -1034,7 +1034,7 @@ api.registerToolDesign({
     return lines.map((line) => rewriteTheMarkOnly(line));
   },
 });
-```
+```text
 
 ### The convention: lines in, lines out
 
@@ -1199,21 +1199,78 @@ The bridge registers exactly ONE `pi.registerToolRenderer` resolver for the whol
 out to these designs. That is why two plugins contributing designs for the same tool do not stack
 wrappers, and why a plugin must never call `pi.registerToolRenderer` itself for a design.
 
+## 15. Plugin keymaps and the command palette
+
+The bridge publishes what plugins contributed; the **host reads it per build**. The direction is the
+design: there is no registration handshake, no startup cache and no lifecycle in the host, so a
+registration made during `session_start` is visible at the next menu or palette open, in any load
+order.
+
+```text
+Symbol.for("gentle-shell-bridge/plugin-surface/v1") → { schema: 1, keymaps(), commands() }
+```text
+
+Both getters answer with a **copy**, never the live array, so a host that keeps one cannot mutate
+what the bridge owns.
+
+### `registerKeymap(registration): () => void`
+
+One action for the host's Keymaps page: `{ id, label, env?, defaultKey?, command? }`.
+
+- `id` and `label` must be non-empty strings; `env`, `defaultKey` and `command` are optional but,
+  when present, must be non-empty strings too. Validation happens here, where the plugin author sees
+  the error.
+- An `id` starting with `command:` is refused: those name palette command bindings, not plugin
+  actions.
+- The same `id` registered twice **replaces in place and is reported**, like every other
+  registration in this package. A silent takeover would be one plugin stealing another's row.
+- The disposer removes exactly the entry it created. A replaced entry is a different object, so
+  disposing the old registration never deletes its successor.
+- A contributed id can never shadow a built-in action or a `command:<name>` binding: the host keeps
+  its own ids.
+
+### `registerCommands(contribution | contribution[]): () => void`
+
+One palette item, or several: `{ id, label, command, section? }`.
+
+- An item joins the section it names, after that section's own entries, or opens a section of its
+  own after the host's catalog. Without `section` it lands in the shared `Plugins` page.
+- The host lists an item only while its command is registered, so a missing extension leaves no
+  dead row, and an own section that would be left empty does not appear at all.
+- An `id` twice **in one call** is refused whole: the batch would silently keep only the last one.
+  Across calls it replaces in place and is reported, exactly like keymaps.
+
+### `resolveKeymap(id): { key?; unavailable? }`
+
+The key an id currently uses, answered by the shell that owns the file, the environment override
+and the defaults — environment variable, then saved binding, then default. It never throws: no
+shell, an older shell or a throwing getter is an `unavailable` reason the caller reports.
+
+The plugin then binds the key itself with `pi.registerShortcut`. The bridge never binds for a
+plugin, and the shell never binds a plugin's key. That split is what keeps one implementation of the
+precedence: the row and the real binding cannot disagree.
+
+**A keymap change applies after `/reload`.** Pi reads extension shortcuts at startup and on reload,
+for native actions and contributed ones alike, and it exposes no way to re-register a shortcut while
+running. The Keymaps page says so, and its last row offers the reload.
+
 ## Limits
 
 - `registerRows`, `registerSection`, `registerCardStyle`, `registerTransform`,
-  `registerToolDesign`, `requestRepaint`, `createStore`, `bridgeApi`, `isBridgeApi`, `onBridgeApi`
+  `registerToolDesign`, `registerKeymap`, `registerCommands`, `resolveKeymap`, `requestRepaint`,
+  `createStore`, `bridgeApi`, `isBridgeApi`, `onBridgeApi`
   and the `gentle-shell-bridge:ready` event are the contract; anything a plugin does inside `action()` beyond
   calling inline helpers is the plugin's own business.
-- **`Keymaps` is reserved.** A provider registered with `category: "Keymaps"` is refused before
-  anything is stored, with an error naming the category and why (its own key capture and footer; not
-  open to plugins yet); the refusal is a rejected registration in the plugin's INTEGRATIONS line and in
-  `/bridge-status`. A single row whose own `category` is `Keymaps` is dropped and reported the same way,
-  and its siblings still render. The comparison is trimmed and case-insensitive: ` keymaps ` and
-  `KEYMAPS` are the same page; `Keymap` and `Key maps` are ordinary categories. `Profiles` and `Reset`
-  are not reserved: a plugin row there renders as an ordinary line. A refusal of one row is listed under
-  `row rejections` but is not counted in the plugin's INTEGRATIONS line (a build cannot reach it; only the
-  registration refusal does).
+- **`Keymaps` stays reserved for row providers.** A provider registered with `category: "Keymaps"` is
+  refused before anything is stored, with an error naming the category and why; the refusal is a rejected
+  registration in the plugin's INTEGRATIONS line and in `/bridge-status`. A single row whose own
+  `category` is `Keymaps` is dropped and reported the same way, and its siblings still render. The
+  comparison is trimmed and case-insensitive: ` keymaps ` and `KEYMAPS` are the same page; `Keymap` and
+  `Key maps` are ordinary categories. `Profiles` and `Reset` are not reserved: a plugin row there renders
+  as an ordinary line. A refusal of one row is listed under `row rejections` but is not counted in the
+  plugin's INTEGRATIONS line (a build cannot reach it; only the registration refusal does). The reason
+  is unchanged and now has a supported alternative: that page captures keys and claims a footer, so a
+  plain row would be advertised as assignable and could never honour it — a plugin uses §15 instead.
 - **A new category becomes a page.** The host computes its page list once, in the view's constructor
   (`lib/visual-customize-view.ts:387`), so the rows must be in the array before that `map` runs; see
   [architecture.md](architecture.md) "A brand-new page". The cost is stated there. The one residual
@@ -1261,6 +1318,6 @@ wrappers, and why a plugin must never call `pi.registerToolRenderer` itself for
   simply false) and keeps working.
 - A transform is a per-frame pass, so a slow transform is a slow frame; the bridge isolates its
   failures and clips its width, and can bound nothing else. It sees lines, never tool metadata.
-- The API is released (`0.3.0`). The `v1` symbol is the compatibility boundary: a breaking
+- The API is released (`0.3.2`). The `v1` symbol is the compatibility boundary: a breaking
   change takes a new key instead of mutating this one (§9). The `gentle-shell-bridge:ready` event is
   additive: a plugin that never subscribes loses nothing but the late-load case.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-shell-bridge",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shared provider bus for gentle-shell's /gentle:customize settings rows: plugins register rows, the bridge owns the single interception layer.",
   "type": "module",
   "keywords": [
@@ -10,6 +10,18 @@
     "gentle-ai",
     "extension"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonasotoaguilar/gentle-shell-bridge.git"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "docs/contract.md",
+    "docs/state.md",
+    "docs/architecture.md",
+    "README.md"
+  ],
   "pi": {
     "extensions": [
       "./src/extension.ts"

package/src/api.ts

@@ -67,7 +67,7 @@ import { createStore } from "./store.ts";
 import { registerToolDesign } from "./tool-designs.ts";
 
 /** The release that published the object; informational, never the compatibility check. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.2";
 
 /** Identity of the object, so a foreign payload at the symbol is never mistaken for ours. */
 export const API_SCHEMA = "gentle-shell-bridge/api";

package/.codegraph/.gitignore

@@ -1,5 +0,0 @@
-# CodeGraph data files — local to each machine, not for committing.
-# Ignore everything in .codegraph/ except this file itself, so transient
-# files (the database, daemon.pid, sockets, logs) never show up in git.
-*
-!.gitignore

package/PRD.md

@@ -1,144 +0,0 @@
-# PRD — gentle-shell-bridge
-
-## Problem
-
-gentle-shell renders `/gentle:customize` from an array it builds itself and never exposes:
-the `ctx.ui.custom` factory constructs a `VisualCustomizeView` and returns a six-method
-adapter, so the rows exist only inside closures
-(`extensions/gentle-shell.ts:3550`, `:3554-3561`). Any plugin that wants a settings line
-therefore reaches for the only reachable moment — the factory call — and patches the host
-to get at the rows.
-
-That works once. It does not compose. Two independent wrappers each swap
-`Array.prototype.map` around the same factory: the inner wrapper installs its patch last
-and wins the capture, the outer wrapper captures nothing and degrades to a warning. With
-the naive approach only one plugin's rows ever appear, and neither plugin can tell the
-difference until someone looks at the menu. This is the collision the bridge exists to
-remove, and it is observed behaviour, not a hypothesis: the first prototype using
-duck-typing on the returned component silently injected nothing because the view is sealed
-behind the adapter.
-
-## Users
-
-- **Plugin authors** (loon, and any future gentle-shell plugin) who want a settings row
-  without owning an interception layer, a rebind lifecycle, or a conflict policy.
-- **gentle-shell users** who want every installed plugin's settings in the one menu they
-  already open, with no plugin silently missing.
-
-## Goals
-
-1. One interception layer per process, shared by every plugin.
-2. A small, typed contract: publish a provider, get rows; dispose to remove them.
-3. Rows that reflect live state, so the `●` marker never lies.
-4. No silent failure: every absent row has a reportable reason.
-5. One place to repair when gentle-shell's internals change.
-
-## Non-goals
-
-- Not a theme pack, banner engine or card renderer; it adds rows to existing categories.
-- Not a UI framework: no widgets, layout engine, or rendering of its own.
-- Not a configuration service for gentle-shell; gentle-shell keeps its own files.
-- Not an upstream replacement: if Pi or gentle-shell ships a row-provider hook, the bridge
-  should shrink to a thin adapter over it rather than compete.
-
-## Requirements
-
-| ID | Requirement | Contract | Status |
-| --- | --- | --- | --- |
-| R1 | `registerRows(provider)` accepts providers and returns a disposer that removes exactly that provider's rows. | `registerRows`, provider shape | Implemented; unit tests plus the end-to-end suite |
-| R2 | Providers are evaluated lazily when the menu is built, in subscription order, with a context carrying at least the active theme and the resolved config home. | Provider `rows(ctx)`, ordering | Implemented; `ctx` carries the factory's theme and the resolved config home, tested |
-| R3 | The bridge supports every row kind gentle-shell's renderer understands: `category`, `label`, `choice`, `preview`, `visible`, `keyhint`, `action`. | Row kinds | Implemented as typed pass-through fields; exercised against the fake host, not the real renderer |
-| R4 | A toggle is expressed as consecutive rows sharing `choice.setting`, and works with the renderer's own `●`/`○` and arrow/Enter handling. | Toggle recipe | Implemented; the end-to-end suite shows the `●` moving after `action()` on a fake host |
-| R5 | Arm-time state is idempotent: repeated `session_start`, rebinds and double loads never double-wrap or double-inject. | Idempotency | Implemented; tested across two `session_start` events and a double entry load |
-| R6 | A throwing provider loses its rows, is reported, and never breaks the menu or other providers. | Failure isolation | Implemented; tested per provider, with the failure reported by `/bridge-status` |
-| R7 | A diagnostics command reports providers, active backend, last capture outcome and last failures. | `/bridge-status` | Implemented as `/bridge-status`; formatter and entry tested, including store problems and duplicate settings from the last menu build |
-| R8 | Composition is stateless; persistence is the plugin's, with an optional namespaced store helper. | `createStore`, [docs/state.md](docs/state.md) | Implemented; `createStore` tested against temporary directories. One documented exception: a sidebar section's visibility is bridge-owned (see R12) |
-| R9 | `registerSection(section)` adds a card to gentle-shell's sidebar and returns a disposer that removes it, with no extra step from the plugin. | `registerSection`, section shape | Implemented; end-to-end over the public API against the fake rail, never in a real TUI |
-| R10 | Each registered section automatically contributes two consecutive rows to `Sections` (a readable label derived from its title or an explicit `rowLabel`, plus `shown`/`hidden`), reading and persisting the same value the rail renders; the id stays internal and never appears in a row. | Automatic toggle rows | Implemented; the menu, the persistence file and the next rail frame are asserted together — against the fake host and fake rail — including the label derivation and the collision rule |
-| R11 | A hidden section is neither rendered nor built (`lines()`/`meta()` not called); a throwing section loses only its own body and is reported. | S7 failure isolation | Implemented; pinned with call counters and `/bridge-status` section failures, against the fake host |
-| R12 | Section visibility persists in the bridge's own store, not the host's `visual-customization.json`, which rejects unknown keys. | `bridge-sections.json`, [docs/state.md](docs/state.md) | Implemented; the document shape is asserted byte-for-byte, and the reason for the separate file is recorded |
-| R13 | `registerCardStyle(style)` accepts `{ id, label, frame: { top, line, bottom }, preview?, order? }`, validates id/label/frame before storing, replaces in place on the same id, and returns a disposer that removes exactly that style. | `registerCardStyle`, frame contract | Implemented; validation, ordering, replacement and disposal are unit-tested, and the published-API path is exercised end to end |
-| R14 | A registered style joins the host's own `Card style` line (spliced in place, one coalesced line, the host's values untouched), with a `Bridge → card style` fallback line only when the host's line is not reachable; the selection is bridge-owned state, pressing a host value returns to native rendering, and a disposed style degrades to `native`/`missing`. | `bridge-card-style.json`, [docs/contract.md](docs/contract.md) §12 | Implemented; one bullet at a time, the way back, the fallback line and the missing-selection degrade are pinned against the fake host and reported by `/bridge-status` |
-| R15 | When a registered style is selected, the bridge repaints the conversation frames the host already drew — detection, title/hint extraction, one style at a time, width clipping, and a pass-through for `native`, for a missing selection and for any throw — and reports the frame outcome. | [docs/architecture.md](docs/architecture.md) §14 | Implemented; proven against a fake conversation built from real `shell-card.ts` output, plus the end-to-end suite through the public API. A downstream post-processor can override the frame, which `/bridge-status` states |
-| R16 | `registerTransform(transform)` accepts `{ id, order?, transform(lines, ctx) }`, validates the id and the function before storing, replaces in place on the same id and returns a disposer that removes exactly that transform; the conversation wrapper runs the card-style repaint first and then every transform in order, each receiving the previous output, clipping the result to the host width, isolating a throw or a non-lines return to that transform, and returning the host's own array when nothing changed; `/bridge-status` lists the pipeline in order with the last frame's outcome per transform. | `registerTransform`, [docs/contract.md](docs/contract.md) §13 | Implemented; ordering, replacement, disposal, identity, clipping, throw isolation and the status block are unit-tested, and the worked example's toggle is proven to restyle cards already on screen, with past and new cards byte-identical |
-
-Sixteen requirements are implemented and covered by the 367-test `node --test` suite, 26 of them
-end to end through the public API and the real extension entry. What is proven and what is not:
-
-- **Proven against a fake host.** The row side drives a fake menu host that models
-  `gentle-shell.ts:3550-3562`: injection, ordering, toggles, failure isolation and the
-  diagnostics lines.
-- **Proven against a fake conversation.** The card-style side drives a fake transcript built from
-  real `gentle-shell/lib/shell-card.ts` output at a fixed width, plus a fake `tui` that models Pi's
-  documented tree: detection, repaint, clipping, the pass-through paths, the disposal degrade, the
-  host line splice, the fallback line and the generation guard. The transform pipeline drives the
-  same conversation through the real wrapper: ordering, identity, clipping, per-transform throw
-  isolation and the `/bridge-status` block — plus the worked example's `Bash rendering` toggle, end
-  to end, where a card drawn before the switch and one drawn after it come out byte-identical.
-- **Proven against a fake rail.** The sidebar side drives a fake terminal that models
-  `lib/shell-sidebar.ts`'s state symbol and `parts` map plus the layout's card frame
-  (`lib/shell-sidebar-layout.ts:35-44,392-410`): section cards, ordering, the `Sections` rows,
-  the store file, hiding and failure isolation.
-- **Not proven in a running TUI.** Neither surface has been re-run inside a real Pi +
-  gentle-shell session through the package. In particular the sidebar's `tui` is acquired
-  through `ctx.ui.setWidget`, and whether a widget whose component renders no rows leaves the
-  editor area visually untouched is **unconfirmed**. R7's hook branch has never met a host
-  that exposes the registry it looks for.
-- The capture technique itself is proven in the real TUI by the reference probe, not by these
-  tests.
-- **The card-style repaint has not been seen in a live TUI.** It depends on the host's `float`
-  grammar and on Pi's component tree; both are cited, neither is observed at runtime here, and a
-  downstream post-processor can erase the frame — reported, not prevented.
-
-## Success criteria
-
-- Two independent providers coexist in one menu, each with its own rows and no lost
-  capture.
-- A toggle persists through `action()`, the menu re-renders, and the `●` moves to the
-  applied value.
-- No silent failure: an uncaptured menu, a broken provider or a duplicate `setting` is
-  visible in `/bridge-status`.
-- When gentle-shell changes its menu construction, exactly one module needs repair.
-- A plugin can add a card style with one call: the value appears on the host's own `Card style`
-  line, selecting it repaints every card the host drew, and selecting a host value or losing the
-  plugin returns the conversation to the host's rendering.
-- A plugin can apply a rendering choice to the WHOLE conversation with one call: the choice reaches
-  cards drawn before the switch, not only the next one, and the worked example proves that a bash
-  card drawn before and one drawn after are byte-identical.
-- The reference probe's observed result reproduces through the package against the fake host
-  that models the real call chain: a `Cards` category showing the injected line
-  `Card bash   ● activity ○ output`. It has not yet been re-run in the real TUI through the
-  package.
-
-## Risks and open questions
-
-- **Upstream hook availability.** If Pi or gentle-shell adds a supported row-provider
-  registry, the capture backend becomes dead weight; the contract should stay stable
-  across that switch. A hook backend now exists (`src/hook.ts`) and prefers a recognized
-  registry over patching, but no host has been observed emitting
-  `Symbol.for("gentle-pi.customize-row-providers")` — that branch is implemented and
-  unverified.
-- **Namespace policy.** Requiring namespaced `setting` names (`"Loon → Banner source"`)
-  avoids accidental merges but depends on authors complying; the bridge can warn on
-  duplicates but cannot rename rows without breaking identity.
-- **Whether the store belongs in the package at all.** It is the only piece that writes to
-  disk and the only piece a plugin could implement itself. Shipping it is a convenience
-  bet, recorded with its alternatives in [docs/state.md](docs/state.md).
-- **Diagnostics spelling.** Settled in code: the command is `/bridge-status`. Pi has no
-  built-in `/status`, and gentle-shell's commands live under the `gentle:` prefix, so a bare
-  `bridge-status` collides with neither. It has not yet been typed into a real host.
-- **Compatibility drift.** The capture depends on one constructor line and one adapter
-  shape; every gentle-shell upgrade is a potential silent break until an upstream hook
-  exists. The sidebar surface depends on the same class of internals: the state symbol, the
-  `parts` map and the hard-coded rail key order.
-- **The sidebar widget's visual footprint is unconfirmed.** Pi exposes no `tui` getter, so the
-  bridge acquires one through `ctx.ui.setWidget` and returns a component that paints nothing.
-  Whether that component leaves the editor area untouched has not been observed; if it does
-  not, the fix is the widget's rendering, not the contract.
-- **Sections cannot be interleaved with the native cards.** The host builds its status
-  sections inside a closure, so "after every native section" is the honest contract; a user
-  request to slot a section between `CHANGES` and `STATS` cannot be met without an upstream
-  change.
-- **Bridge-owned visibility is new state.** It is one namespaced file the bridge writes; a
-  future host that opens `VISUAL_SECTION_KEYS` would make it redundant and it should then be
-  migrated rather than duplicated.