@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.2

package/packages/shared/src/__tests__/plugin-bridge-register.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  registerPluginBridge,
+  deregisterPluginBridge,
+  listManagedBridges,
+} from "../plugin-bridge-register.js";
+
+let tmpDir: string;
+let homedir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "plugin-bridge-test-"));
+  homedir = tmpDir;
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function settingsPath() {
+  return path.join(homedir, ".pi", "agent", "settings.json");
+}
+
+function readSettings(): Record<string, unknown> {
+  return JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+}
+
+describe("registerPluginBridge", () => {
+  it("writes dashboard-<id> entry under dashboardPluginBridges", () => {
+    const result = registerPluginBridge("demo", "/path/to/demo/bridge.js", { homedir });
+    expect(result.type).toBe("ok");
+    const s = readSettings();
+    const managed = s.dashboardPluginBridges as Record<string, string>;
+    expect(managed["dashboard-demo"]).toBe("/path/to/demo/bridge.js");
+  });
+
+  it("returns ok when entry already matches (idempotent)", () => {
+    registerPluginBridge("demo", "/path/to/bridge.js", { homedir });
+    const result = registerPluginBridge("demo", "/path/to/bridge.js", { homedir });
+    expect(result.type).toBe("ok");
+  });
+
+  it("returns conflict when entry exists with different path", () => {
+    registerPluginBridge("demo", "/old/bridge.js", { homedir });
+    const result = registerPluginBridge("demo", "/new/bridge.js", { homedir });
+    expect(result.type).toBe("conflict");
+    if (result.type === "conflict") {
+      expect(result.existingPath).toBe("/old/bridge.js");
+      expect(result.newPath).toBe("/new/bridge.js");
+    }
+    // Should not overwrite
+    const s = readSettings();
+    const managed = s.dashboardPluginBridges as Record<string, string>;
+    expect(managed["dashboard-demo"]).toBe("/old/bridge.js");
+  });
+
+  it("never touches user-owned packages array", () => {
+    // Pre-populate settings with user packages
+    fs.mkdirSync(path.join(homedir, ".pi", "agent"), { recursive: true });
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ packages: ["/user/extension1", "/user/extension2"] }),
+    );
+
+    registerPluginBridge("demo", "/demo/bridge.js", { homedir });
+    const s = readSettings();
+    const pkgs = s.packages as string[];
+    expect(pkgs).toEqual(["/user/extension1", "/user/extension2"]);
+  });
+});
+
+describe("deregisterPluginBridge", () => {
+  it("removes the managed entry", () => {
+    registerPluginBridge("demo", "/demo/bridge.js", { homedir });
+    deregisterPluginBridge("demo", { homedir });
+    const s = readSettings();
+    const managed = s.dashboardPluginBridges as Record<string, string>;
+    expect(managed["dashboard-demo"]).toBeUndefined();
+  });
+
+  it("is a no-op when entry does not exist", () => {
+    // Should not throw
+    expect(() => deregisterPluginBridge("nonexistent", { homedir })).not.toThrow();
+  });
+
+  it("does not remove other plugin entries", () => {
+    registerPluginBridge("a", "/a/bridge.js", { homedir });
+    registerPluginBridge("b", "/b/bridge.js", { homedir });
+    deregisterPluginBridge("a", { homedir });
+    const managed = listManagedBridges({ homedir });
+    expect(managed["dashboard-a"]).toBeUndefined();
+    expect(managed["dashboard-b"]).toBe("/b/bridge.js");
+  });
+});
+
+describe("listManagedBridges", () => {
+  it("returns all managed entries", () => {
+    registerPluginBridge("a", "/a/bridge.js", { homedir });
+    registerPluginBridge("b", "/b/bridge.js", { homedir });
+    const managed = listManagedBridges({ homedir });
+    expect(Object.keys(managed)).toHaveLength(2);
+    expect(managed["dashboard-a"]).toBe("/a/bridge.js");
+    expect(managed["dashboard-b"]).toBe("/b/bridge.js");
+  });
+
+  it("returns empty object when no plugins registered", () => {
+    const managed = listManagedBridges({ homedir });
+    expect(managed).toEqual({});
+  });
+});

