gentle-shell-bridge 0.3.0 → 0.3.2

package/test/sidebar-e2e.test.ts

@@ -1,331 +0,0 @@
-/**
- * End-to-end over the PUBLIC API (S9, S12, S13).
- *
- * Everything a plugin may touch is imported from `src/index.ts`; the only other non-test import is
- * the Pi entry Pi itself loads (`src/extension.ts`). Internal seams appear here for teardown only,
- * exactly as `test/e2e.test.ts` uses them, and the API-surface test proves they are not public.
- *
- * The host is the fake: a menu host for the `Sections` rows and the fake sidebar for the rail. So
- * these tests prove the wiring, the ordering and the shared state — not the real TUI, which is
- * listed as unverified in PRD.md and README.md.
- */
-
-import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import test from "node:test";
-
-// The public surface, exactly as a plugin reaches it.
-import {
-  VERSION,
-  registerRows,
-  registerSection,
-  type CustomizeRow,
-  type RowProvider,
-  type SidebarSection,
-} from "../src/index.ts";
-// The real Pi entry, armed and commanded exactly as Pi loads it.
-import gentleShellBridge, {
-  STATUS_COMMAND,
-  type BridgeCommandContext,
-  type BridgeCommandHandler,
-  type BridgeExtensionApi,
-  type BridgeSessionHandler,
-} from "../src/extension.ts";
-// Teardown-only seams.
-import { resetBusForTests } from "../src/bus.ts";
-import { disableCaptureBackend, resetCaptureStateForTests } from "../src/capture.ts";
-import { resetHookStateForTests } from "../src/hook.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 { createFakeHost, type FakeHost, type FakeUiTarget } from "./fake-host.ts";
-import {
-  cardBody,
-  cardTitles,
-  fakeState,
-  fakeTui,
-  registerNativeFooter,
-  resetSidebar,
-} from "./fake-sidebar.ts";
-
-const HOOK_KEY = Symbol.for("gentle-pi.customize-row-providers");
-const hookSlot = (): Record<symbol, unknown> => globalThis as unknown as Record<symbol, unknown>;
-
-let configHome: string;
-let previousConfigHome: string | undefined;
-
-test.before(() => {
-  configHome = mkdtempSync(join(tmpdir(), "gsb-sidebar-e2e-"));
-  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 });
-  resetBusForTests();
-  resetSidebar();
-  resetSidebarStateForTests();
-  resetSectionFailuresForTests();
-  resetStoreStateForTests();
-  resetCaptureStateForTests();
-  resetHookStateForTests();
-  resetRowBuildStateForTests();
-  disableCaptureBackend();
-  disableSidebarBackend();
-  delete hookSlot()[HOOK_KEY];
-});
-
-test.afterEach(() => {
-  disableCaptureBackend();
-  disableSidebarBackend();
-  delete hookSlot()[HOOK_KEY];
-});
-
-interface Entry {
-  sessionHandlers: BridgeSessionHandler[];
-  commands: Array<{ name: string; handler: BridgeCommandHandler }>;
-}
-
-const loadEntry = (): Entry => {
-  const sessionHandlers: BridgeSessionHandler[] = [];
-  const commands: Entry["commands"] = [];
-  const pi: BridgeExtensionApi = {
-    // `gentle-pi` is present, so `session_start` arms the row side and the rail (S9/T12).
-    getCommands: () => [{ name: "gentle:customize" }],
-    on(_event, handler) {
-      sessionHandlers.push(handler);
-    },
-    registerCommand(name, command) {
-      commands.push({ name, handler: command.handler });
-    },
-  };
-  gentleShellBridge(pi);
-  return { sessionHandlers, commands };
-};
-
-/** Pi fires `session_start`: the entry arms the row side and installs the sidebar widget. */
-const armThroughEntry = (host: FakeHost): Entry => {
-  const entry = loadEntry();
-  entry.sessionHandlers[0]({}, { hasUI: true, ui: host.ui });
-  return entry;
-};
-
-const printStatus = (entry: Entry): string => {
-  const printed: string[] = [];
-  const ctx: BridgeCommandContext = { ui: { notify: (message: string) => printed.push(message) } };
-  entry.commands.find((command) => command.name === STATUS_COMMAND)?.handler("", ctx);
-  return printed.join("\n");
-};
-
-type UiWithWidget = FakeUiTarget & {
-  setWidget?: (key: string, factory: (tui: unknown, theme: unknown) => unknown) => void;
-};
-
-interface WidgetCall {
-  key: string;
-  component: unknown;
-}
-
-/** Model Pi's `ui.setWidget(key, factory)`: it runs the factory with the real `tui` immediately. */
-const installWidgetSurface = (host: FakeHost): WidgetCall[] => {
-  const calls: WidgetCall[] = [];
-  const ui = host.ui as UiWithWidget;
-  ui.setWidget = (key, factory) => {
-    calls.push({ key, component: factory(fakeTui(), { name: "fake-theme" }) });
-  };
-  return calls;
-};
-
-const musicSection = (overrides: Partial<SidebarSection> = {}): SidebarSection => ({
-  id: "loon.music",
-  title: "MUSIC",
-  meta: () => "1 playing",
-  lines: () => ["track  one", "album  two"],
-  ...overrides,
-});
-
-const sectionLine = (label: string): CustomizeRow[] => [
-  {
-    category: "Cards",
-    label,
-    choice: { setting: "Loon banner source", value: "on", current: () => true },
-    action: () => {},
-  },
-  {
-    category: "Cards",
-    label,
-    choice: { setting: "Loon banner source", value: "off", current: () => false },
-    action: () => {},
-  },
-];
-
-test("one registerSection call reaches the rail and the Sections menu through the entry", () => {
-  const host = createFakeHost();
-  const widgets = installWidgetSurface(host);
-  registerNativeFooter(); // the host's own rail, registered BEFORE our arm
-  registerSection(musicSection());
-
-  const entry = armThroughEntry(host);
-  host.buildMenu();
-
-  assert.equal(widgets.length, 1, "the entry installed exactly one sidebar widget factory");
-  assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"], "the host frames our section after its own");
-  assert.deepEqual(cardBody("MUSIC"), ["track  one", "album  two"]);
-
-  const line = host.toggleLines().find((candidate) => candidate.startsWith("music "));
-  assert.ok(line !== undefined, "the toggle exists without the plugin writing a row");
-  assert.ok(line.includes("● shown") && line.includes("○ hidden"), line);
-  assert.ok(host.rendered().includes("music"), "the row reads as the section label");
-
-  const printed = printStatus(entry);
-  assert.match(printed, /sections: 1/u);
-  assert.match(printed, /sidebar: intercepted \(rail wrapped\)/u);
-});
-
-test("the same holds when the host registers its rail AFTER the arm", () => {
-  const host = createFakeHost();
-  installWidgetSurface(host);
-  // The host's rail STATE exists from startup; what arrives late is the footer PART. That is the
-  // ordering S4 is about, and the reason the interception patches the map instead of the part.
-  fakeState();
-  registerSection(musicSection());
-
-  armThroughEntry(host);
-  registerNativeFooter(); // the host's own rail, registered after our interception
-
-  assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"]);
-});
-
-test("the widget the bridge installs renders no rows", () => {
-  const host = createFakeHost();
-  const widgets = installWidgetSurface(host);
-  registerNativeFooter();
-
-  armThroughEntry(host);
-
-  const component = widgets[0]?.component as { render(width: number): string[] } | undefined;
-  assert.ok(component !== undefined);
-  assert.deepEqual(component.render(40), [], "the widget exists only to receive the tui");
-});
-
-test("toggling through the menu hides the section on the next frame and stops building it", async () => {
-  const host = createFakeHost();
-  installWidgetSurface(host);
-  registerNativeFooter();
-  let linesCalls = 0;
-  registerSection(
-    musicSection({
-      lines: () => {
-        linesCalls += 1;
-        return ["track  one", "album  two"];
-      },
-    }),
-  );
-
-  armThroughEntry(host);
-  host.buildMenu();
-  assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"]);
-
-  await host.pressRow(
-    (row) => row.choice?.setting === "music" && row.choice.value === "hidden",
-  );
-  linesCalls = 0;
-
-  assert.deepEqual(cardTitles(), ["FOOTER"], "the next frame drops the card");
-  assert.equal(linesCalls, 0, "and the hidden section's content is not built");
-  assert.deepEqual(
-    JSON.parse(readFileSync(join(configHome, "gentle-shell-bridge", "bridge-sections.json"), "utf8")),
-    { schemaVersion: 1, values: { sections: { "loon.music": false } } },
-  );
-});
-
-test("disposing the section removes the card and, on a fresh menu, its rows", () => {
-  const host = createFakeHost();
-  installWidgetSurface(host);
-  registerNativeFooter();
-  const dispose = registerSection(musicSection());
-
-  armThroughEntry(host);
-  host.buildMenu();
-  assert.deepEqual(cardTitles(), ["FOOTER", "MUSIC"]);
-  assert.ok(host.toggleLines().some((line) => line.startsWith("music ")));
-
-  dispose();
-
-  assert.deepEqual(cardTitles(), ["FOOTER"], "the rail drops it immediately");
-
-  // A menu that received rows once keeps them (the capture marks the array), so a fresh menu is the
-  // honest way to observe the next build.
-  const second = createFakeHost();
-  installWidgetSurface(second);
-  armThroughEntry(second);
-  second.buildMenu();
-  assert.deepEqual(second.toggleLines(), [], "no toggle left for a disposed section");
-  assert.equal(
-    second.rendered().some((label) => label.includes("MUSIC")),
-    false,
-    "and no row label either",
-  );
-});
-
-test("the row side still behaves in the same process, alongside the sections", () => {
-  const host = createFakeHost();
-  installWidgetSurface(host);
-  registerNativeFooter();
-  const provider: RowProvider = {
-    id: "loon.banner-source",
-    category: "Cards",
-    rows: () => sectionLine("Loon banner source"),
-  };
-  registerRows(provider);
-  registerSection(musicSection());
-
-  armThroughEntry(host);
-  host.buildMenu();
-
-  const injected = host.liveRows().slice(4);
-  assert.deepEqual(
-    injected.slice(0, 2).map((row) => row.category),
-    ["Cards", "Cards"],
-    "provider rows keep their place and order",
-  );
-  assert.deepEqual(
-    injected.slice(2).map((row) => row.category),
-    ["Sections", "Sections"],
-    "the bridge's own rows follow",
-  );
-  const lines = host.toggleLines();
-  assert.ok(lines.some((line) => line.startsWith("Loon banner source")));
-  assert.ok(lines.some((line) => line.startsWith("music ")));
-});
-
-test("a UI without setWidget is reported as unarmed and never throws", () => {
-  const host = createFakeHost(); // no setWidget on this UI: Pi always has one, the test does not
-  registerSection(musicSection());
-
-  const entry = armThroughEntry(host); // must not throw
-  host.buildMenu();
-
-  assert.deepEqual(cardTitles(), [], "no rail interception was possible");
-  assert.ok(host.rendered().includes("music"), "the row side still works: the toggle is visible");
-
-  const printed = printStatus(entry);
-  assert.match(printed, /sidebar: not armed/u);
-  assert.match(printed, /sections: 1/u);
-});
-
-test("the public version is the released one", () => {
-  assert.equal(VERSION, "0.3.0");
-});

