bb plugin screenshot: plan and capture marketplace listing screenshots from the running app

apps/app/src/lib/plugin-slots.ts

@@ -399,6 +399,17 @@ export function getPluginSlotSnapshot(): PluginSlotSnapshot {
   return snapshot;
 }
 
+// The listing-screenshot capture harness (`bb plugin screenshot --capture`)
+// drives a headless window at this app and needs to know which surfaces a
+// plugin actually registered — the one fact only the running renderer has.
+// Components carry functions, so the harness reads ids/paths, never this
+// object wholesale.
+if (typeof window !== "undefined") {
+  (
+    window as { __bbPluginSlotSnapshot?: () => PluginSlotSnapshot }
+  ).__bbPluginSlotSnapshot = getPluginSlotSnapshot;
+}
+
 /** All plugin slot registrations, re-rendering on store changes. */
 export function usePluginSlots(): PluginSlotSnapshot {
   return useSyncExternalStore(subscribePluginSlots, getPluginSlotSnapshot);

apps/cli/src/__tests__/plugin-screenshot.test.ts

@@ -0,0 +1,148 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { planPluginScreenshots } from "../plugin-screenshot.js";
+
+/** The plugins bb ships, which are the closest thing to real submissions. */
+const PLUGINS_DIR = new URL("../../../../plugins", import.meta.url).pathname;
+const plan = (name: string, pluginId: string, fixtureThreadId?: string) =>
+  planPluginScreenshots({
+    rootDir: join(PLUGINS_DIR, name),
+    pluginId,
+    ...(fixtureThreadId === undefined ? {} : { fixtureThreadId }),
+  });
+
+describe("planPluginScreenshots", () => {
+  it("leads a panel plugin's listing with its own panel", async () => {
+    const result = await plan("tasks", "tasks");
+    expect(result.steps[0]).toMatchObject({
+      slot: "navPanel",
+      url: "/plugins/tasks/tasks",
+      outputFile: "01-panel.png",
+    });
+  });
+
+  it("plans nothing for a plugin that paints nothing, and does not fail", async () => {
+    // provider-retry continues turns after a limit resets. A listing for it
+    // should never be held up waiting for a screenshot that cannot exist.
+    const result = await plan("provider-retry", "provider-retry");
+    expect(result.steps.filter((step) => step.kind === "route")).toEqual([]);
+  });
+
+  it("reports fixture-only surfaces instead of photographing an empty app", async () => {
+    const withoutFixture = await plan("inline-vis", "inline-vis");
+    expect(withoutFixture.steps).toEqual([]);
+    expect(withoutFixture.needsFixture).toContain("messageDirective");
+
+    const withFixture = await plan("inline-vis", "inline-vis", "thr_fixture");
+    expect(withFixture.needsFixture).toEqual([]);
+    expect(withFixture.steps).toEqual([
+      {
+        slot: "messageDirective",
+        kind: "fixture",
+        url: "/threads/thr_fixture",
+        outputFile: "06-message.png",
+        requires: "a thread whose last message carries the plugin's directive",
+      },
+    ]);
+  });
+
+  it("uses the plugin's real id in the panel URL, not its directory name", async () => {
+    // The docs plugin installs as `simple-notes`; a URL built from the folder
+    // would 404 for every listing screenshot it takes.
+    const result = await plan("docs", "simple-notes");
+    expect(result.steps[0]?.url).toBe("/plugins/simple-notes/docs");
+  });
+
+  it("ignores a plugin's vendored SDK declarations", async () => {
+    // Every plugin vendors types/ that mention every slot in the SDK. Reading
+    // those would plan a screenshot of every surface for every plugin.
+    const result = await plan("provider-codex", "provider-codex");
+    expect(result.slots).not.toContain("navPanel");
+    expect(result.slots).not.toContain("homepageSection");
+  });
+});
+
+describe("the capture harness planner", async () => {
+  const { createRequire } = await import("node:module");
+  const requireCjs = createRequire(import.meta.url);
+  const harness = requireCjs(
+    "../../../desktop/scripts/plugin-capture.cjs",
+  ) as {
+    planSteps: (
+      plan: {
+        pluginId: string;
+        surfaces: ReadonlyArray<{
+          slot: string;
+          kind: string;
+          route: string;
+          stem: string;
+        }>;
+        fixtureThreadId?: string;
+      },
+      slotIndex: Record<
+        string,
+        Array<{ pluginId: string; path?: string | null }>
+      >,
+    ) => Array<{ slot: string; url: string; outputFile: string }>;
+    SNAPSHOT_KEYS: Record<string, string>;
+  };
+
+  it("maps every capturable surface to a live snapshot key", async () => {
+    const { PLUGIN_CAPTURE_SURFACES } = await import("@bb/domain");
+    for (const surface of PLUGIN_CAPTURE_SURFACES) {
+      expect(harness.SNAPSHOT_KEYS[surface.slot], surface.slot).toBeTruthy();
+    }
+  });
+
+  it("shoots only the target plugin's registrations", () => {
+    const steps = harness.planSteps(
+      {
+        pluginId: "tasks",
+        surfaces: [
+          {
+            slot: "navPanel",
+            kind: "route",
+            route: "/plugins/:pluginId/:panelPath",
+            stem: "01-panel",
+          },
+        ],
+      },
+      {
+        navPanels: [
+          { pluginId: "tasks", path: "/board" },
+          { pluginId: "someone-else", path: "other" },
+        ],
+      },
+    );
+    expect(steps).toEqual([
+      { slot: "navPanel", url: "/plugins/tasks/board", outputFile: "01-panel.png" },
+    ]);
+  });
+
+  it("skips fixture surfaces without a fixture thread, like the CLI planner", () => {
+    const surfaces = [
+      {
+        slot: "messageDirective",
+        kind: "fixture",
+        route: "/threads/:threadId",
+        stem: "06-message",
+      },
+    ];
+    const slotIndex = { messageDirectives: [{ pluginId: "tasks" }] };
+    expect(
+      harness.planSteps({ pluginId: "tasks", surfaces }, slotIndex),
+    ).toEqual([]);
+    expect(
+      harness.planSteps(
+        { pluginId: "tasks", surfaces, fixtureThreadId: "thr_1" },
+        slotIndex,
+      ),
+    ).toEqual([
+      {
+        slot: "messageDirective",
+        url: "/threads/thr_1",
+        outputFile: "06-message.png",
+      },
+    ]);
+  });
+});

apps/cli/src/commands/plugin.ts

@@ -27,6 +27,11 @@ import {
   syncPluginTypes,
   type PluginPackageLayoutMigration,
 } from "@bb/templates/plugin-scaffold";
+import {
+  planPluginScreenshots,
+  resolveElectronBinary,
+  runPluginCapture,
+} from "../plugin-screenshot.js";
 import { action } from "../action.js";
 import { cliFetch, createCliBbSdk } from "../client.js";
 import {
@@ -1543,6 +1548,105 @@ export function registerPluginCommands(
       }),
     );
 