package/packages/shared/src/__tests__/plugin-config-update-protocol.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Type-level test ensuring plugin_config_update is in ServerToBrowserMessage.
+ *
+ * Prevents the recurring esbuild-strips-as-any-cases regression where message
+ * types not in the union get dead-code eliminated in production builds.
+ */
+import { describe, it, expect } from "vitest";
+import type { ServerToBrowserMessage, PluginConfigUpdateMessage } from "../browser-protocol.js";
+
+// Type-level assertion: if PluginConfigUpdateMessage is NOT in the union, this fails to compile.
+type AssertExtends<T, U> = T extends U ? true : never;
+type _PluginConfigUpdateInUnion = AssertExtends<PluginConfigUpdateMessage, ServerToBrowserMessage>;
+
+function extractPluginConfigId(msg: ServerToBrowserMessage): string | null {
+  switch (msg.type) {
+    case "plugin_config_update": return msg.id;
+    default: return null;
+  }
+}
+
+describe("ServerToBrowserMessage includes plugin_config_update", () => {
+  it("plugin_config_update is a valid discriminant", () => {
+    const msg: PluginConfigUpdateMessage = {
+      type: "plugin_config_update",
+      id: "demo",
+      config: { foo: 1 },
+    };
+    expect(extractPluginConfigId(msg)).toBe("demo");
+  });
+
+  it("config payload is only this plugin's namespace", () => {
+    const msg: PluginConfigUpdateMessage = {
+      type: "plugin_config_update",
+      id: "openspec",
+      config: { pollIntervalSeconds: 30 },
+    };
+    // The config is the plugin's namespace only — not the full config
+    expect((msg.config as any).pollIntervalSeconds).toBe(30);
+    expect((msg.config as any).plugins).toBeUndefined();
+  });
+});

package/packages/shared/src/__tests__/recommended-extensions.test.ts

