gentle-shell-bridge 0.3.0 → 0.3.1

package/odd/tasks/palette-sections.md

@@ -1,30 +0,0 @@
-# ODD — plugin sections in gentle's command palette
-
-Two repos: `gentle-shell-bridge` (the API plugins call) and `gentle-shell`/gentle-pi (owner of `/gentle:commands`). Size: large (cross-repo). The user calls the palette "panel de gentle shell commands".
-
-## Specs
-
-- **S1** — A plugin adds its entries to the palette in either of two shapes: into an existing section, or as a new section of its own. User: "agregar seccioones a panel de gentle shell comands, ya sea a una seccion exxistente o con categoria nueva en commands".
-- **S2** — A contributed entry behaves like a native one: the palette lists it only while its command is registered, and selecting it runs that command.
-- **S3** — Disposing the registration removes the entry, or the section when it was the plugin's own and is left empty.
-- **S4** — Without host support the registration reports an unavailable reason through `/bridge-status`, never a silent no-op.
-- **S5** — Order and grouping stay the host's: a contributed section appears with the host's sections and does not reorder them.
-
-## Tasks
-
-- **T1** (S1, S5) — Host: catalog accepts contributed sections/items at build time, in catalog order. Route: inline.
-- **T2** (S1) — Bridge: `registerCommands` (existing section) and a section of its own, with disposer. Route: inline.
-- **T3** (S2) — Selecting a contributed entry runs the plugin's command, including when the command disappears mid-session.
-- **T4** (S3) — Dispose removes entry/section at the next palette open.
-- **T5** (S4) — Unavailable path reported through `/bridge-status`.
-- **T6** — Docs: contract.md, README, host docs.
-
-## Log
-
-- **L1** — "ahora veremos si podemos agregar 2 feactures para bridge, una es para agregar algun aparatado a panel commands [Image#1] ya sea en una seccion existe o propia, que seria ahi acciones rapidas como abrir panel etc, las que tiene."
-- **L2** — "que preguntas, sabes siquiera de que hablamos? que es este plugin bridge, ya tenemos arto integrado, ni revisaste el contexto del proyecto"
-- **L3** — "otro para agregar seccioones a panel de gentle shell comands, ya sea a una seccion exxistente o con categoria nueva en commands"
-- **L4** (evidence, explorer mwgxgx3x-1-onuz) — The palette is a curated static catalog, "not a raw listing of every registered extension command" (`gentle-shell/lib/command-palette-catalog.ts:2-4`); `buildCommandPaletteGroups` keeps only catalog entries that are registered (`:33-49`). No extension point exists for a third-party group or item.
-- **L5** (commits) — Host: `33bbe4e84` (merge of contributions in `lib/command-palette-catalog.ts`, `CONTRIBUTED_SECTION` = "Plugins" for an item that names no section). Bridge: `85f0f2b` (`registerCommands`, publishing on the same surface as keymaps).
-- **L6** (evidence) — Covered by `tests/plugin-surface.test.ts`: joins a named section, opens an own section after the catalog, and an unregistered command is not listed (also for an own section that would be left empty).
-- **L8** (delivery) — Same two PRs as plugin-keymap (bridge #6, host #80), both merged. CI never started on the host fork (0 runs for the head SHA).

package/odd/tasks/plugin-keymap.md

@@ -1,32 +0,0 @@
-# ODD — plugin keymaps in gentle's Customize Keymap page
-
-Two repos: `gentle-shell-bridge` (the API plugins call) and `gentle-shell`/gentle-pi (the owner of the Keymaps page, the bindings file and the collision rules). Size: large (multi-session, cross-repo, contract-level).
-
-## Specs
-
-- **S1** — A plugin registers one keymapped action through the bridge and the host lists it on the `Keymaps` page of `/gentle:customize`. User: "registrar keymap en customize keymap, para que aparezca ahi".
-- **S2** — That row is edited with the host's own gestures on that page (Enter assigns, ⌫ disables, r restores the default), persists where the host persists its keymaps and applies after `/reload`. User: "se pueda modificar desde ahi el keymap del plugin" and "sumo compativlidad para modificar mendiante customize keymap de gentle".
-- **S3** — The binding is real, not advertised: the plugin can resolve its own effective key and register the shortcut itself, so the row never claims a key that does nothing.
-- **S4** — The host stays the single registry: environment overrides, reserved Pi keys and duplicate-key checks keep working for plugin ids exactly as for native ones. User's "compatibilidad" means the native rules, not a bypass.
-- **S5** — Disposing the registration removes the plugin's row; a stale row or a stale key must not survive it.
-- **S6** — Without host support, `registerKeymap` reports an unavailable reason through `/bridge-status`; it never fails silently.
-
-## Tasks
-
-- **T1** (S1, S6) — Host: extension-facing registry for keymap actions, and the bridge reads it. Route: inline.
-- **T2** (S1, S2) — Host: `buildKeymapRows` and the collision helpers accept registered ids. Route: inline.
-- **T3** (S1, S3) — Bridge: `registerKeymap` in the published API, disposer, and effective-key resolution for the plugin. Route: inline.
-- **T4** (S4) — Collision + env-lock parity pinned by tests on both sides. Route: inline.
-- **T5** (S2, S5) — End-to-end: register, reassign from the page, `/reload`, key works; dispose, key gone.
-- **T6** — Docs: contract.md, README, and the host's docs for the new surface.
-
-## Log
-
-- **L1** — "ahora veremos si podemos agregar 2 feactures para bridge, una es para agregar algun aparatado a panel commands [Image#1] ya sea en una seccion existe o propia, que seria ahi acciones rapidas como abrir panel etc, las que tiene. Y otra para registrar keymap en customize keymap, para que aparezca ahi y se pueda modificar desde ahi el keymap del plugin integra y sumo compativlidad para modificar mendiante customize keymap de gentle."
-- **L2** — "que preguntas, sabes siquiera de que hablamos? que es este plugin bridge, ya tenemos arto integrado, ni revisaste el contexto del proyecto"
-- **L3** — "Y ahora ve como integrar lo que pedi, el bridge para registrar keymap de un plugin en gentle customize keymap. y otro para agregar seccioones a panel de gentle shell comands, ya sea a una seccion exxistente o con categoria nueva en commands"
-- **L4** (evidence, explorer mwgxgx3x-1-onuz) — Host today: rows only from the static `KEYMAP_ACTIONS` (`gentle-shell/lib/keymaps.ts:34`) plus curated-catalog commands (`lib/keymaps-customize.ts:64-67`); no third-party registry of any kind; `keymaps.json` persists unknown ids (`parseKeymapFile`) but `keymapOwner`/`checkKeymap` ignore them, so an unknown id gets no row, no binding and no collision check. Bridge refuses the category at `src/row-names.ts:119-120` and `src/bus.ts:121-138`.
-- **L5** (commits) — Host half: `33bbe4e84` on `feat/plugin-surfaces` in the gentle-shell worktree (5 files, 320 lines): `lib/plugin-surface.ts` reader, contributed actions in `lib/keymaps.ts` (lookup, effective key, source, collisions), the published keymap resolver, and `lib/keymaps-customize.ts` listing them. Bridge half: `85f0f2b` on `feat/plugin-surfaces` (6 files, 398 lines): `src/plugin-surface.ts`, the three optional API members, and the export/API contract lists.
-- **L6** (evidence) — Host tests: `tests/plugin-surface.test.ts` 12/12; with `keymaps` and `keymaps-customize`, 25/26 — the one failure is `tests/command-palette.test.ts` unable to resolve `@earendil-works/pi-coding-agent` because neither checkout has `node_modules` installed (pre-existing, environment). Bridge tests: 691/691.
-- **L7** (delivery defect + fix) — The first delivery was NOT visible: Pi loads the host from the installed git checkout (`/home/jona/.pi/agent/git/github.com/Gentleman-Programming/gentle-shell`, at 3dc902975) and the bridge from `gentle-shell-bridge-worktrees/bash-card-identity`, neither of which had this work. Restarting Pi could not help. Fix, applied to the running copies: `git apply` of the host patch onto the installed checkout (its `lib/keymaps.ts`, `lib/keymaps-customize.ts`, `lib/command-palette-catalog.ts` are byte-identical to the base commit, so it applies cleanly), and the bridge package entry in `~/.pi/agent/settings.json` repointed to `../../dev/projects/gentle-shell-bridge` (backup `settings.json.bak-plugin-surface`). Verified by importing the INSTALLED `lib/keymaps.ts`/`lib/keymaps-customize.ts`/`lib/command-palette-catalog.ts` with a published surface: action listed, row `Bash card: report state: alt+b`, palette group `Panel`, and the resolver answering `alt+b`. The installed checkout is now a dirty working tree: a package update replaces it and the patch must be reapplied (or the branch merged upstream).
-- **L9** (delivery) — Bridge PR jonasotoaguilar/gentle-shell-bridge#6 merged as `90704ca`; host PR jonasotoaguilar/gentle-shell#80 merged as `b61559cf6`. Both merge commits, no squash. CI on the host fork never ran: `actions/runs?head_sha=33bbe4e8…` returned `total_count: 0` while the workflow is active and Actions is enabled — a GitHub-side condition, not a code failure; the proof for this change is the local suites plus the live TUI confirmation (L8). The installed upstream checkout still carries the hand-applied patch, so it is unaffected by the fork merge.

package/odd/tasks/plugin-surface-contract.md

@@ -1,55 +0,0 @@
-# Wire contract — the bridge publishes, the host reads
-
-Two repos, one handshake. The bridge already publishes its API at module load on
-`Symbol.for("gentle-shell-bridge/api/v1")`; this contract adds a second, narrower global that
-holds the plugin contributions the host must render. Direction matters: **the bridge publishes
-and the host reads lazily**, so no load order, no session_start race, and no lifecycle in the host.
-
-## The global
-
-```ts
-Symbol.for("gentle-shell-bridge/plugin-surface/v1")
-```
-
-```ts
-interface PluginSurface {
-  schema: 1;
-  /** Live: the host calls this per menu/palette build, never once at startup. */
-  keymaps(): readonly PluginKeymapAction[];
-  commands(): readonly PluginCommandContribution[];
-}
-
-interface PluginKeymapAction {
-  /** Plugin-owned, stable, never a built-in id and never `command:<name>`. */
-  id: string;
-  label: string;
-  /** Optional environment variable that overrides the key, same semantics as a built-in action. */
-  env?: string;
-  defaultKey?: string;
-  /** The slash command this action invokes, when it has one. */
-  command?: string;
-}
-
-interface PluginCommandContribution {
-  id: string;
-  /** An existing palette section title, or a new one the plugin owns. */
-  section?: string;
-  label: string;
-  /** The slash command the palette runs. Listed only while this command is registered. */
-  command: string;
-}
-```
-
-## Rules both sides obey
-
-1. **Absent or malformed is empty.** A host that finds no global, a wrong `schema`, a throwing
-   getter or a bad entry renders nothing from it and never throws. Fail closed, entry by entry.
-2. **Live reads.** The host calls `keymaps()`/`commands()` at build time. A registration made
-   during `session_start` is visible at the next menu or palette open; nothing is cached at startup.
-3. **The host keeps ownership of its own rules.** A contributed key obeys the same reserved Pi
-   keys, environment lock and duplicate-key checks as a native one; a contributed id takes part in
-   collision detection exactly like a built-in id. No bypass.
-4. **The plugin binds its own key.** `pi.registerShortcut` is called by the plugin (or the bridge
-   on its behalf), never invented by the host; the host only renders the row and checks the key.
-5. **No new host-side lifecycle.** The host never disposes a contribution. Removal is the bridge's
-   disposer, and the next build simply stops seeing it.

package/test/api.test.ts

@@ -1,395 +0,0 @@
-/**
- * The runtime handshake (S1, S5 "zero extra steps"): the published API object, its shape gate and
- * the `bridgeApi()` helper a plugin calls from its own `session_start` handler.
- *
- * A plugin and the bridge are two independent projects. Pi gives them one sanctioned channel that
- * needs no path: `globalThis`. These tests pin that channel only — the symbol, the frozen object,
- * the gate and the absent-means-absent rule — because a path or an environment variable is exactly
- * what the rejected design offered and what this design replaces.
- */
-
-import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import test from "node:test";
-
-import {
-  API_SCHEMA,
-  API_VERSION,
-  BRIDGE_API_KEY,
-  VERSION,
-  bridgeApi,
-  isBridgeApi,
-  publishBridgeApi,
-  resetBridgeApiForTests,
-} from "../src/api.ts";
-import {
-  resetBusForTests,
-  resetSectionsForTests,
-  snapshotProviders,
-  snapshotSections,
-} from "../src/bus.ts";
-import { disableCaptureBackend, getCaptureDiagnostics, resetCaptureStateForTests } from "../src/capture.ts";
-import gentleShellBridge, {
-  type BridgeExtensionApi,
-  type BridgeSessionHandler,
-} from "../src/extension.ts";
-import { resetHookStateForTests } from "../src/hook.ts";
-import { resetNoticesForTests, snapshotNotices } from "../src/notices.ts";
-import { resetRowBuildStateForTests } from "../src/rows.ts";
-import {
-  disableSidebarBackend,
-  resetSidebarStateForTests,
-} from "../src/sidebar.ts";
-import { resetSectionFailuresForTests } from "../src/sidebar-render.ts";
-import { resetStoreStateForTests } from "../src/store.ts";
-import type { RowProvider, SidebarSection } from "../src/types.ts";
-import { createFakeHost, type FakeHost, type FakeUiTarget } from "./fake-host.ts";
-import {
-  cardBody,
-  cardTitles,
-  fakeTui,
-  registerNativeFooter,
-  resetSidebar,
-} from "./fake-sidebar.ts";
-
-const hostSlot = (): Record<symbol, unknown> => globalThis as unknown as Record<symbol, unknown>;
-
-const provider = (id: string): RowProvider => ({ id, category: "Cards", rows: () => [] });
-const section = (id: string, title = "MUSIC"): SidebarSection => ({
-  id,
-  title,
-  meta: () => "1 playing",
-  lines: () => ["track  one"],
-});
-
-/** Every terminal write the process would show; the bridge must produce none. */
-const captureConsole = (): { writes: string[]; restore: () => void } => {
-  const writes: string[] = [];
-  const sink = (globalThis as unknown as { console: { log: unknown; warn: unknown; error: unknown } })
-    .console;
-  const original = { log: sink.log, warn: sink.warn, error: sink.error };
-  const record =
-    (method: string) =>
-    (...args: unknown[]): void => {
-      writes.push(`${method}: ${args.map((arg) => String(arg)).join(" ")}`);
-    };
-  sink.log = record("log");
-  sink.warn = record("warn");
-  sink.error = record("error");
-  return {
-    writes,
-    restore: () => {
-      sink.log = original.log;
-      sink.warn = original.warn;
-      sink.error = original.error;
-    },
-  };
-};
-
-let configHome: string;
-let previousConfigHome: string | undefined;
-
-test.before(() => {
-  configHome = mkdtempSync(join(tmpdir(), "gsb-api-"));
-  previousConfigHome = process.env.GENTLE_PI_CONFIG_HOME;
-  process.env.GENTLE_PI_CONFIG_HOME = configHome;
-});
-
-test.after(() => {
-  if (previousConfigHome === undefined) delete process.env.GENTLE_PI_CONFIG_HOME;
-  else process.env.GENTLE_PI_CONFIG_HOME = previousConfigHome;
-  rmSync(configHome, { recursive: true, force: true });
-});
-
-test.beforeEach(() => {
-  rmSync(join(configHome, "gentle-shell-bridge"), { recursive: true, force: true });
-  resetBridgeApiForTests();
-  resetNoticesForTests();
-  resetBusForTests();
-  resetSectionsForTests();
-  resetSidebar();
-  resetSidebarStateForTests();
-  resetSectionFailuresForTests();
-  resetStoreStateForTests();
-  resetCaptureStateForTests();
-  resetHookStateForTests();
-  resetRowBuildStateForTests();
-  disableCaptureBackend();
-  disableSidebarBackend();
-});
-
-test.afterEach(() => {
-  disableCaptureBackend();
-  disableSidebarBackend();
-});
-
-// ---------------------------------------------------------------------------------------------
-// The published object
-// ---------------------------------------------------------------------------------------------
-
-test("publishing stores one frozen, versioned API object at the stable symbol", () => {
-  const api = publishBridgeApi();
-
-  assert.equal(hostSlot()[BRIDGE_API_KEY], api, "the slot holds exactly the object published");
-  assert.ok(Object.isFrozen(api), "the published contract is frozen: nobody may extend it in place");
-  assert.deepEqual(Object.keys(api).sort(), [
-    "VERSION",
-    "createStore",
-    "registerCardStyle",
-    "registerCommands",
-    "registerKeymap",
-    "registerRows",
-    "registerSection",
-    "registerToolDesign",
-    "registerTransform",
-    "requestRepaint",
-    "resolveKeymap",
-    "schema",
-    "version",
-  ]);
-  assert.equal(api.schema, "gentle-shell-bridge/api");
-  assert.equal(api.version, 1);
-  assert.equal(api.VERSION, VERSION);
-  assert.equal(api.schema, API_SCHEMA);
-  assert.equal(api.version, API_VERSION);
-  assert.equal(isBridgeApi(api), true);
-});
-
-test("the published functions are the working ones, not a stale copy", () => {
-  const api = publishBridgeApi();
-
-  const disposeRows = api.registerRows(provider("loon.banner-source"));
-  const disposeSection = api.registerSection(section("loon.music"));
-
-  assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["loon.banner-source"]);
-  assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
-
-  disposeSection();
-  disposeRows();
-  assert.deepEqual(snapshotProviders(), []);
-  assert.deepEqual(snapshotSections(), []);
-});
-
-test("the shape gate accepts only the v1 surface it advertises", () => {
-  const valid = {
-    schema: API_SCHEMA,
-    version: API_VERSION,
-    registerRows: () => () => {},
-    registerSection: () => () => {},
-    createStore: () => ({}),
-  };
-
-  assert.equal(isBridgeApi(valid), true);
-
-  // Every mismatch is "absent", so the caller sees `undefined` instead of an error path.
-  for (const rejected of [
-    undefined,
-    null,
-    "gentle-shell-bridge",
-    42,
-    {},
-    { ...valid, schema: "gentle-shell-bridge/api/v2" },
-    { ...valid, version: 2 },
-    { ...valid, version: "1" },
-    { schema: API_SCHEMA, version: API_VERSION },
-    { ...valid, registerRows: undefined },
-    { ...valid, registerSection: "nope" },
-    { ...valid, createStore: {} },
-  ]) {
-    assert.equal(isBridgeApi(rejected), false, `must reject ${JSON.stringify(rejected)}`);
-  }
-});
-
-test("a second publish keeps the first object: first wins", () => {
-  const first = publishBridgeApi();
-  const second = publishBridgeApi();
-
-  assert.equal(second, first);
-  assert.equal(hostSlot()[BRIDGE_API_KEY], first);
-});
-
-test("two loaded copies of the module publish one object and both work through it", async () => {
-  const first = publishBridgeApi();
-
-  // Pi loads every extension with `moduleCache: false`, so this package genuinely exists twice in
-  // one process. A second copy is a second module instance, not a second global slot.
-  const copyPath = new URL("../src/api.ts?second-copy", import.meta.url).href;
-  const second = (await import(copyPath)) as typeof import("../src/api.ts");
-
-  assert.equal(hostSlot()[BRIDGE_API_KEY], first, "the second copy never overwrote the slot");
-  const secondApi = second.publishBridgeApi();
-  assert.equal(secondApi, first, "and publishing again hands the same object back");
-  assert.equal(second.isBridgeApi(hostSlot()[BRIDGE_API_KEY]), true);
-
-  // Both copies register into the same process-global bus, which is what makes them interchangeable.
-  first.registerRows(provider("shared"));
-  secondApi.registerRows(provider("shared"));
-  assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["shared"]);
-  secondApi.registerSection(section("shared.section"));
-  assert.deepEqual(snapshotSections().map((registered) => registered.id), ["shared.section"]);
-});
-
-// ---------------------------------------------------------------------------------------------
-// bridgeApi(): the object or undefined, never a wait
-// ---------------------------------------------------------------------------------------------
-
-test("bridgeApi returns undefined when nothing is published, and the object once it is", () => {
-  assert.equal(bridgeApi(), undefined, "no publication is absent, full stop");
-
-  const api = publishBridgeApi();
-  assert.equal(bridgeApi(), api, "and the published object is handed back immediately");
-});
-
-test("an object that fails the gate is absent: bridgeApi returns undefined, one notice, no throw", () => {
-  for (const incompatible of [
-    { ...usableSurface(), schema: "someone-else/api" },
-    { ...usableSurface(), version: 2 },
-    { schema: API_SCHEMA, version: API_VERSION },
-  ]) {
-    resetBridgeApiForTests();
-    resetNoticesForTests();
-    hostSlot()[BRIDGE_API_KEY] = incompatible;
-    const captured = captureConsole();
-    let seen: unknown;
-    try {
-      assert.doesNotThrow(() => {
-        seen = bridgeApi();
-      });
-    } finally {
-      captured.restore();
-    }
-
-    assert.equal(seen, undefined, "a mismatched object is never handed to a plugin");
-    assert.equal(hostSlot()[BRIDGE_API_KEY], incompatible, "the slot is left exactly as it was");
-    assert.deepEqual(captured.writes, [], "the skew is never written to the terminal");
-    const notices = snapshotNotices().entries;
-    assert.equal(notices.length, 1, "and it is recorded once, not per call");
-    assert.match(notices[0].message, /incompatible|unsupported|version|not the/u);
-    assert.match(notices[0].message, /absent|ABSENT/u);
-    assert.match(notices[0].message, /left/u);
-    assert.doesNotMatch(notices[0].message, /queue/u, "the notice never mentions a removed queue");
-  }
-});
-
-const usableSurface = (): Record<string, unknown> => ({
-  schema: API_SCHEMA,
-  version: API_VERSION,
-  registerRows: () => () => {},
-  registerSection: () => () => {},
-  createStore: () => ({ get: () => undefined, set: () => {} }),
-});
-
-test("an incompatible slot is never reset, and publishing still yields a working API", () => {
-  const incompatible = { ...usableSurface(), version: 2 };
-  hostSlot()[BRIDGE_API_KEY] = incompatible;
-  const captured = captureConsole();
-  let published: ReturnType<typeof publishBridgeApi> | undefined;
-  try {
-    published = publishBridgeApi();
-  } finally {
-    captured.restore();
-  }
-
-  assert.deepEqual(captured.writes, []);
-  assert.equal(hostSlot()[BRIDGE_API_KEY], incompatible, "the slot is left exactly as it was");
-  assert.equal(isBridgeApi(hostSlot()[BRIDGE_API_KEY]), false);
-  assert.equal(bridgeApi(), undefined, "and consumers still see it as absent");
-  assert.ok(published !== undefined, "this copy still has an object to register through");
-  assert.equal(isBridgeApi(published), true);
-  published.registerSection(section("loon.music"));
-  assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
-});
-
-// ---------------------------------------------------------------------------------------------
-// Through the entry: a plugin registers from its own session_start handler
-// ---------------------------------------------------------------------------------------------
-
-type UiWithWidget = FakeUiTarget & {
-  setWidget?: (key: string, factory: (tui: unknown, theme: unknown) => unknown) => void;
-};
-
-const installWidgetSurface = (host: FakeHost): void => {
-  const ui = host.ui as UiWithWidget;
-  ui.setWidget = (_key, factory) => {
-    factory(fakeTui(), { name: "fake-theme" });
-  };
-};
-
-const armThroughEntry = (host: FakeHost): void => {
-  const handlers: BridgeSessionHandler[] = [];
-  const pi: BridgeExtensionApi = {
-    // `gentle-pi` is present, so `session_start` arms (S9/T12).
-    getCommands: () => [{ name: "gentle:customize" }],
-    on(event, handler) {
-      if (event === "session_start") handlers.push(handler);
-    },
-    registerCommand() {},
-  };
-  gentleShellBridge(pi);
-  assert.equal(handlers.length, 1);
-  handlers[0]({}, { hasUI: true, ui: host.ui });
-};
-
-test("a plugin that registers from session_start renders its section and its Sections toggle", () => {
-  const host = createFakeHost();
-  installWidgetSurface(host);
-  registerNativeFooter(); // the host's own rail
-
-  publishBridgeApi(); // the bridge loaded, as it always does before any session_start
-
-  const api = bridgeApi();
-  assert.ok(api !== undefined, "the API is present in the handler: no waiting, no queue");
-  api.registerRows({
-    id: "loon.banner-source",
-    category: "Cards",
-    rows: () => [
-      {
-        category: "Cards",
-        label: "Loon banner source",
-        choice: { setting: "Loon banner source", value: "on", current: () => true },
-        action: () => {},
-      },
-    ],
-  });
-  api.registerSection(section("loon.music"));
-  assert.deepEqual(snapshotProviders().map((registered) => registered.id), ["loon.banner-source"]);
-  assert.deepEqual(snapshotSections().map((registered) => registered.id), ["loon.music"]);
-
-  armThroughEntry(host); // session_start
-  host.buildMenu();
-
-  assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"], "the registered section reached the rail");
-  assert.deepEqual(cardBody("MUSIC"), ["track  one"]);
-  const toggle = host.toggleLines().find((line) => line.startsWith("music "));
-  assert.ok(toggle !== undefined, "and its toggle reached Sections");
-  assert.ok(toggle.includes("● shown") && toggle.includes("○ hidden"));
-  assert.ok(
-    host.toggleLines().some((line) => line.startsWith("Loon banner source")),
-    "the provider's rows reached the menu too",
-  );
-});
-
-test("PRESERVE: a session_start without a UI still arms nothing", () => {
-  const handlers: BridgeSessionHandler[] = [];
-  const pi: BridgeExtensionApi = {
-    getCommands: () => [{ name: "gentle:customize" }],
-    on(_event, handler) {
-      handlers.push(handler);
-    },
-    registerCommand() {},
-  };
-  gentleShellBridge(pi);
-  publishBridgeApi();
-  bridgeApi()?.registerRows(provider("queued.rows"));
-
-  handlers[0]({}, { hasUI: false });
-
-  assert.equal(getCaptureDiagnostics().armedTargets, 0, "no UI still means no arming");
-  assert.deepEqual(
-    snapshotProviders().map((registered) => registered.id),
-    ["queued.rows"],
-    "registration from a plugin handler is independent of the bridge arming",
-  );
-});