From 910832f39e73629948c1685e6480cd82f4b00506 Mon Sep 17 00:00:00 2001
From: Luke Parker <10430890+Hona@users.noreply.github.com>
Date: Wed, 4 Nov 2026 16:33:53 -0600
Subject: [PATCH] refactor(app): end each plugin dialog exactly once through a
state machine (#61803)
---
.../src/runtime/plugin/dialog-machine.test.ts | 62 ++++++++++
.../app/src/runtime/plugin/dialog-machine.ts | 81 +++++++++++++
packages/app/src/runtime/plugin/host.tsx | 114 +++++++++++-------
3 files changed, 213 insertions(+), 44 deletions(-)
create mode 100644 packages/app/src/runtime/plugin/dialog-machine.test.ts
create mode 100644 packages/app/src/runtime/plugin/dialog-machine.ts
diff --git a/packages/app/src/runtime/plugin/dialog-machine.test.ts b/packages/app/src/runtime/plugin/dialog-machine.test.ts
new file mode 100644
index 00000000000..de89579cecd
--- /dev/null
+++ b/packages/app/src/runtime/plugin/dialog-machine.test.ts
@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test"
+import {
+ createPluginDialogState,
+ transitionPluginDialog,
+ type PluginDialogEffect,
+ type PluginDialogEvent,
+ type PluginDialogState,
+} from "./dialog-machine"
+
+/** Folds events through the machine from a new handle, collecting every effect in order. */
+function replay(events: readonly PluginDialogEvent[]) {
+ return events.reduce<{ state: PluginDialogState; effects: PluginDialogEffect["type"][] }>(
+ (current, event) => {
+ const next = transitionPluginDialog(current.state, event)
+
+ return { state: next.state, effects: [...current.effects, ...next.effects.map((effect) => effect.type)] }
+ },
+ { state: createPluginDialogState(), effects: [] },
+ )
+}
+
+const open: PluginDialogEvent = { type: "open", aborted: false }
+
+// Before, closing a shown dialog ran `ended` once through the stack's onClose and again directly, and once more when
+// the scope that opened it went away.
+test("closing a shown dialog ends it once, whatever closes it afterwards", () => {
+ const run = replay([open, { type: "mounted" }, { type: "close" }, { type: "dismissed" }, { type: "close" }])
+
+ expect(run.state.status).toBe("closed")
+ expect(run.effects).toEqual(["register", "wait", "show", "abort", "close", "release", "ended"])
+})
+
+// Before, a dialog closed before it mounted kept its close registered with the plugin, which ran `ended` again at
+// teardown.
+test.each<{ name: string; events: PluginDialogEvent[]; effects: PluginDialogEffect["type"][] }>([
+ {
+ name: "waits for the app interface",
+ events: [open, { type: "close" }, { type: "mounted" }],
+ effects: ["register", "wait", "cancel", "release", "ended"],
+ },
+ {
+ name: "waits for the stack to mount it",
+ // The stack sees the aborted open and reports it dropped.
+ events: [open, { type: "mounted" }, { type: "close" }, { type: "dismissed" }],
+ effects: ["register", "wait", "show", "abort", "close", "release", "ended"],
+ },
+])("a dialog closed while it $name is released and ends once", (input) => {
+ expect(replay(input.events).effects).toEqual(input.effects)
+})
+
+test("a dialog the stack dismisses ends without closing anything else", () => {
+ const run = replay([open, { type: "mounted" }, { type: "dismissed" }, { type: "close" }])
+
+ expect(run.effects).toEqual(["register", "wait", "show", "release", "ended"])
+})
+
+test("a dialog asked of a plugin that went away ends at once and registers nothing", () => {
+ const run = replay([{ type: "open", aborted: true }, { type: "mounted" }, { type: "close" }])
+
+ expect(run.effects).toEqual(["ended"])
+ expect(transitionPluginDialog(run.state, { type: "close" }).state).toBe(run.state)
+})
diff --git a/packages/app/src/runtime/plugin/dialog-machine.ts b/packages/app/src/runtime/plugin/dialog-machine.ts
new file mode 100644
index 00000000000..f01b378e2db
--- /dev/null
+++ b/packages/app/src/runtime/plugin/dialog-machine.ts
@@ -0,0 +1,81 @@
+/** One dialog a plugin opened, from `ctx.dialogs.open` until its `ended` callback runs, once. */
+export type PluginDialogState =
+ /** The handle exists; the open has not been requested yet. */
+ | { readonly status: "created" }
+ /** Waits for the app interface to mount, so it never shows behind the startup screen. */
+ | { readonly status: "waiting" }
+ /** Handed to the dialog stack, which mounts it in a later transition. */
+ | { readonly status: "shown" }
+ | { readonly status: "closed" }
+
+export type PluginDialogEvent =
+ /** `aborted`: the plugin, or the scope that opened the dialog, already went away. */
+ | { readonly type: "open"; readonly aborted: boolean }
+ | { readonly type: "mounted" }
+ /** The handle's `close`, the plugin or scope going away, or the content failing to render. */
+ | { readonly type: "close" }
+ /** The stack closed or dropped the dialog: Escape, a click outside, a replacing dialog, or its root going away. */
+ | { readonly type: "dismissed" }
+
+export type PluginDialogEffect =
+ /** Ties the dialog to the plugin or scope that opened it. */
+ | { readonly type: "register" }
+ | { readonly type: "release" }
+ | { readonly type: "wait" }
+ | { readonly type: "cancel" }
+ | { readonly type: "show" }
+ /** Keeps a deferred open from mounting or replacing another dialog. */
+ | { readonly type: "abort" }
+ | { readonly type: "close" }
+ | { readonly type: "ended" }
+
+export type PluginDialogTransition = {
+ readonly state: PluginDialogState
+ readonly effects: readonly PluginDialogEffect[]
+}
+
+const created: PluginDialogState = { status: "created" }
+
+const waiting: PluginDialogState = { status: "waiting" }
+
+const shown: PluginDialogState = { status: "shown" }
+
+const closed: PluginDialogState = { status: "closed" }
+
+export function createPluginDialogState() {
+ return created
+}
+
+export function transitionPluginDialog(state: PluginDialogState, event: PluginDialogEvent): PluginDialogTransition {
+ if (state.status === "created") {
+ if (event.type !== "open") return step(state)
+
+ if (event.aborted) return step(closed, [{ type: "ended" }])
+
+ return step(waiting, [{ type: "register" }, { type: "wait" }])
+ }
+
+ if (state.status === "waiting") {
+ if (event.type === "mounted") return step(shown, [{ type: "show" }])
+
+ if (event.type === "close") return step(closed, [{ type: "cancel" }, { type: "release" }, { type: "ended" }])
+
+ return step(state)
+ }
+
+ if (state.status === "shown") {
+ // An open the stack has not mounted yet is aborted; a mounted one closes by its own id, never the top one.
+ if (event.type === "close")
+ return step(closed, [{ type: "abort" }, { type: "close" }, { type: "release" }, { type: "ended" }])
+
+ if (event.type === "dismissed") return step(closed, [{ type: "release" }, { type: "ended" }])
+
+ return step(state)
+ }
+
+ return step(state)
+}
+
+function step(state: PluginDialogState, effects: readonly PluginDialogEffect[] = []): PluginDialogTransition {
+ return { state, effects }
+}
diff --git a/packages/app/src/runtime/plugin/host.tsx b/packages/app/src/runtime/plugin/host.tsx
index 7378f4a67b8..5d7d6ea3d8b 100644
--- a/packages/app/src/runtime/plugin/host.tsx
+++ b/packages/app/src/runtime/plugin/host.tsx
@@ -51,6 +51,12 @@ import {
} from "@opencode/plugin/gui"
import { OpenCode, type OpenCodeClient } from "@opencode/client/promise"
import { useLanguage } from "@/runtime/i18n/language"
+import {
+ createPluginDialogState,
+ transitionPluginDialog,
+ type PluginDialogEffect,
+ type PluginDialogEvent,
+} from "./dialog-machine"
import { PluginAlertDialog, PluginConfirmDialog, PluginPromptDialog, PluginSelectDialog } from "./dialogs"
import { selectDisabled, selectHostReady, selectInstalled, selectMainFailed, selectServersReady } from "./machine"
import { createStartupGate } from "./startup"
@@ -333,62 +339,82 @@ function createHost(input: HostInput) {
ended?: () => void,
): DialogHandle => {
const id = `plugin:${plugin}:${sequence.value++}`
- const waiting = { cancel: () => {} }
// This open alone: once it aborts, a deferred open neither mounts nor replaces another dialog.
const opening = new AbortController()
+ const edge = { state: createPluginDialogState(), cancel: () => {}, release: () => {} }
+ // Events an effect raises synchronously (the interface already mounted, the stack closing) wait behind it.
+ const queue: PluginDialogEvent[] = []
- // Each handle names its own dialog, so it never closes one another plugin or instance opened. Closing a
- // dialog that still waits for the app interface, or for its deferred open, cancels it.
- const close = () => {
- abort(opening)
- waiting.cancel()
- dialog.close(id)
- ended?.()
+ const dispatch = (event: PluginDialogEvent) => {
+ queue.push(event)
+
+ if (queue.length === 1) drain()
}
- const handle = { close }
+ const drain = () => {
+ const event = queue[0]
- if (context.signal.aborted) {
- ended?.()
+ if (!event) return
- return handle
+ const next = transitionPluginDialog(edge.state, event)
+
+ edge.state = next.state
+ next.effects.forEach(run)
+ queue.shift()
+ drain()
}
- // Closes this dialog, not whichever is on top, when the plugin or the scope that opened it goes away.
- const release = register(close)
+ // Each handle names its own dialog, so it never closes one another plugin or instance opened.
+ const handle = { close: () => dispatch({ type: "close" }) }
- // A dialog opened before the app interface mounts, as during setup, shows after its first render: never behind
- // the startup screen, and never before a route that focuses itself as it mounts.
- waiting.cancel = input.whenMounted(
- () =>
- void dialog[options?.replace ? "show" : "push"](
- () => {
- // The dialog's root disposes when it closes or another dialog replaces it.
- onCleanup(() => void release())
+ const run = (effect: PluginDialogEffect) => {
+ // Closes this dialog, not whichever is on top, when the plugin or the scope that opened it goes away.
+ if (effect.type === "register") return void (edge.release = register(handle.close))
- return (
- {
- onMount(() => {
- dialog.close(id)
- fail(plugin, error, "render")
- })
+ // A dialog opened before the app interface mounts, as during setup, shows after its first render: never
+ // behind the startup screen, and never before a route that focuses itself as it mounts.
+ if (effect.type === "wait") return void (edge.cancel = input.whenMounted(() => dispatch({ type: "mounted" })))
- return null
- }}
- >
- {untrack(() => render(handle))}
-
- )
- },
- // Escape, a click outside, a replacing dialog, or an open the stack dropped.
- ended,
- id,
- // The stack mounts in a later transition. Its handle, its owner or the plugin ending before then keeps
- // it closed.
- AbortSignal.any([opening.signal, context.signal]),
- ),
- )
+ if (effect.type === "cancel") return edge.cancel()
+
+ if (effect.type === "release") return void edge.release()
+
+ if (effect.type === "abort") return abort(opening)
+
+ if (effect.type === "close") return dialog.close(id)
+
+ if (effect.type === "ended") return ended?.()
+
+ void dialog[options?.replace ? "show" : "push"](
+ () => {
+ // The dialog's root disposes when it closes, another dialog replaces it, or the stack goes away.
+ onCleanup(() => dispatch({ type: "dismissed" }))
+
+ return (
+ {
+ onMount(() => {
+ handle.close()
+ fail(plugin, error, "render")
+ })
+
+ return null
+ }}
+ >
+ {untrack(() => render(handle))}
+
+ )
+ },
+ // Escape, a click outside, a replacing dialog, or an open the stack dropped.
+ () => dispatch({ type: "dismissed" }),
+ id,
+ // The stack mounts in a later transition. Its handle, its owner or the plugin ending before then keeps
+ // it closed.
+ AbortSignal.any([opening.signal, context.signal]),
+ )
+ }
+
+ dispatch({ type: "open", aborted: context.signal.aborted })
return handle
}