diff --git a/packages/app/component-tests/plugin-host.fixture.tsx b/packages/app/component-tests/plugin-host.fixture.tsx
index e54ccb77587..09c82550aa6 100644
--- a/packages/app/component-tests/plugin-host.fixture.tsx
+++ b/packages/app/component-tests/plugin-host.fixture.tsx
@@ -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: {
)}
+
)
}
diff --git a/packages/app/component-tests/plugin-host.spec.ts b/packages/app/component-tests/plugin-host.spec.ts
index 3a5fb6b5b4f..e42e52740d0 100644
--- a/packages/app/component-tests/plugin-host.spec.ts
+++ b/packages/app/component-tests/plugin-host.spec.ts
@@ -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 }
@@ -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(`[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 }) => {
diff --git a/packages/app/src/runtime/plugin/render.tsx b/packages/app/src/runtime/plugin/render.tsx
index 90be86625e8..8eb4c2d2a3e 100644
--- a/packages/app/src/runtime/plugin/render.tsx
+++ b/packages/app/src/runtime/plugin/render.tsx
@@ -96,6 +96,30 @@ export function PluginSlot(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 (
+
+
+
+
+
+ )
+}
+
export function PluginStyles() {
const host = usePluginHost()
diff --git a/packages/app/src/shell/shell.tsx b/packages/app/src/shell/shell.tsx
index 0312e34b843..2f63b79852f 100644
--- a/packages/app/src/shell/shell.tsx
+++ b/packages/app/src/shell/shell.tsx
@@ -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). */}
+
diff --git a/packages/gui-plugins/README.md b/packages/gui-plugins/README.md
index d3a685c55af..9badb3474b5 100644
--- a/packages/gui-plugins/README.md
+++ b/packages/gui-plugins/README.md
@@ -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
diff --git a/packages/plugin/src/gui/context.typecheck.ts b/packages/plugin/src/gui/context.typecheck.ts
index 59cd162ec1a..a94936cbd06 100644
--- a/packages/plugin/src/gui/context.typecheck.ts
+++ b/packages/plugin/src/gui/context.typecheck.ts
@@ -118,6 +118,8 @@ equal(true)
equal(true)
+equal(true)
+
equal(true)
export const ineligible: PanelTab = { id: "details", title: "Details", fallback: false }
diff --git a/packages/plugin/src/gui/registries.ts b/packages/plugin/src/gui/registries.ts
index 09481f4dabf..8f86727fda5 100644
--- a/packages/plugin/src/gui/registries.ts
+++ b/packages/plugin/src/gui/registries.ts
@@ -863,6 +863,17 @@ export interface Theme {
export interface SlotMap {
/** Full-width strip under the window content, above toasts. */
readonly "window.bottom": Record
+ /**
+ * 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
/** 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. */
diff --git a/services/www/src/docs/content/build/plugins/gui/index.mdx b/services/www/src/docs/content/build/plugins/gui/index.mdx
index 4adbbfacd92..cb30d32cd74 100644
--- a/services/www/src/docs/content/build/plugins/gui/index.mdx
+++ b/services/www/src/docs/content/build/plugins/gui/index.mdx
@@ -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: () => 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
+ "window.overlay": Record
"session.header": { screen: SessionScreen; session: MountedSession; active: boolean }
"session.location.menu": { screen: SessionScreen; session: MountedSession; shown: boolean }
"session.panel.end": { screen: SessionScreen; session: MountedSession }