feat(plugin): let composer pills render their own popover content (#59764)

Co-authored-by: neriousy <34747899+neriousy@users.noreply.github.com>

Author: opencode-agent[bot]

packages/app/component-tests/plugin-host.spec.ts

@@ -1452,9 +1452,6 @@ story("composer pills show per session, open their rows, and fail only their own
                     },
                     { id: "13", label: "#13 Draft", icon: "branch" },
                   ],
-                  actions: [
-                    { id: "refresh", label: "Refresh", run: () => void (document.body.dataset.refreshed = "") },
-                  ],
                 }),
               }),
           }),
@@ -1511,14 +1508,54 @@ story("composer pills show per session, open their rows, and fail only their own
   // A row without `run` only shows.
   await expect(rows.nth(1)).toHaveAttribute("data-disabled", "")
 
-  // Actions sit in one row under the rows.
-  const actions = menu.locator('[data-slot="session-plugin-pill-actions"] [data-slot="session-plugin-pill-action"]')
-  await expect(actions).toHaveText(["Refresh"])
-
   await rows.nth(0).click()
   await expect(page.locator("body")).toHaveAttribute("data-picked", "12")
+})
 
-  await pills.click()
-  await actions.first().click()
-  await expect(page.locator("body")).toHaveAttribute("data-refreshed", "")
+story("a composer pill with a menu opens the plugin's content under the host's heading", async ({ page }) => {
+  await page.evaluate(async (fixture) => {
+    const { mountComposerPills, until, ComposerPill } = await import(fixture)
+
+    const host = mountComposerPills({
+      definitions: [
+        {
+          id: "acme",
+          windowEntry: async () => ({
+            default: (ctx: Context) =>
+              void ctx.add(ComposerPill, {
+                id: "goal",
+                // `menu` wins over the view's rows.
+                show: () => ({ label: "Goal", title: "Ship the release", rows: [{ id: "unused", label: "Unused" }] }),
+                menu: (input: { readonly session: { readonly directory: string }; close(): void }) => {
+                  const button = document.createElement("button")
+                  button.dataset.testid = "goal-pause"
+                  button.textContent = `Pause ${input.session.directory}`
+                  button.onclick = () => input.close()
+
+                  return button
+                },
+              }),
+          }),
+        },
+      ],
+    })
+
+    await until(() => host.status("acme") === "active")
+  }, fixture)
+
+  const pill = page.getByTestId("composer-pills").locator('[data-slot="session-plugin-pill"]')
+  await expect(pill).toHaveText("Goal")
+
+  await pill.click()
+  const popover = page.locator('[data-slot="session-plugin-pill-popover"]')
+  await expect(popover.getByText("Ship the release")).toBeVisible()
+  await expect(popover.locator('[data-slot="session-plugin-pill-row"]')).toHaveCount(0)
+  await expect(popover.getByTestId("goal-pause")).toHaveText("Pause /repo")
+
+  await popover.getByTestId("goal-pause").click()
+  await expect(popover).toHaveCount(0)
+
+  // The content renders again on the next open.
+  await pill.click()
+  await expect(page.getByTestId("goal-pause")).toBeVisible()
 })

packages/app/src/session/composer/plugin-pills.tsx

@@ -1,6 +1,8 @@
 import { Icon } from "@opencode/ui/icon"
 import { Menu } from "@opencode/ui/menu"