package/test/sidebar-hover.test.ts

@@ -1,276 +0,0 @@
-/**
- * S21/T40–T41: hover reaches the bridge's own rail rows.
- *
- * The fake now models the host's part-level mouse dispatch as it really is. The `footer` part is a
- * `NativePointerRegion` (`extensions/gentle-shell.ts:2766`) whose `onHover` answers EVERY `move`
- * inside the part's frame (`lib/native-pointer-region.ts:80-88`,
- * `extensions/gentle-shell.ts:2732-2741`): it claims the host's shared pointer slot
- * (`SidebarState.hover`, `lib/shell-sidebar.ts:31,72-78`) for a row it owns and clears it otherwise,
- * returning `{ handled: true }` either way. A move over a row the bridge appended is therefore
- * consumed by the host's region and never reaches the bridge's wrapper, which is why these tests
- * failed before the fix: the wrapper consulted the host first and only asked the contributor when
- * the host declined, and the host never declines a move.
- *
- * Every dispatch below is the event the layout really hands a part — `y` in the PART's frame, `width`
- * the frame it rendered (`lib/shell-sidebar-layout.ts:245-259`) — so the offset arithmetic is the
- * bridge's real code, not a test-only shortcut.
- */
-
-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 { registerSection, resetBusForTests, resetSectionsForTests } from "../src/bus.ts";
-import { setRepaintHost, resetRepaintForTests } from "../src/repaint.ts";
-import { resetSectionPanelForTests, setSectionTheme } from "../src/section-panel.ts";
-import { getSectionHoverReport, resetSectionPointerForTests } from "../src/section-pointer.ts";
-import {
-  SIDEBAR_RAIL_KEY,
-  disableSidebarBackend,
-  installSidebarBackend,
-  resetSidebarStateForTests,
-} from "../src/sidebar.ts";
-import {
-  installSectionRail,
-  resetSectionFailuresForTests,
-} from "../src/sidebar-render.ts";
-import { resetStoreStateForTests } from "../src/store.ts";
-import type { SidebarSection } from "../src/types.ts";
-import {
-  cacheRevision,
-  fakeState,
-  fakeTerminal,
-  fakeTui,
-  registerNativeFooter,
-  renderSidebar,
-  resetSidebar,
-  setHostHover,
-} from "./fake-sidebar.ts";
-
-let configHome: string;
-let previousConfigHome: string | undefined;
-
-test.before(() => {
-  configHome = mkdtempSync(join(tmpdir(), "gsb-sidebar-hover-"));
-  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 });
-  resetBusForTests();
-  resetSectionsForTests();
-  resetSidebar();
-  resetSidebarStateForTests();
-  resetSectionFailuresForTests();
-  resetSectionPanelForTests();
-  resetSectionPointerForTests();
-  resetRepaintForTests();
-  resetStoreStateForTests();
-  disableSidebarBackend();
-  renders = 0;
-});
-
-const section = (id: string, extra: Partial<SidebarSection> = {}): SidebarSection => ({
-  id,
-  title: id.toUpperCase(),
-  lines: () => [`body ${id}`],
-  ...extra,
-});
-
-let renders = 0;
-
-/** Arm the rail with a `tui` whose `requestRender` and cache revision a test can count. */
-function arm(): void {
-  const tui = {
-    terminal: fakeTerminal(),
-    requestRender: () => {
-      renders += 1;
-    },
-  };
-  setRepaintHost(tui);
-  registerNativeFooter();
-  installSidebarBackend(() => fakeTui());
-  installSectionRail();
-}
-
-const rail = () => fakeState().parts.get(SIDEBAR_RAIL_KEY);
-const rowOf = (text: string, width = 40): string | undefined =>
-  (rail()?.render(width) ?? []).find((row) => row.includes(text));
-
-/** The native footer renders three rows, so the contribution's first row is 3. */
-const NATIVE_ROWS = 3;
-
-/** The section HEADER row, and the first inner row of a body, in the part's own frame. */
-const HEADER_ROW = NATIVE_ROWS;
-const FIRST_BODY_ROW = NATIVE_ROWS + 1;
-
-const move = (y: number): unknown =>
-  rail()?.handleMouse?.({ type: "move", button: "none", x: 4, y, width: 40, height: 40 });
-const click = (y: number): unknown =>
-  rail()?.handleMouse?.({ type: "click", button: "left", x: 4, y, width: 40, height: 40 });
-
-/** The host's hover role (`HOVER_ROLE = "warning"`, `lib/shell-hover.ts:33`), as SGR 33. */
-const HOVER_SGR = "\u001b[33m";
-
-const ROLE_SGR: Record<string, number> = {
-  text: 37,
-  muted: 90,
-  dim: 2,
-  accent: 95,
-  success: 32,
-  error: 31,
-  warning: 33,
-};
-
-function fakeTheme(): { fg(role: string, text: string): string; bold(text: string): string } {
-  return {
-    fg: (role, text) => `\u001b[${String(ROLE_SGR[role] ?? 0)}m${text}\u001b[39m`,
-    bold: (text) => `\u001b[1m${text}\u001b[22m`,
-  };
-}
-
-test("a move over the section HEADER paints it with the host's hover role", () => {
-  setSectionTheme(fakeTheme());
-  registerSection(section("music", { title: "MUSIC" }));
-  arm();
-  renderSidebar();
-
-  assert.ok(!(rowOf("MUSIC") ?? "").includes(HOVER_SGR), "the header starts idle");
-  const digestBefore = rail()?.digest?.();
-  const revisionBefore = cacheRevision();
-
-  assert.deepEqual(move(HEADER_ROW), { handled: true, render: true }, "the header answers the move");
-  assert.equal(renders, 1, "exactly one differential frame is asked for");
-  assert.equal(cacheRevision(), revisionBefore + 1, "and the host's sidebar revision moved");
-  assert.ok((rowOf("MUSIC") ?? "").includes(HOVER_SGR), "the header takes the host's hover role");
-
-  const hover = fakeState().hover;
-  assert.ok(hover !== undefined, "the shared pointer slot carries our claim");
-  assert.equal(getSectionHoverReport().mechanism, "host-state");
-  assert.notEqual(rail()?.digest?.(), digestBefore, "the hover moves the digest, so no stale frame");
-});
-
-test("a move over an inner CLICKABLE row paints it, and never runs its action", () => {
-  setSectionTheme(fakeTheme());
-  const calls: string[] = [];
-  registerSection(
-    section("music", {
-      title: "MUSIC",
-      lines: () => [
-        { label: "play", meta: "enter", onClick: () => calls.push("play") },
-        { label: "inert" },
-      ],
-    }),
-  );
-  arm();
-  renderSidebar();
-
-  assert.ok(!(rowOf("play") ?? "").includes(HOVER_SGR), "the row starts idle");
-
-  assert.deepEqual(move(FIRST_BODY_ROW), { handled: true, render: true }, "the row answers the move");
-  assert.equal(renders, 1, "one frame");
-  assert.ok((rowOf("play") ?? "").includes(HOVER_SGR), "the row takes the host's hover role");
-  assert.equal(fakeState().hover !== undefined, true, "the shared pointer slot carries our claim");
-  assert.deepEqual(calls, [], "hovering never runs a row's work");
-
-  assert.deepEqual(move(FIRST_BODY_ROW), { handled: true }, "the same row again is not a new hover");
-  assert.equal(renders, 1, "so it asks for no frame");
-
-  assert.deepEqual(move(FIRST_BODY_ROW + 1), { handled: true, render: true }, "an inert row clears it");
-  assert.equal(renders, 2);
-  assert.ok(!(rowOf("play") ?? "").includes(HOVER_SGR), "the row is painted idle again");
-});
-
-test("the host's own row keeps the pointer: the bridge never steals it", () => {
-  setSectionTheme(fakeTheme());
-  registerSection(
-    section("music", {
-      title: "MUSIC",
-      lines: () => [{ label: "play", onClick: () => {} }],
-    }),
-  );
-  arm();
-  renderSidebar();
-
-  // Row 1 is the native footer's own body row: the host's region claims it, and a fix that asked the
-  // contributor first for EVERY row would take the pointer from the card the user says works today.
-  assert.deepEqual(
-    move(1),
-    { handled: true, render: true },
-    "the host's region answered, exactly as it does for its own cards",
-  );
-  assert.equal(renders, 0, "no bridge frame is asked for");
-  assert.equal(getSectionHoverReport().mechanism, "not used", "the bridge never claimed the pointer");
-  assert.ok(fakeState().hover !== undefined, "the host's own claim holds the slot");
-  assert.ok(!(rowOf("MUSIC") ?? "").includes(HOVER_SGR), "and none of our rows is painted");
-  assert.ok(!(rowOf("play") ?? "").includes(HOVER_SGR));
-});
-
-test("moving from our row to the host's row hands the pointer back, one surface at a time", () => {
-  setSectionTheme(fakeTheme());
-  registerSection(
-    section("music", {
-      title: "MUSIC",
-      lines: () => [{ label: "play", onClick: () => {} }],
-    }),
-  );
-  arm();
-  renderSidebar();
-
-  move(FIRST_BODY_ROW);
-  assert.ok((rowOf("play") ?? "").includes(HOVER_SGR), "our row is painted while it owns the pointer");
-  const claimed = fakeState().hover?.owner;
-
-  move(0);
-  assert.notEqual(fakeState().hover?.owner, claimed, "the host's own target took the pointer");
-  assert.ok(!(rowOf("play") ?? "").includes(HOVER_SGR), "and our row is released, not left painted");
-});
-
-test("the host's own pointer-left step clears our row and repaints once", () => {
-  setSectionTheme(fakeTheme());
-  registerSection(section("music", { title: "MUSIC" }));
-  arm();
-  renderSidebar();
-  move(HEADER_ROW);
-  assert.equal(renders, 1);
-
-  // `setSidebarHover(tui)` with no owner: what the layout does when the pointer leaves the rail
-  // (`lib/shell-sidebar-layout.ts:280,447`). It runs the current owner's `clear()`.
-  setHostHover();
-
-  assert.equal(renders, 2, "the clear repaints once");
-  assert.equal(fakeState().hover, undefined, "the slot is empty");
-  assert.ok(!(rowOf("MUSIC") ?? "").includes(HOVER_SGR), "the header is idle again");
-});
-
-test("a click on an inner action row still runs once, and only on that row", () => {
-  const calls: string[] = [];
-  registerSection(
-    section("music", {
-      title: "MUSIC",
-      lines: () => [
-        { label: "play", onClick: () => calls.push("play") },
-        { label: "inert" },
-      ],
-    }),
-  );
-  arm();
-  renderSidebar();
-
-  assert.deepEqual(click(FIRST_BODY_ROW), { handled: true, render: true });
-  assert.deepEqual(click(FIRST_BODY_ROW), { handled: true, render: true });
-  assert.deepEqual(calls, ["play", "play"], "one click, one call — never doubled by the host");
-
-  assert.equal(click(FIRST_BODY_ROW + 1), undefined, "an inert row declines");
-  assert.equal(click(HEADER_ROW + 9), undefined, "a row past the contribution is not ours");
-  assert.deepEqual(calls, ["play", "play"]);
-});