mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-16 05:01:03 +03:00
feat(plugin): add a window.overlay slot for full-window GUI plugin layers
This commit is contained in:
@@ -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()
|
||||
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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 }
|
||||
|
||||
@@ -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 }
|
||||
|
||||
Reference in New Issue
Block a user