@@ -127,8 +127,12 @@ describe("RecommendedExtension type", () => {
 
 describe("BUNDLED_EXTENSION_IDS manifest", () => {
 	it("contains exactly the v0.x initial bundled set", () => {
+		// pi-flows temporarily removed: upstream repo lacks SPDX license,
+		// blocking the bundle-recommended-extensions.sh license check.
+		// Re-add when https://github.com/BlackBeltTechnology/pi-flows has
+		// a license declared.
 		expect([...BUNDLED_EXTENSION_IDS].sort()).toEqual(
-			["pi-anthropic-messages", "pi-flows"].sort(),
+			["pi-anthropic-messages"].sort(),
 		);
 	});
 

package/packages/shared/src/__tests__/spawn-session-attach-proposal.test.ts

@@ -0,0 +1,47 @@
+/**
+ * Type-level + structural tests for the `attachProposal` field on
+ * `SpawnSessionBrowserMessage`. See change:
+ * add-folder-task-checker-and-spawn-attach.
+ */
+import { describe, it, expect } from "vitest";
+import type {
+  SpawnSessionBrowserMessage,
+  BrowserToServerMessage,
+} from "../browser-protocol.js";
+
+describe("SpawnSessionBrowserMessage.attachProposal", () => {
+  it("is optional — the bare-spawn payload still type-checks", () => {
+    // Compile-time: omitting attachProposal is allowed.
+    const bare: SpawnSessionBrowserMessage = { type: "spawn_session", cwd: "/x" };
+    expect(bare.attachProposal).toBeUndefined();
+    const _inUnion: BrowserToServerMessage = bare;
+    void _inUnion;
+  });
+
+  it("accepts a string attachProposal when set", () => {
+    const withAttach: SpawnSessionBrowserMessage = {
+      type: "spawn_session",
+      cwd: "/x",
+      attachProposal: "add-foo",
+    };
+    expect(withAttach.attachProposal).toBe("add-foo");
+  });
+
+  it("JSON round-trip preserves the field", () => {
+    const sent: SpawnSessionBrowserMessage = {
+      type: "spawn_session",
+      cwd: "/project/foo",
+      attachProposal: "add-auth",
+    };
+    const parsed = JSON.parse(JSON.stringify(sent)) as SpawnSessionBrowserMessage;
+    expect(parsed.type).toBe("spawn_session");
+    expect(parsed.cwd).toBe("/project/foo");
+    expect(parsed.attachProposal).toBe("add-auth");
+  });
+
+  it("JSON round-trip without the field omits it", () => {
+    const sent: SpawnSessionBrowserMessage = { type: "spawn_session", cwd: "/x" };
+    const parsed = JSON.parse(JSON.stringify(sent)) as SpawnSessionBrowserMessage;
+    expect("attachProposal" in parsed).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/tool-registry-strategies-appimage.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Tests for the AppImage self-hit guard inside `whereStrategy`. Per
+ * design D2 (change: fix-electron-appimage-cli-self-detection), the
+ * guard runs after `whichSync(name)` returns and demotes self-hits to
+ * `{ ok: false, reason: "appimage-self-hit: <path>" }` so the
+ * registry's diagnostic trail records the rejection.
+ */
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import os from "node:os";
+
+import { whereStrategy } from "../tool-registry/strategies.js";
+import {
+  ToolRegistry,
+  OverridesStore,
+} from "../tool-registry/index.js";
+
+function tmpStore(): OverridesStore {
+  return new OverridesStore({
+    filePath: path.join(
+      os.tmpdir(),
+      `where-strategy-appimage-test-${process.pid}-${Math.random().toString(36).slice(2)}.json`,
+    ),
+    warn: () => {},
+  });
+}
+
+describe("whereStrategy AppImage self-hit guard", () => {
+  it("rejects an APPDIR-mount candidate", () => {
+    const savedAppDir = process.env.APPDIR;
+    const fakeAppDir = "/tmp/.mount_PI-DAS-TEST";
+    process.env.APPDIR = fakeAppDir;
+    try {
+      const strat = whereStrategy("pi-dashboard", {
+        which: () => fakeAppDir + "/pi-dashboard",
+      });
+      const r = strat.run({
+        overrides: {},
+        platform: "linux",
+      });
+      expect(r.ok).toBe(false);
+      if (!r.ok) {
+        expect(r.reason).toContain("appimage-self-hit");
+        expect(r.reason).toContain(fakeAppDir + "/pi-dashboard");
+      }
+    } finally {
+      if (savedAppDir === undefined) delete process.env.APPDIR;
+      else process.env.APPDIR = savedAppDir;
+    }
+  });
+
+  it("rejects a process.execPath self-hit", () => {
+    // Use the running process.execPath — realpath-equality matches.
+    const exec = process.execPath;
+    const strat = whereStrategy("pi-dashboard", {
+      which: () => exec,
+    });
+    const r = strat.run({
+      overrides: {},
+      platform: process.platform,
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.reason).toContain("appimage-self-hit");
+    }
+  });
+
+  it("returns ok for unrelated paths when no AppImage env vars are set", () => {
+    const savedAppDir = process.env.APPDIR;
+    const savedAppImage = process.env.APPIMAGE;
+    delete process.env.APPDIR;
+    delete process.env.APPIMAGE;
+    try {
+      const candidate = "/usr/local/bin/git";
+      const strat = whereStrategy("git", { which: () => candidate });
+      const r = strat.run({ overrides: {}, platform: "linux" });
+      expect(r.ok).toBe(true);
+      if (r.ok) expect(r.path).toBe(candidate);
+    } finally {
+      if (savedAppDir !== undefined) process.env.APPDIR = savedAppDir;
+      if (savedAppImage !== undefined) process.env.APPIMAGE = savedAppImage;
+    }
+  });
+});
+
+describe("ToolRegistry diagnostic trail records appimage-self-hit", () => {
+  it("Resolution.tried includes a 'where' entry whose reason contains 'appimage-self-hit'", () => {
+    const savedAppDir = process.env.APPDIR;
+    const fakeAppDir = "/tmp/.mount_PI-REG-TEST";
+    process.env.APPDIR = fakeAppDir;
+    try {
+      const registry = new ToolRegistry({
+        overrides: tmpStore(),
+        platform: "linux",
+      });
+      registry.register({
+        name: "synthetic-tool",
+        kind: "binary",
+        strategies: [
+          // Final strategy in the chain is `where`, fed by an injected
+          // `which` that returns an APPDIR-mount candidate.
+          whereStrategy("synthetic-tool", {
+            which: () => fakeAppDir + "/synthetic-tool",
+          }),
+        ],
+      });
+
+      const res = registry.resolve("synthetic-tool");
+      expect(res.ok).toBe(false);
+      const whereEntry = res.tried.find((t) => t.strategy === "where");
+      expect(whereEntry).toBeDefined();
+      expect(String(whereEntry!.result)).toContain("appimage-self-hit");
+    } finally {
+      if (savedAppDir === undefined) delete process.env.APPDIR;
+      else process.env.APPDIR = savedAppDir;
+    }
+  });
+});

package/packages/shared/src/browser-protocol.ts

@@ -11,6 +11,8 @@ import type {
   OpenSpecData,
   ModelInfo,
   PiSessionInfo,
+  ExtensionUiModule,
+  DecoratorDescriptor,
 } from "./types.js";
 import type { TerminalSession } from "./terminal-types.js";
 import type { EditorInstanceStatus } from "./editor-types.js";
@@ -214,13 +216,24 @@ export interface BrowserPromptCancelMessage {
   promptId: string;
 }
 
-/** Progress event streamed during a package install/remove/update operation. */
+/** Progress event streamed during a package install/remove/update/move operation.
+ *
+ * `moveId` is set when this progress event is part of a move operation
+ * (which composes install + remove). Clients group events by `moveId`
+ * to display a single composite progress affordance instead of two
+ * separate operations. Consumers that ignore the field continue to
+ * render install + remove independently — graceful degradation.
+ *
+ * See change: unify-package-management-ui.
+ */
 export interface PackageProgressMessage {
   type: "package_progress";
   operationId: string;
+  /** Optional move grouping id when emitted as part of a move. */
+  moveId?: string;
   event: {
     type: "start" | "progress" | "complete" | "error";
-    action: "install" | "remove" | "update" | "clone" | "pull";
+    action: "install" | "remove" | "update" | "clone" | "pull" | "move";
     source: string;
     message?: string;
   };
@@ -297,16 +310,72 @@ export interface BootstrapTicketCompleteMessage {
 export interface PackageOperationCompleteMessage {
   type: "package_operation_complete";
   operationId: string;
-  action: "install" | "remove" | "update";
+  /** Optional move grouping id; set on every event of a composite move op. */
+  moveId?: string;
+  action: "install" | "remove" | "update" | "move";
   source: string;
   scope: "global" | "local";
   success: boolean;
   error?: string;
   /** Number of sessions reloaded (only on success). */
   sessionsReloaded?: number;
+  /** Set on a move op when install succeeded but remove failed.
+   * Indicates the package now exists in BOTH scopes; UI should surface
+   * a recovery action (POST /api/packages/remove against fromScope). */
+  partialSuccess?: {
+    installed: boolean;
+    removed: boolean;
+    removeError?: string;
+  };
+}
+
+// ── Extension UI System (Phase 1: management-modal slot) ───────────
+// See change: add-extension-ui-modal.
+
+/** Server → browser: cached extension-declared UI modules for a session. */
+export interface BrowserUiModulesListMessage {
+  type: "ui_modules_list";
+  sessionId: string;
+  modules: ExtensionUiModule[];
+}
+
+/** Server → browser: row data for a `view.dataEvent`. */
+export interface BrowserUiDataListMessage {
+  type: "ui_data_list";
+  sessionId: string;
+  event: string;
+  items: unknown[];
+}
+
+// ── Extension UI System (Phase 2: live in-page decorations) ──
+// See change: add-extension-ui-decorations.
+
+/**
+ * Server → browser: a live decorator descriptor (forwarded verbatim from the
+ * extension). `removed: true` instructs the client to unmount the matching
+ * descriptor.
+ */
+export interface BrowserExtUiDecoratorMessage {
+  type: "ext_ui_decorator";
+  sessionId: string;
+  descriptor: DecoratorDescriptor;
+  removed?: boolean;
+}
+
+/** Sent when a plugin's config changes; carries only that plugin's namespace. */
+export interface PluginConfigUpdateMessage {
+  type: "plugin_config_update";
+  /** Plugin id that was updated. */
+  id: string;
+  /**
+   * Only this plugin's namespace config (plugins.<id>.*).
+   * Never contains other plugins' configs.
+   */
+  config: unknown;
 }
 
 export type ServerToBrowserMessage =
+  | PluginConfigUpdateMessage
   | SessionAddedMessage
   | SessionUpdatedMessage
   | SessionRemovedMessage
@@ -344,7 +413,10 @@ export type ServerToBrowserMessage =
   | BrowserPromptCancelMessage
   | ModelsRefreshedMessage
   | BootstrapStatusUpdateMessage
-  | BootstrapTicketCompleteMessage;
+  | BootstrapTicketCompleteMessage
+  | BrowserUiModulesListMessage
+  | BrowserUiDataListMessage
+  | BrowserExtUiDecoratorMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 
@@ -483,6 +555,16 @@ export interface ResumeSessionBrowserMessage {
   mode: "continue" | "fork";
   /** When forking, optionally fork from a specific session entry instead of the latest */
   entryId?: string;
+  /**
+   * Placement intent for the resumed session in the cwd's sessionOrder:
+   *   - "front" (default): move to top of alive tier (Resume button, REST,
+   *     prompt-auto-resume).
+   *   - "keep": leave order alone (drag-to-resume — drop position was already
+   *     persisted by an earlier `reorder_sessions` message).
+   * Server defaults to "front" when omitted, preserving prior behavior.
+   * See change: differentiate-resume-intent-by-trigger.
+   */
+  placement?: "front" | "keep";
 }
 
 export interface HideSessionBrowserMessage {
@@ -498,6 +580,15 @@ export interface UnhideSessionBrowserMessage {
 export interface SpawnSessionBrowserMessage {
   type: "spawn_session";
   cwd: string;
+  /**
+   * Optional kebab-case OpenSpec change name to attach to the spawned session
+   * once it registers. The server queues the intent in `pendingAttachByCwd`
+   * and consumes it on the next matching `session_register`.
+   * Old servers that ignore unknown fields produce a bare spawn (degraded but
+   * recoverable: the user attaches manually). See change:
+   * add-folder-task-checker-and-spawn-attach.
+   */
+  attachProposal?: string;
 }
 
 export interface AttachProposalBrowserMessage {
@@ -629,6 +720,20 @@ export interface RequestRolesBrowserMessage {
   sessionId: string;
 }
 
+/**
+ * Browser → server: the user invoked a Phase-1 module action / requested
+ * row data. Server forwards via `piGateway.sendToSession` to the bridge,
+ * which re-emits as `pi.events.emit(event, { ...params, action, _reply })`.
+ * See change: add-extension-ui-modal.
+ */
+export interface UiManagementBrowserMessage {
+  type: "ui_management";
+  sessionId: string;
+  action: string;
+  event: string;
+  params?: Record<string, unknown>;
+}
+
 export type BrowserToServerMessage =
   | SubscribeMessage
   | UnsubscribeMessage
@@ -669,4 +774,5 @@ export type BrowserToServerMessage =
   | RolePresetSaveBrowserMessage
   | RolePresetDeleteBrowserMessage
   | RequestRolesBrowserMessage
+  | UiManagementBrowserMessage
   | KillProcessBrowserMessage;

package/packages/shared/src/config.ts

@@ -80,6 +80,12 @@ export interface KnownServer {
   addedAt: string; // ISO timestamp
 }
 
+/**
+ * Plugin-specific config namespace.
+ * Lives at ~/.pi/dashboard/config.json#plugins.<id>.*
+ */
+export type PluginsConfig = Record<string, Record<string, unknown>>;
+
 export interface DashboardConfig {
   port: number;
   piPort: number;
@@ -107,6 +113,13 @@ export interface DashboardConfig {
   electronMode: boolean;
   /** Persisted list of known remote servers */
   knownServers: KnownServer[];
+  /**
+   * Per-plugin config namespaces. Reserved top-level key.
+   * Each plugin's config lives at plugins.<id>.*
+   * Plugin-shaped legacy top-level keys (e.g. openspec.*) stay at top-level
+   * until each extract-*-as-plugin change migrates them.
+   */
+  plugins: PluginsConfig;
 }
 
 export interface CorsConfig {
@@ -117,6 +130,7 @@ export interface CorsConfig {
 const VALID_SPAWN_STRATEGIES: SpawnStrategy[] = ["tmux", "headless"];
 
 const DEFAULTS: DashboardConfig = {
+  plugins: {},
   port: 8000,
   piPort: 9999,
   autoStart: true,
@@ -237,6 +251,36 @@ function parseMemoryLimits(raw: any): MemoryLimitsConfig {
   };
 }
 
+function parsePluginsConfig(raw: unknown): PluginsConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result: PluginsConfig = {};
+  for (const [id, val] of Object.entries(raw as Record<string, unknown>)) {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      result[id] = val as Record<string, unknown>;
+    }
+  }
+  return result;
+}
+
+/**
+ * Get the plugins config block from a loaded DashboardConfig.
+ * Provides typed access to plugins.<id>.* namespaces.
+ */
+export function getPluginsConfig(config: DashboardConfig): PluginsConfig {
+  return config.plugins ?? {};
+}
+
+/**
+ * Get a single plugin's config from a loaded DashboardConfig.
+ * Returns {} if the plugin has no stored config.
+ */
+export function getPluginConfig(
+  config: DashboardConfig,
+  pluginId: string,
+): Record<string, unknown> {
+  return config.plugins?.[pluginId] ?? {};
+}
+
 function parseKnownServers(raw: any): KnownServer[] {
   if (!Array.isArray(raw)) return [];
   return raw
@@ -299,6 +343,7 @@ export function loadConfig(): DashboardConfig {
       ...(typeof parsed.lastServer === "string" ? { lastServer: parsed.lastServer } : {}),
       electronMode: parsed.electronMode === true,
       knownServers: parseKnownServers(parsed.knownServers),
+      plugins: parsePluginsConfig(parsed.plugins),
     };
 
     // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts

package/packages/shared/src/dashboard-plugin/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Barrel export for dashboard plugin system shared types.
+ * Import from:
+ *   @blackbelt-technology/pi-dashboard-shared/dashboard-plugin/index.js
+ *   @blackbelt-technology/pi-dashboard-shared/dashboard-plugin/slot-types.js
+ *   etc.
+ */
+export * from "./slot-types.js";
+export * from "./manifest-types.js";
+export * from "./slot-props.js";
+export * from "./plugin-status.js";

package/packages/shared/src/dashboard-plugin/manifest-types.ts

@@ -0,0 +1,58 @@
+import type { SlotId, SettingsTab } from "./slot-types.js";
+
+/**
+ * A single slot claim in a plugin manifest.
+ */
+export interface PluginClaim {
+  /** The slot this claim targets. */
+  slot: SlotId;
+  /** Exported component name from the plugin's client entry (for React slots). */
+  component?: string;
+  /** Route command for "command-route" slot (e.g. "/specs"). */
+  command?: string;
+  /** Trigger id for "anchored-popover" slot. */
+  trigger?: string;
+  /** toolName for "tool-renderer" slot. */
+  toolName?: string;
+  /**
+   * For "settings-section" slot: which SettingsPanel tab to render in.
+   * Defaults to "general" if omitted.
+   */
+  tab?: SettingsTab;
+  /** Slot-specific extra config. */
+  config?: Record<string, unknown>;
+  /** Optional exported predicate function name for filtering contributions. */
+  predicate?: string;
+}
+
+/**
+ * The pi-dashboard-plugin manifest.
+ * Declared as the `pi-dashboard-plugin` field in a package.json,
+ * or as a top-level `dashboard-plugin.json` adjacent to package.json.
+ */
+export interface PluginManifest {
+  /** Globally unique kebab-case plugin id. */
+  id: string;
+  /** Human-readable display name. */
+  displayName: string;
+  /**
+   * Lower number = rendered earlier in multi-contribution slots.
+   * Default 1000. First-party plugins use 100.
+   */
+  priority?: number;
+  /** Relative path to the bundled client entry (from package root). */
+  client?: string;
+  /** Optional relative path to the server entry. */
+  server?: string;
+  /** Optional relative path to a pi-extension/bridge entry. */
+  bridge?: string;
+  /** Optional relative path to a JSON Schema 7 file for plugin config validation. */
+  configSchema?: string;
+  /** Slot claims. */
+  claims: PluginClaim[];
+  /**
+   * When true, the plugin is a test fixture and SHALL be excluded from
+   * production bundles (NODE_ENV=production).
+   */
+  fixture?: boolean;
+}