-import { createMemo, For, Show, type Accessor, type JSX } from "solid-js"
+import { Popover } from "@kobalte/core/popover"
+import { createMemo, For, Match, Show, Switch, untrack, type Accessor, type JSX } from "solid-js"
+import { createStore } from "solid-js/store"
 import {
   ComposerPill,
   type ComposerPillProps,
@@ -72,12 +74,12 @@ function PluginPill(props: { pill: ComposerPill; input: ComposerPillProps; align
   const alignment = props.alignment
   const view = createMemo(() => props.pill.show(props.input))
   const placement = () => (({ center: "top", start: "top-start", end: "top-end" }) as const)[alignment()]
+  const [state, setState] = createStore({ open: false })
 
   return (
     <Show when={view()}>
       {(current) => (
-        <Show
-          when={current().rows || current().actions}
+        <Switch
           fallback={
             <button
               type="button"
@@ -90,58 +92,93 @@ function PluginPill(props: { pill: ComposerPill; input: ComposerPillProps; align
             </button>
           }
         >
-          <Menu gutter={8} placement={placement()}>
-            <Menu.Trigger
-              as="button"
-              type="button"
-              data-slot="session-plugin-pill"
-              aria-label={current().title}
-              class={capsule}
-            >
-              <Content view={current()} />
-            </Menu.Trigger>
-            <Menu.Portal>
-              <Menu.Content data-slot="session-plugin-pill-menu" aria-label={current().title ?? current().label}>
-                <Menu.Group>
-                  <Menu.GroupLabel class="!h-auto max-w-80 !py-1.5">
-                    <span dir="auto" class="line-clamp-3 break-words">
-                      {current().title ?? current().label}
-                    </span>
-                  </Menu.GroupLabel>
-                  <For each={current().rows}>
-                    {(row) => (
-                      <Menu.Item
-                        data-slot="session-plugin-pill-row"
-                        disabled={!row.run}
-                        onSelect={() => row.run?.()}
-                        badge={row.detail}
-                      >
-                        <PillIcon name={row.icon} tone={row.tone} />
-                        <span dir="auto" class="min-w-0 flex-1 truncate">
-                          {row.label}
-                        </span>
-                      </Menu.Item>
+          <Match when={props.pill.menu}>
+            {(menu) => (
+              <Popover
+                open={state.open}
+                onOpenChange={(open) => setState("open", open)}
+                placement={placement()}
+                gutter={8}
+              >
+                <Popover.Trigger
+                  as="button"
+                  type="button"
+                  data-slot="session-plugin-pill"
+                  aria-label={current().title}
+                  class={capsule}
+                >
+                  <Content view={current()} />
+                </Popover.Trigger>
+                <Popover.Portal>
+                  <Popover.Content
+                    data-slot="session-plugin-pill-popover"
+                    aria-label={current().title ?? current().label}
+                    class="w-80 max-w-[calc(100vw-56px)] rounded-[10px] border-[0.5px] border-v2-border-border-muted bg-v2-background-bg-layer-01 p-1 shadow-[var(--v2-elevation-floating)] outline-none"
+                  >
+                    <div class="px-2 pt-1 pb-1.5 text-[11px] font-[530] tracking-[0.05px] leading-[var(--line-height-tight)] text-v2-text-text-faint">
+                      <span dir="auto" class="line-clamp-3 break-words">
+                        {current().title ?? current().label}
+                      </span>
+                    </div>
+                    {/* Untracked: the content renders once per open; its own reactivity updates it in place. */}
+                    {untrack(() =>
+                      menu()({
+                        get session() {
+                          return props.input.session
+                        },
+                        get screen() {
+                          return props.input.screen
+                        },
+                        close: () => setState("open", false),
+                      }),
                     )}
-                  </For>
-                </Menu.Group>
-                <Show when={current().actions?.length}>
-                  <div data-slot="session-plugin-pill-actions" class="flex justify-end gap-1 px-1 pt-1">
-                    <For each={current().actions}>
-                      {(action) => (
-                        <Menu.Item data-slot="session-plugin-pill-action" class="!px-2" onSelect={() => action.run()}>
-                          <PillIcon name={action.icon} />
-                          <span dir="auto" class="whitespace-nowrap">
-                            {action.label}
-                          </span>
-                        </Menu.Item>
-                      )}
-                    </For>
-                  </div>
-                </Show>
-              </Menu.Content>
-            </Menu.Portal>
-          </Menu>
-        </Show>
+                  </Popover.Content>
+                </Popover.Portal>
+              </Popover>
+            )}
+          </Match>
+          <Match when={current().rows}>
+            {(rows) => (
+              <Menu gutter={8} placement={placement()}>
+                <Menu.Trigger
+                  as="button"
+                  type="button"
+                  data-slot="session-plugin-pill"
+                  aria-label={current().title}
+                  class={capsule}
+                >
+                  <Content view={current()} />
+                </Menu.Trigger>
+                <Menu.Portal>
+                  <Menu.Content data-slot="session-plugin-pill-menu" aria-label={current().title ?? current().label}>
+                    <Menu.Group>
+                      <Menu.GroupLabel class="!h-auto max-w-80 !py-1.5">
+                        <span dir="auto" class="line-clamp-3 break-words">
+                          {current().title ?? current().label}
+                        </span>
+                      </Menu.GroupLabel>
+                      <For each={rows()}>
+                        {(row) => (
+                          <Menu.Item
+                            data-slot="session-plugin-pill-row"
+                            disabled={!row.run}
+                            onSelect={() => row.run?.()}
+                            badge={row.detail}
+                          >
+                            <PillIcon name={row.icon} tone={row.tone} />
+                            <span dir="auto" class="min-w-0 flex-1 truncate">
+                              {row.label}
+                            </span>
+                          </Menu.Item>
+                        )}
+                      </For>
+                    </Menu.Group>
+                  </Menu.Content>
+                </Menu.Portal>
+              </Menu>
+            )}
+          </Match>
+        </Switch>
       )}
     </Show>
   )

packages/gui-plugins/README.md

@@ -223,7 +223,7 @@ SDK icon fields take an `IconName` from `@opencode/plugin/gui`: the names of the
 | [`Server`](../plugin/src/gui/registries.ts)       | window  | A source of servers, such as SSH hosts                                                                                                                              |
 | [`LinkHandler`](../plugin/src/gui/registries.ts)  | window  | Opens local links, such as file paths in messages, and says whether their target exists                                                                             |
 | [`TitlebarItem`](../plugin/src/gui/registries.ts) | window  | A pill in the titlebar or the tabs footer                                                                                                                           |
-| [`ComposerPill`](../plugin/src/gui/registries.ts) | window  | A pill in the row above a session's composer, optionally opening a menu of rows with a row of action buttons                                                        |
+| [`ComposerPill`](../plugin/src/gui/registries.ts) | window  | A pill in the row above a session's composer, optionally opening a menu of rows or a popover of your own content                                                    |
 | [`Slot`](../plugin/src/gui/registries.ts)         | window  | Content for `window.bottom`, `session.header`, `session.location.menu`, `session.panel.end`; built-ins also fill `session.location.workspace`, `session.location.branch.menu` and `session.location.path.menu` through `BuiltinSlot` |
 | [`Style`](../plugin/src/gui/registries.ts)        | window  | CSS imported with `?inline`                                                                                                                                         |
 | [`MenubarItem`](../plugin/src/gui/main.ts)        | main    | An item of the native app menu                                                                                                                                      |

packages/gui-plugins/src/goal/renderer.tsx

@@ -1,6 +1,8 @@
-import { ComposerPill, type ComposerPillAction, type ComposerPillProps, type Plugin } from "@opencode/plugin/gui"
+import { ComposerPill, type ComposerPillProps, type Plugin } from "@opencode/plugin/gui"
 import { SessionGoal } from "@opencode/schema/session-goal"
+import { Button } from "@opencode/ui/button"
 import { showToast } from "@opencode/ui/toast"
+import { Show } from "solid-js"
 import type Goal from "./index"
 
 const status = {
@@ -10,10 +12,18 @@ const status = {
 } as const
 
 /**
- * The session's `/goal` above its composer: the status as a pill, and a menu headed by the objective with the actions
- * that apply. The server's goal plugin keeps the goal in the session's metadata; a bare `/goal` shows the last reason.
+ * The session's `/goal` above its composer: the status as a pill, and a popover headed by the objective with the
+ * actions that apply. The server's goal plugin keeps the goal in the session's metadata; a bare `/goal` shows the last
+ * reason.
  */
 const setup: Plugin.Setup<typeof Goal> = (ctx) => {
+  // A goal copied from the parent belongs to the parent, so only the session's own goal shows.
+  const goal = (input: ComposerPillProps) => {
+    const session = input.session.server.data.session.get(input.session.id)
+
+    return session && SessionGoal.fromMetadata(session.id, session.metadata)
+  }
+
   const command = (input: ComposerPillProps, text: "pause" | "resume" | "clear") =>
     void input.session.server.client.session
       .command({ sessionID: input.session.id, name: "goal", text })
@@ -28,24 +38,37 @@ const setup: Plugin.Setup<typeof Goal> = (ctx) => {
   ctx.add(ComposerPill, {
     id: "goal",
     show: (input) => {
-      const session = input.session.server.data.session.get(input.session.id)
-      // A goal copied from the parent belongs to the parent, so only the session's own goal shows.
-      const goal = session && SessionGoal.fromMetadata(session.id, session.metadata)
-
-      if (!goal) return
+      const current = goal(input)
 
-      const view = status[goal.status]
-      const actions: ComposerPillAction[] = []
+      if (!current) return
 
-      if (goal.status === "active")
-        actions.push({ id: "pause", label: ctx.t("pause"), icon: "stop", run: () => command(input, "pause") })
+      const view = status[current.status]
 
-      if (goal.status === "paused")
-        actions.push({ id: "resume", label: ctx.t("resume"), icon: "refresh", run: () => command(input, "resume") })
-
-      actions.push({ id: "clear", label: ctx.t("clear"), icon: "outline-trash", run: () => command(input, "clear") })
+      return { label: ctx.t(view.label), icon: view.icon, tone: view.tone, title: current.objective }
+    },
+    menu: (input) => {
+      const run = (text: "pause" | "resume" | "clear") => {
+        input.close()
+        command(input, text)
+      }
 
-      return { label: ctx.t(view.label), icon: view.icon, tone: view.tone, title: goal.objective, actions }
+      return (
+        <div class="flex justify-end gap-1 px-1 pt-1">
+          <Show when={goal(input)?.status === "active"}>
+            <Button size="small" variant="ghost" icon="stop" onClick={() => run("pause")}>
+              {ctx.t("pause")}
+            </Button>
+          </Show>
+          <Show when={goal(input)?.status === "paused"}>
+            <Button size="small" variant="ghost" icon="refresh" onClick={() => run("resume")}>
+              {ctx.t("resume")}
+            </Button>
+          </Show>
+          <Button size="small" variant="ghost" icon="outline-trash" onClick={() => run("clear")}>
+            {ctx.t("clear")}
+          </Button>
+        </div>
+      )
     },
   })
 }

packages/plugin/src/gui/registries.ts

@@ -619,16 +619,10 @@ export interface ComposerPillRow {
   run?(): void
 }
 
-/** A button in the row at the bottom of the menu a composer pill opens. */
-export interface ComposerPillAction {
-  /** The button's id, unique within the pill. */
-  readonly id: string
-  /** The button's text. */
-  readonly label: string
-  /** The button's icon. Omit it for none. */
-  readonly icon?: IconName
-  /** Runs when the user clicks the button; the menu then closes. */
-  run(): void
+/** What a composer pill's `menu` receives: the pill's session and a way to close the popover. Do not destructure. */
+export interface ComposerPillMenuProps extends ComposerPillProps {
+  /** Closes the popover, for example after the user picks an action in it. Does nothing once it is closed. */
+  close(): void
 }
 
 /** What a composer pill shows above one session's composer. */
@@ -640,18 +634,13 @@ export interface ComposerPillView {
   /** Colors the capsule's icon. */
   readonly tone?: ComposerPillTone
   /**
-   * Accessible name, and the heading of the menu the pill opens, when it differs from `label`. The heading wraps to at
-   * most three lines, then truncates.
+   * Accessible name, and the heading of the menu or popover the pill opens, when it differs from `label`. The heading
+   * wraps to at most three lines, then truncates.
    */
   readonly title?: string
-  /** The rows of the menu the pill opens. Omit them, and `actions`, for a pill that runs `run` instead. */
+  /** The menu the pill opens. Omit it for a pill that runs `run` instead. Unused when the pill has a `menu`. */
   readonly rows?: readonly ComposerPillRow[]
-  /**
-   * Buttons in one row at the bottom of the menu the pill opens, for actions on what the pill shows, such as pause and
-   * clear. The pill opens its menu when it has rows or actions.
-   */
-  readonly actions?: readonly ComposerPillAction[]
-  /** Runs when the user clicks a pill without `rows` or `actions`. */
+  /** Runs when the user clicks a pill without `rows` or a `menu`. */
   run?(): void
 }
 
@@ -672,6 +661,16 @@ export interface ComposerPill {
    * @param input - The session and its screen. Do not destructure.
    */
   show(input: ComposerPillProps): ComposerPillView | undefined
+  /**
+   * Your content for the popover the pill opens, for a pill that needs more than `rows`, such as status text and
+   * buttons. The host owns the capsule and the popover around this content: its placement, focus, dismissal, and the
+   * heading (`title`, else `label`). When set, clicking the pill opens the popover, and the view's `rows` and `run` are
+   * unused. Renders each time the popover opens; its own reactivity updates it while open, also when another session is
+   * routed. A render that throws renders nothing and records the error.
+   *
+   * @param input - The session, its screen, and `close`. Do not destructure.
+   */
+  menu?(input: ComposerPillMenuProps): JSX.Element
 }
 
 /** The places a `Slot` renders, with the input each passes to `render`. */