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 }