+  plugin
+    .command("screenshot [path]")
+    .description(
+      "Plan the listing screenshots for a plugin: reads the surfaces its frontend registers and reports one shot per surface. Surfaces that only exist inside a thread, composer, or open file need the shared capture fixture",
+    )
+    .option("--json", "Output JSON")
+    .option(
+      "--fixture-thread <id>",
+      "Thread the shared capture fixture seeded, enabling the surfaces that need one",
+    )
+    .option(
+      "--app-url <url>",
+      "Where the app shell is served when it differs from the server (a source dev instance serves the app from Vite's port); defaults to the server URL",
+    )
+    .option(
+      "--capture <outDir>",
+      "Take the screenshots: drives a headless window at this bb, reads which surfaces the plugin registered from the running app, and writes one PNG per surface into <outDir>",
+    )
+    .action(
+      action(
+        async (
+          path: string | undefined,
+          opts: JsonOutputOptions & {
+            fixtureThread?: string;
+            capture?: string;
+            appUrl?: string;
+          },
+        ) => {
+          const rootDir = resolve(process.cwd(), path ?? ".");
+          const raw: unknown = JSON.parse(
+            await readFile(join(rootDir, "package.json"), "utf8"),
+          );
+          const packageName = pluginPackageSummarySchema.parse(raw).name;
+          if (packageName === undefined) {
+            throw new Error(`No plugin package name in ${rootDir}/package.json`);
+          }
+          const plan = await planPluginScreenshots({
+            rootDir,
+            pluginId: derivePluginId(packageName),
+            ...(opts.fixtureThread === undefined
+              ? {}
+              : { fixtureThreadId: opts.fixtureThread }),
+          });
+          if (opts.json) {
+            outputJson(opts, plan);
+            return;
+          }
+          if (plan.slots.length === 0) {
+            // Not a failure: a plugin that only adds agent tools or a provider
+            // paints nothing, and its listing should not wait on a screenshot
+            // that cannot exist.
+            console.log(
+              `${plan.pluginId} registers no visual surface — no listing screenshots to take.`,
+            );
+            return;
+          }
+          for (const step of plan.steps) {
+            console.log(`${step.outputFile}  ${step.url}  (${step.slot})`);
+          }
+          for (const slot of plan.needsFixture) {
+            console.log(
+              `skipped ${slot} — needs the capture fixture; pass --fixture-thread <id>`,
+            );
+          }
+          if (opts.capture !== undefined) {
+            const harnessPath = resolve(
+              import.meta.dirname,
+              "../../desktop/scripts/plugin-capture.cjs",
+            );
+            const electronBinary = resolveElectronBinary(
+              process.env,
+              harnessPath,
+            );
+            if (electronBinary === null) {
+              throw new Error(
+                "No Electron found for the capture harness. Run from a bb checkout, or set BB_ELECTRON to an Electron binary.",
+              );
+            }
+            const report = await runPluginCapture({
+              appUrl: opts.appUrl ?? getUrl(),
+              pluginId: plan.pluginId,
+              outDir: resolve(process.cwd(), opts.capture),
+              harnessPath,
+              electronBinary,
+              ...(opts.fixtureThread === undefined
+                ? {}
+                : { fixtureThreadId: opts.fixtureThread }),
+            });
+            if (report.written.length === 0) {
+              console.log("Capture ran; the app reports no surfaces to shoot.");
+            }
+            for (const shot of report.written) {
+              console.log(`wrote ${shot.file}  (${shot.slot})`);
+            }
+          }
+        },
+      ),
+    );
+
   plugin
     .command("dev [path]")
     .description(