gentle-shell-bridge 0.0.0-stage → 0.3.0

package/odd/tasks/palette-sections.md

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,32 @@
+# 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

@@ -0,0 +1,55 @@
+# 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/package.json

@@ -1,6 +1,37 @@
 {
   "name": "gentle-shell-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "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": [
+    "pi-package",
+    "pi",
+    "gentle-shell",
+    "gentle-ai",
+    "extension"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,492 @@
+/**
+ * The runtime handshake: how a plugin reaches this bridge without a path, an environment variable
+ * or an import.
+ *
+ * Pi gives two independent projects exactly one sanctioned channel that needs no install detail:
+ * `globalThis` (`docs/extensions.md:1965-1972`). So the package publishes a frozen, versioned
+ * service object at a stable symbol, at module load:
+ *
+ * ```ts
+ * Symbol.for("gentle-shell-bridge/api/v1") → { schema, version, VERSION, registerRows,
+ *                                              registerSection, registerCardStyle,
+ *                                              registerTransform, registerToolDesign,
+ *                                              createStore, requestRepaint }
+ * ```
+ *
+ * A plugin registers from its own `session_start` handler. But Pi does NOT guarantee that this
+ * package loaded first: the real TUI showed global extensions (`~/.pi/agent/extensions`) loading —
+ * and receiving `session_start` — before a configured package's module ever published. So the
+ * symbol's presence is the complete answer only when it is present. When it is absent, the plugin
+ * still needs a way to hear about a bridge that publishes later, and it hears it on Pi's own
+ * cross-extension bus (`docs/extensions.md:1965-1972`):
+ *
+ * ```ts
+ * pi.events.on("gentle-shell-bridge:ready", ({ schema, version, VERSION }) => …)
+ * ```
+ *
+ * The bridge emits that event once per process, after a successful publish and never for an
+ * incompatible slot (`announceBridgeReady`). A plugin that imports this package calls
+ * `onBridgeApi(handler, pi.events)`, which serves it immediately when the object is already there
+ * and subscribes when it is not. The symbol stays the authority: the announcement only says "look
+ * again", so a copy that publishes an incompatible slot announces nothing and a listener that
+ * hears the event still gates on the object itself.
+ *
+ * Why a symbol instead of a path or `GENTLE_SHELL_BRIDGE_MODULE`: a path is not a contract between
+ * two projects — it names one checkout on one machine, and it breaks the day either project moves.
+ * The symbol key is the contract, and `v1` in the key is the major version: a future major takes a
+ * NEW key rather than mutating this one. `pi-lens` publishes its IO bridge the same way
+ * (`clients/io-bridge-contract.ts:26-31`, `clients/process-bridge.ts:31-66`): stable symbol, a
+ * version constant, a frozen non-writable slot, and "version mismatch means unsupported".
+ *
+ * ## First wins, and nothing is ever reset
+ *
+ * Pi loads every extension through its own jiti loader with `moduleCache: false`, so this module
+ * exists once per copy. Every copy's functions operate on the same process-global bus
+ * (`./bus.ts`, `./store.ts`), which makes them interchangeable: whoever publishes first owns the
+ * slot, and later copies hand the same object back. A slot that holds something incompatible is
+ * treated as ABSENT — never overwritten, never deleted.
+ *
+ * ## Version skew
+ *
+ * Consumers gate on the schema string, `version === 1` and the three callable members
+ * (`isBridgeApi`). A mismatch is not an error and never a fallback to a half-working object: the
+ * caller sees `undefined`, and one notice is recorded per process (the TUI shows it once and
+ * `/bridge-status` keeps reporting it).
+ *
+ * ## Why the gate is also documented inline
+ *
+ * A plugin that does not depend on this package must be able to do the same thing in about six
+ * lines, so README.md carries the inline copy of the gate and the symbol. Keep the two in sync.
+ */
+
+import { registerCardStyle, registerRows, registerSection, registerTransform } from "./bus.ts";
+import { recordNotice } from "./notices.ts";
+import { registerCommands, registerKeymap, resolveKeymap } from "./plugin-surface.ts";
+import { requestRepaint } from "./repaint.ts";
+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";
+
+/** Identity of the object, so a foreign payload at the symbol is never mistaken for ours. */
+export const API_SCHEMA = "gentle-shell-bridge/api";
+
+/** Major version of the published shape. A breaking change means a new symbol key. */
+export const API_VERSION = 1;
+
+/** The published service object's stable, process-global key. */
+export const BRIDGE_API_KEY: symbol = Symbol.for("gentle-shell-bridge/api/v1");
+
+/**
+ * The channel this package announces itself on, on Pi's cross-extension bus.
+ *
+ * A plugin loaded before this package has no object to read yet, so it subscribes here. The
+ * announcement is a notification, never a registry: it says "the object is published now", and the
+ * listener reads the symbol. That keeps one authority (the symbol and its shape gate) and one
+ * channel for the timing.
+ */
+export const BRIDGE_READY_EVENT = "gentle-shell-bridge:ready";
+
+/** What the announcement carries: identity, major version and the publishing release. */
+export interface BridgeReadyPayload {
+  readonly schema: typeof API_SCHEMA;
+  readonly version: typeof API_VERSION;
+  readonly VERSION: string;
+}
+
+/**
+ * The two members of `pi.events` this package uses (`docs/extensions.md:1965-1972`). Both are
+ * optional so a host without a bus is a normal case, not a type error: no bus means the symbol is
+ * the only channel, which is exactly how this worked before.
+ */
+export type BridgeEventUnsubscribe = () => void;
+
+export interface BridgeEventBus {
+  emit?(channel: string, data: unknown): void;
+  on?(channel: string, handler: (data: unknown) => void): BridgeEventUnsubscribe | void;
+}
+
+/** The one payload every announcement carries; frozen like the published object. */
+const READY_PAYLOAD: BridgeReadyPayload = Object.freeze({
+  schema: API_SCHEMA,
+  version: API_VERSION,
+  VERSION,
+});
+
+/**
+ * Bookkeeping for "one announcement per process", keyed by a symbol so two copies of this module
+ * share it, exactly like the slot and the skew notice.
+ */
+const READY_KEY: symbol = Symbol.for("gentle-shell-bridge/api/v1.ready");
+
+/** Bookkeeping for "one skew notice per process", kept off module scope for the same reason as the bus. */
+const WARNED_KEY: symbol = Symbol.for("gentle-shell-bridge/api/v1.warned");
+
+/** The object published at `BRIDGE_API_KEY`. */
+export interface BridgeApi {
+  readonly schema: typeof API_SCHEMA;
+  readonly version: typeof API_VERSION;
+  /** The publishing release, e.g. `"0.2.0"`. Informational. */
+  readonly VERSION: string;
+  readonly registerRows: typeof registerRows;
+  readonly registerSection: typeof registerSection;
+  /**
+   * Card styles (S1). Absent only on an object published by a copy that predates this surface: the
+   * slot is first-wins, so a mixed-copy process can hand back the older object. The shape gate does
+   * NOT demand it, deliberately — an older object is still a usable bridge for rows, sections and
+   * the store, and a plugin that needs card styles checks `typeof api.registerCardStyle ===
+   * "function"` before using it. Demanding it here would turn a working bridge into "absent" for
+   * every row-only plugin.
+   */
+  readonly registerCardStyle?: typeof registerCardStyle;
+  /**
+   * Transcript transforms (S1). Optional for the same reason as `registerCardStyle`: the slot is
+   * first-wins, so a mixed-copy process can hand back an object published before this surface. A
+   * plugin that needs the pipeline checks `typeof api.registerTransform === "function"`; demanding
+   * it in the gate would turn a working bridge into "absent" for every row-only plugin.
+   */
+  readonly registerTransform?: typeof registerTransform;
+  /**
+   * A repaint of what the host draws (T4, S13): one DIFFERENTIAL frame, `requestRender()` with no
+   * argument, after bumping the host's sidebar revision. It does NOT invalidate the component tree and
+   * does NOT force a full redraw: measured on a 600-child transcript with real pi components, that cost
+   * 753 ms and 6.9 MB per switch against 20 ms for the differential frame, because invalidating clears
+   * every Markdown cache. A design change still reaches the cards ALREADY on screen because the design
+   * wrapper re-applies the live selection to the host's rows on every render pass.
+   *
+   * Returns what `/bridge-status` reports as the last repaint, and never throws — with no host
+   * captured yet the request is reported as `unavailable` with its reason.
+   *
+   * Optional for the same reason as `registerCardStyle`: the slot is first-wins, so a mixed-copy
+   * process can hand back an object published before this member existed. A plugin that needs it
+   * checks `typeof api.requestRepaint === "function"`; demanding it in the gate would turn a working
+   * bridge into "absent" for every plugin that does not.
+   */
+  readonly requestRepaint?: typeof requestRepaint;
+  /**
+   * A card DESIGN for one tool name (S4, S5, S7): the bridge owns the single
+   * `pi.registerToolRenderer` resolver and fans it out to every design a plugin registers here. A
+   * design receives the rows the host's own card produced and returns the rows to draw, so the frame
+   * stays the host's.
+   *
+   * Optional for the same reason as `registerCardStyle`: the slot is first-wins, so a mixed-copy
+   * process can hand back an object published before this member existed. A plugin that needs it
+   * checks `typeof api.registerToolDesign === "function"`; demanding it in the gate would turn a
+   * working bridge into "absent" for every plugin that does not register a design.
+   */
+  readonly registerToolDesign?: typeof registerToolDesign;
+  /**
+   * A keymapped action for the host's Keymaps page (S1): the plugin's own action, editable with the
+   * same gestures as a native one (Enter assigns, ⌫ disables, r restores the default) and
+   * participating in the host's reserved-key and duplicate-key checks.
+   *
+   * The bridge publishes the entry; the host reads it while it builds the page. The plugin binds
+   * the key itself — Pi reads extension shortcuts at startup and on `/reload` — and asks
+   * `resolveKeymap` which key to bind, so the answer comes from the host's own precedence.
+   *
+   * Optional for the same reason as `registerCardStyle`: the slot is first-wins, so a mixed-copy
+   * process can hand back an object published before this member existed.
+   */
+  readonly registerKeymap?: typeof registerKeymap;
+  /**
+   * Items for the host's command palette (S1): one entry, or several, into a section the host
+   * already has or a section of its own. An item whose command is not registered is not listed.
+   *
+   * Optional for the same reason as `registerKeymap`.
+   */
+  readonly registerCommands?: typeof registerCommands;
+  /**
+   * The key an id currently uses, as the shell resolves it: environment variable, then saved
+   * binding, then default. Never throws; `unavailable` carries the reason when no shell answers.
+   *
+   * Optional for the same reason as `registerKeymap`.
+   */
+  readonly resolveKeymap?: typeof resolveKeymap;
+  readonly createStore: typeof createStore;
+}
+
+function apiHost(): Record<symbol, unknown> {
+  // SAFETY: `globalThis` accepts symbol keys, and every write to these slots happens in this module
+  // behind the shape checks below.
+  return globalThis as unknown as Record<symbol, unknown>;
+}
+
+interface WarnedState {
+  skew: boolean;
+}
+
+/** One announcement per process, no matter how many copies publish or how often they ask. */
+interface ReadyState {
+  announced: boolean;
+}
+
+/**
+ * The process-global state for a symbol-keyed flag, created on first use. A foreign object at the
+ * key is replaced by a fresh one: this state belongs to this package alone, and it carries nothing
+ * a consumer reads.
+ */
+function flagState<T extends object>(key: symbol, shape: (candidate: Partial<T>) => boolean, created: T): T {
+  const host = apiHost();
+  const existing = host[key];
+  if (typeof existing === "object" && existing !== null) {
+    const candidate = existing as Partial<T>;
+    if (shape(candidate)) return candidate as T;
+  }
+  host[key] = created;
+  return created;
+}
+
+function warnedState(): WarnedState {
+  return flagState<WarnedState>(
+    WARNED_KEY,
+    (candidate) => typeof candidate.skew === "boolean",
+    { skew: false },
+  );
+}
+
+function readyState(): ReadyState {
+  return flagState<ReadyState>(
+    READY_KEY,
+    (candidate) => typeof candidate.announced === "boolean",
+    { announced: false },
+  );
+}
+
+/** One clear notice per process, no matter how many copies ask. */
+function warnSkewOnce(): void {
+  const state = warnedState();
+  if (state.skew) return;
+  state.skew = true;
+  recordNotice(
+    `gentle-shell-bridge: the slot ${String(BRIDGE_API_KEY)} holds something that is not the ` +
+      `"${API_SCHEMA}" API version ${String(API_VERSION)} this process expects (a different major ` +
+      "version, another library's payload, or a partial object). It is treated as ABSENT: " +
+      "bridgeApi() returns undefined and plugins register nothing through this slot. The slot is " +
+      "left exactly as it is — it is never overwritten and never reset. This notice is recorded " +
+      "once per process and appears in the TUI and in /bridge-status.",
+    "warning",
+  );
+}
+
+/**
+ * The shape gate: the schema string, `version === 1`, and the three members a consumer calls.
+ * Anything else — another library's object, a future major version, a partial object — is absent,
+ * never an error.
+ */
+export function isBridgeApi(value: unknown): value is BridgeApi {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    candidate.schema === API_SCHEMA &&
+    candidate.version === API_VERSION &&
+    typeof candidate.registerRows === "function" &&
+    typeof candidate.registerSection === "function" &&
+    typeof candidate.createStore === "function"
+  );
+}
+
+/** The object this copy publishes when it owns the slot (or when the slot is unusable). */
+const LOCAL_API: BridgeApi = Object.freeze({
+  schema: API_SCHEMA,
+  version: API_VERSION,
+  VERSION,
+  registerRows,
+  registerSection,
+  registerCardStyle,
+  registerTransform,
+  requestRepaint,
+  registerToolDesign,
+  registerKeymap,
+  registerCommands,
+  resolveKeymap,
+  createStore,
+});
+
+/** The slot's object when it passes the gate; `undefined` when it is absent or incompatible. */
+function compatibleApi(): BridgeApi | undefined {
+  const existing = apiHost()[BRIDGE_API_KEY];
+  if (existing === undefined) return undefined;
+  if (isBridgeApi(existing)) return existing;
+  warnSkewOnce();
+  return undefined;
+}
+
+/**
+ * The validated published object as the slot holds it RIGHT NOW, or `undefined`.
+ *
+ * This is the whole handshake for a plugin that imports the package and is loaded after it. Call it
+ * from a `session_start` handler: an object means register now. `undefined` means nothing is
+ * published yet — which is "not yet", not necessarily "not installed", because Pi may load your
+ * plugin before this package. Use `onBridgeApi(handler, pi.events)` when both orders have to work;
+ * `bridgeApi()` itself never waits, defers or retries.
+ */
+export function bridgeApi(): BridgeApi | undefined {
+  return compatibleApi();
+}
+
+/**
+ * Publish this copy's API object.
+ *
+ * Runs at module load, so loading the package — through `./extension.ts` or `./index.ts` — makes
+ * the API available before any `session_start`. First wins: a valid object already in the slot is
+ * kept and returned untouched. An incompatible object is kept too (never reset), and this copy's
+ * own object is returned so its own extension can still register through the same bus.
+ */
+export function publishBridgeApi(): BridgeApi {
+  const host = apiHost();
+  const existing = host[BRIDGE_API_KEY];
+  if (existing === undefined) {
+    host[BRIDGE_API_KEY] = LOCAL_API;
+    return LOCAL_API;
+  }
+  if (isBridgeApi(existing)) return existing;
+  warnSkewOnce();
+  return LOCAL_API;
+}
+
+/**
+ * Test-only seam: forget the published object, the once-per-process notice flag and the
+ * announcement flag. Clearing the published object is what lets a test model "the bridge is not
+ * installed"; clearing the announcement flag is what lets one process prove "once" twice. The
+ * extension never calls this. Deliberately not re-exported from `src/index.ts`.
+ */
+export function resetBridgeApiForTests(): void {
+  const host = apiHost();
+  delete host[BRIDGE_API_KEY];
+  delete host[WARNED_KEY];
+  delete host[READY_KEY];
+}
+
+// ---------------------------------------------------------------------------------------------
+// The announcement: how a plugin loaded BEFORE the package learns about it
+// ---------------------------------------------------------------------------------------------
+
+/** The `emit` member of a bus-shaped object, bound to it, or `undefined` when unusable. */
+function busEmitter(events: unknown): ((channel: string, data: unknown) => void) | undefined {
+  if (typeof events !== "object" || events === null) return undefined;
+  const emit = (events as BridgeEventBus).emit;
+  if (typeof emit !== "function") return undefined;
+  return (channel, data) => {
+    emit.call(events, channel, data);
+  };
+}
+
+/** The `on` member of a bus-shaped object, bound to it, or `undefined` when unusable. */
+function busListener(
+  events: unknown,
+): ((channel: string, handler: (data: unknown) => void) => BridgeEventUnsubscribe | void) | undefined {
+  if (typeof events !== "object" || events === null) return undefined;
+  const on = (events as BridgeEventBus).on;
+  if (typeof on !== "function") return undefined;
+  return (channel, handler) => on.call(events, channel, handler);
+}
+
+/**
+ * Announce this process's bridge, on Pi's cross-extension bus, at most once.
+ *
+ * Called from the extension entry — the first moment `pi.events` exists — right after the module
+ * load that published the object. Rules, all of them observable in the tests:
+ *
+ * - **once per process**, across package copies: the flag lives on `globalThis`, like the slot;
+ * - **never for an incompatible slot**: a process whose slot holds another library's payload (or
+ *   another major) has no bridge to announce, and telling plugins to look again would only send
+ *   them to an object that is absent;
+ * - **silent without a bus**: Pi may have no `pi.events` in a bare harness; the symbol still works
+ *   for any plugin that reads it, so nothing is reported and nothing throws.
+ *
+ * Returns whether this call emitted.
+ */
+export function announceBridgeReady(events: unknown): boolean {
+  const emit = busEmitter(events);
+  if (emit === undefined) return false;
+  const state = readyState();
+  if (state.announced) return false;
+  // The announcement says "the slot is usable now": an incompatible slot is never announced.
+  if (compatibleApi() === undefined) return false;
+  state.announced = true;
+  try {
+    emit(BRIDGE_READY_EVENT, READY_PAYLOAD);
+  } catch {
+    // A bus that throws cannot un-announce the process: the flag stays set, so `once` holds even
+    // when the delivery failed. Nothing is written to the terminal.
+  }
+  return true;
+}
+
+/** What a consumer does with the published object. */
+export type BridgeApiHandler = (api: BridgeApi) => void;
+
+/**
+ * Serve a plugin the published API, now or when it is announced.
+ *
+ * This is the helper form of the corrected timing rule:
+ *
+ * - **the object is already published** (this package loaded first): the handler runs immediately, in
+ *   the same turn, and nothing is subscribed — calling it twice cannot leak a listener;
+ * - **it is not published yet** (the plugin loaded first, the real defect): the handler runs when the
+ *   bridge announces itself, at most once per subscription, and the listener detaches itself.
+ *
+ * `events` is `pi.events`. Without a bus the helper cannot hear a later publication: it returns a
+ * no-op disposer and never calls the handler, which is the honest answer for a host with no bus.
+ * A handler that throws is contained: one plugin's failure must not break the announcement for the
+ * next listener.
+ */
+export function onBridgeApi(handler: BridgeApiHandler, events?: unknown): () => void {
+  /** One plugin's throw is its own: the bus must survive to notify the next listener. */
+  const deliver = (api: BridgeApi): void => {
+    try {
+      handler(api);
+    } catch {
+      // Contained on purpose (see the contract: nothing a plugin does may throw into Pi's render).
+    }
+  };
+
+  const existing = bridgeApi();
+  if (existing !== undefined) {
+    deliver(existing);
+    return () => {};
+  }
+
+  const listen = busListener(events);
+  if (listen === undefined) return () => {};
+
+  let active = true;
+  let unsubscribe: BridgeEventUnsubscribe | void;
+
+  const detach = (): void => {
+    const off = unsubscribe;
+    unsubscribe = undefined;
+    if (typeof off !== "function") return;
+    try {
+      off();
+    } catch {
+      // A disposer that throws cannot resurrect the subscription.
+    }
+  };
+
+  const onReady = (): void => {
+    if (!active) return;
+    const api = bridgeApi();
+    if (api === undefined) return; // an announcement not backed by a usable slot
+    active = false;
+    detach();
+    deliver(api);
+  };
+
+  try {
+    unsubscribe = listen(BRIDGE_READY_EVENT, onReady);
+  } catch {
+    return () => {};
+  }
+
+  return () => {
+    active = false;
+    detach();
+  };
+}
+
+// The publishing point: loading this module publishes the API. `./extension.ts` imports it, so the
+// object exists as soon as the package has loaded at all — and, when the package loads after a
+// plugin, `announceBridgeReady` from the same entry is how that plugin hears about it.
+publishBridgeApi();