feat(plugin): add a window.overlay slot for full-window GUI plugin layers

This commit is contained in:
Luke Parker
2026-11-06 04:17:01 +10:00
Unverified
parent f7cf3a10f4
commit 5fa8c824f0
8 changed files with 210 additions and 20 deletions
@@ -45,7 +45,7 @@ import { createRegion, RegionContent } from "../src/runtime/plugin/panels"
import { createSessionScreenLayout } from "../src/session/screen-layout"
import type { SessionModel } from "../src/session/model"
import { createClosedTabs } from "../src/runtime/plugin/closed-tabs"
import { PluginLinks, PluginSlot, PluginThemes } from "../src/runtime/plugin/render"
import { PluginLinks, PluginSlot, PluginThemes, PluginWindowOverlay } from "../src/runtime/plugin/render"
import { Markdown } from "@opencode/session-ui/markdown"
import { ThemeProvider, useTheme, type ColorScheme } from "@opencode/ui/theme/context"
import { persistedHandle } from "../src/runtime/plugin/stores"
@@ -228,7 +228,7 @@ export function mountPluginHost() {
/**
* Mounts the real host over these definitions, before any session mounts, with the HostApis faked at their
* boundary. Storage is the real persisted store of a desktop window whose reads wait until `release()`; `stored` seeds
* it. Renders the `window.bottom` slot once the startup gate opens.
* it. Renders the `window.bottom` and `window.overlay` slots once the startup gate opens.
*/
export function mountPlugins(input: {
definitions: readonly Entry[]
@@ -301,6 +301,7 @@ export function mountPlugins(input: {
)}
</Show>
<PluginSlot at="window.bottom" input={{}} />
<PluginWindowOverlay />
</Show>
)
}
@@ -30,6 +30,9 @@ type Scope = { owner?: Owner | null; end: () => void; ctx?: Context }
/** The context the session-routing case keeps from inside its plugin. */
type Kept = { ctx?: Context }
/** The contexts the window overlay case keeps from inside its two plugins. */
type Overlays = { fixture?: Context; broken?: Context }
/** What the asking case keeps from inside its plugin: its dialogs, the end of its scope, and that scope's prompt. */
type Asked = { dialogs?: Dialogs; end?: () => void; prompt?: Promise<string | undefined> }
@@ -985,6 +988,95 @@ story("a contribution that throws renders nothing and records the error; the oth
})
})
story(
"window.overlay covers the app without taking its clicks, stays below dialogs, and leaves when empty",
async ({ page }) => {
const result = await page.evaluate(async (fixture) => {
const { mountPlugins, until, Slot } = await import(fixture)
const kept: Overlays = {}
const layer = () => document.querySelector('[data-slot="plugin-window-overlay"]')
const find = (name: string) => document.querySelector<HTMLElement>(`[data-hit="${name}"]`)
const hit = (x: number, y: number) =>
document.elementFromPoint(x, y)?.closest("[data-hit]")?.getAttribute("data-hit")
const element = (name: string, style: string) => () => {
const div = document.createElement("div")
div.dataset.hit = name
div.style.cssText = style
return div
}
// The shell's highest chrome is fixed at z-index 40, as its collapsed sidebar toggle.
const beneath = element(
"beneath",
"position: fixed; left: 40px; top: 40px; width: 120px; height: 40px; z-index: 40",
)()
document.body.append(beneath)
const host = mountPlugins({
definitions: [
{ id: "fixture", windowEntry: async () => ({ default: (ctx: Context) => void (kept.fixture = ctx) }) },
{ id: "broken", windowEntry: async () => ({ default: (ctx: Context) => void (kept.broken = ctx) }) },
],
})
await until(() => host.status("fixture") === "active" && host.status("broken") === "active")
const empty = !layer()
const veil = kept.fixture?.add(Slot, {
at: "window.overlay",
render: element("veil", "position: absolute; inset: 0"),
})
kept.broken?.add(Slot, {
at: "window.overlay",
render: () => {
throw new Error("broken overlay")
},
})
await until(() => !!find("veil") && !!host.failure("broken"))
const box = find("veil")?.getBoundingClientRect()
const covers = box?.width === window.innerWidth && box.height === window.innerHeight
const passes = hit(100, 60)
const grab = kept.fixture?.add(Slot, {
at: "window.overlay",
render: element("grab", "position: absolute; inset: 0; pointer-events: auto"),
})
await until(() => !!find("grab"))
const above = hit(100, 60)
const dialog = kept.fixture?.dialogs.open(element("dialog", "width: 240px; height: 120px; pointer-events: auto"))
await until(() => !!find("dialog"))
const below = hit(window.innerWidth / 2, window.innerHeight / 2)
const broken = { status: host.status("broken"), phase: host.failure("broken")?.phase }
dialog?.close()
veil?.()
grab?.()
host.disable(["broken"])
await until(() => !layer())
host.unmount()
beneath.remove()
return { empty, covers, passes, above, below, broken }
}, fixture)
expect(result).toEqual({
empty: true,
covers: true,
passes: "beneath",
above: "grab",
below: "dialog",
broken: { status: "active", phase: "render" },
})
},
)
story(
"plugin GUIs join, hot-reload in place, run their returned cleanup and leave, without holding startup",
async ({ page }) => {
@@ -96,6 +96,30 @@ export function PluginSlot<At extends keyof BuiltinSlotMap>(props: {
)
}
/**
* The `window.overlay` slot: a layer over the whole window that takes no pointer events, present only while a plugin
* contributes to it. Portalled to the body, so it covers the viewport whatever contains the shell. Its z-index puts it
* above the shell's chrome (the highest is 40) and below the host's portalled layers: dialogs, popovers and hover cards
* at 50, menus and selects at 60, tooltips and toasts at 1000. The desktop startup splash (100) stays above it too.
*/
export function PluginWindowOverlay() {
const host = usePluginHost()
const shown = createMemo(() => host.items(BuiltinSlot).some((item) => item.value.at === "window.overlay"))
return (
<Show when={shown()}>
<Portal>
<div
data-slot="plugin-window-overlay"
style={{ position: "fixed", inset: "0", "z-index": "45", "pointer-events": "none", contain: "strict" }}
>
<PluginSlot at="window.overlay" input={{}} />
</div>
</Portal>
</Show>
)
}
export function PluginStyles() {
const host = usePluginHost()
+2 -1
View File
@@ -11,7 +11,7 @@ import { UploadToastHost } from "@/composer/attachments/uploads"
import { useSettingsSurface } from "@/settings/surface"
import { useSettings } from "@/settings/model"
import { PluginServerCover } from "@/runtime/plugin/server-shell"
import { PluginSlot } from "@/runtime/plugin/render"
import { PluginSlot, PluginWindowOverlay } from "@/runtime/plugin/render"
import { COMMAND_SEARCH_ID, useCommand } from "@/shell/commands/command"
import { useLanguage } from "@/runtime/i18n/language"
import { useGlobal } from "@/runtime/server/runtime"
@@ -321,6 +321,7 @@ export default function Layout(props: ParentProps) {
Last in order, so it stays below a bottom titlebar (also order-last, but earlier in the DOM). */}
<div data-slot="composer-touch-bar-mount" class="order-last shrink-0" />
<PluginSlot at="window.bottom" input={{}} />
<PluginWindowOverlay />
<ToastRegion />
<UploadToastHost />
</div>
+20 -16
View File
@@ -252,22 +252,26 @@ SDK icon fields take an `IconName` from `@opencode/plugin/gui`: the names of the
### Registries
| Registry | Process | What an item is |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`Command`](../plugin/src/gui/registries.ts) | window | A palette command with an optional keybind and slash command |
| [`MenuItem`](../plugin/src/gui/registries.ts) | window | An item of a host menu: the side panel + menu, Add server, a server row |
| [`Panel`](../plugin/src/gui/registries.ts) | window | Tabs in the session's side region |
| [`SettingsPage`](../plugin/src/gui/registries.ts) | window | A settings page, a section on a host page, or rows in a host section |
| [`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 or a popover of your own content |
| [`CodeBlock`](../plugin/src/gui/registries.ts) | window | Your UI in place of the highlighted code of complete fenced code blocks of the languages you list, such as a diagram or a table |
| [`CodeBlockAction`](../plugin/src/gui/registries.ts) | window | A button beside the Copy button of complete fenced code blocks of the languages you list, such as "Run in terminal" |
| [`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` |
| [`Theme`](../plugin/src/gui/registries.ts) | window | A color theme in the app's theme file format, listed in Settings › Appearance › Theme |
| [`MenubarItem`](../plugin/src/gui/main.ts) | main | An item of the native app menu |
| Registry | Process | What an item is |
| ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`Command`](../plugin/src/gui/registries.ts) | window | A palette command with an optional keybind and slash command |
| [`MenuItem`](../plugin/src/gui/registries.ts) | window | An item of a host menu: the side panel + menu, Add server, a server row |
| [`Panel`](../plugin/src/gui/registries.ts) | window | Tabs in the session's side region |
| [`SettingsPage`](../plugin/src/gui/registries.ts) | window | A settings page, a section on a host page, or rows in a host section |
| [`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 or a popover of your own content |
| [`CodeBlock`](../plugin/src/gui/registries.ts) | window | Your UI in place of the highlighted code of complete fenced code blocks of the languages you list, such as a diagram or a table |
| [`CodeBlockAction`](../plugin/src/gui/registries.ts) | window | A button beside the Copy button of complete fenced code blocks of the languages you list, such as "Run in terminal" |
| [`Slot`](../plugin/src/gui/registries.ts) | window | Content for `window.bottom`, `window.overlay`, `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` |
| [`Theme`](../plugin/src/gui/registries.ts) | window | A color theme in the app's theme file format, listed in Settings › Appearance › Theme |
| [`MenubarItem`](../plugin/src/gui/main.ts) | main | An item of the native app menu |
`window.overlay` is a layer over the whole window, above the app's interface and below its dialogs, menus, popovers,
tooltips and toasts. The layer takes no pointer events: contributions set `pointer-events: auto` on their own
elements. The host adds it only while something contributes, and renders it with the shell, after the startup gate opens.
`session.location.menu` contributes items after the project menu's location details. It receives the owning `screen`,
the live `session`, and `shown`; keep data subscriptions active only while `shown` is true. Loading headers without an
@@ -118,6 +118,8 @@ equal<SlotMap["session.panel.end"]["screen"], SessionScreen>(true)
equal<SlotMap["window.bottom"]["screen"], never>(true)
equal<SlotMap["window.overlay"]["screen"], never>(true)
equal<PanelTab["fallback"], boolean | undefined>(true)
export const ineligible: PanelTab = { id: "details", title: "Details", fallback: false }
+11
View File
@@ -863,6 +863,17 @@ export interface Theme {
export interface SlotMap {
/** Full-width strip under the window content, above toasts. */
readonly "window.bottom": Record<string, never>
/**
* A layer over the whole window, for boot animations, ambient effects, focus overlays and coach marks. It sits above
* the app's interface and below its dialogs, menus, popovers, tooltips and toasts; the native window controls and
* the desktop title bar's drag region stay above it. The layer takes no pointer events (`pointer-events: none`), so
* the app beneath keeps working: set `pointer-events: auto` on the elements of yours that take clicks. Keep those out
* of the title bar, whose drag region takes the pointer first on desktop, and never set `app-region`. The host adds
* the layer only while something contributes, and does not animate it: honor `prefers-reduced-motion` in your own
* animations. It renders once the window's interface first renders, after the built-in plugins start; a plugin from
* the config may join later, so its first frame can come after the app's.
*/
readonly "window.overlay": Record<string, never>
/** The timeline title row. Cached timelines stay mounted while hidden; `active` is false then. */
readonly "session.header": {
/** The timeline's owning session screen; always present, also while the timeline is cached. */
@@ -996,7 +996,7 @@ interface SettingEntry {
### Slots
`Slot` renders UI into one of four window slots.
`Slot` renders UI into one of the window's slots.
```tsx
import { Slot } from "@opencode/plugin/gui"
@@ -1009,6 +1009,8 @@ ctx.add(Slot, {
```
- `window.bottom` is a full-width strip at the bottom of the window, above toasts.
- `window.overlay` is a layer over the whole window, for boot animations, ambient effects, and coach marks. See
[Window overlay](#window-overlay).
- `session.header` is the session timeline's title row. A cached timeline stays mounted while hidden, with `active`
`false`.
- `session.location.menu` adds items to the project menu, after its location details.
@@ -1035,6 +1037,58 @@ ctx.add(Slot, {
})
```
#### Window overlay
`window.overlay` renders over the whole window, such as a boot animation, an ambient effect, a focus overlay, or coach
marks that point at the app's interface. Withdraw the contribution when it is done:
```tsx
import { Slot } from "@opencode/plugin/gui"
const remove = ctx.add(Slot, {
at: "window.overlay",
render: () => <Intro onDone={() => remove()} />,
})
```
- The layer takes no pointer events, so clicks, hovers, and scrolling reach the app beneath it. Set
`pointer-events: auto` on each element of yours that takes them, such as a coach mark's button.
- It stacks above the app's interface and below its dialogs, menus, popovers, tooltips, and toasts. A dialog that opens
during your animation shows above it.
- On desktop, the native window controls stay above the layer, and the title bar keeps moving the window under your
content. Keep interactive elements out of the title bar, whose drag region takes the pointer first, and do not set
`app-region`.
- The host does not animate the layer. Honor `prefers-reduced-motion` in your own animations.
- The host adds the layer only while a contribution exists, and removes it when the last one is withdrawn.
- The layer renders on the app's screens: Home, sessions, and Settings.
```css title="intro.css"
.acme-intro {
pointer-events: auto;
animation: acme-intro-out 1.2s ease-in forwards;
}
@media (prefers-reduced-motion: reduce) {
.acme-intro {
animation-duration: 1ms;
}
}
```
The layer first renders with the window's interface. That sets when a boot animation can start:
1. On desktop, the window shows the app's loading splash.
2. The built-in plugins start. The interface first renders once they settle, or once their startup times out.
3. On desktop, the splash fades out over 300 ms once the first screen is ready.
4. Plugins from the config join as the desktop app sends their GUIs. They never hold startup, so your first frame can
come before or after the splash fades, and after the app's own first frame.
- Open on a frame that suits the app beneath it, such as the window's background color, and do not rely on the user
seeing the first moments of the animation.
- A reload of your plugin, such as a rebuild, runs `setup` again. To play once per window, keep a flag in
`ctx.storage.memory`, which survives plugin reloads.
- Third-party overlays show in the desktop app only. The web app runs built-in plugins only.
#### Reference
```ts
@@ -1044,6 +1098,7 @@ type Slot = {
interface SlotMap {
"window.bottom": Record<string, never>
"window.overlay": Record<string, never>
"session.header": { screen: SessionScreen; session: MountedSession; active: boolean }
"session.location.menu": { screen: SessionScreen; session: MountedSession; shown: boolean }
"session.panel.end": { screen: SessionScreen; session: MountedSession }