feat(desktop): ctx.os — the curated OS door for plugins
Fold ctx.notifyNative into a ctx.os namespace so every way a plugin reaches outside the app window lives behind one attributed door instead of accreting one top-level ctx method per capability: - ctx.os.notify — the native-notification door from the previous commit, unchanged semantics (plugin kind pref, away-gating, per-plugin throttle). - ctx.os.openExternal / ctx.os.revealPath / ctx.os.writeClipboard — the existing window.hermesDesktop bridge capabilities, now sanctioned and result-shaped: each resolves false (never throws) when the bridge or member is missing, so a plugin branches on the result instead of sniffing the preload surface or crashing on an older shell. No new Electron surface: everything routes through bridge members the app already ships; the notification path keeps every existing gate.
This commit is contained in:
@@ -168,8 +168,8 @@ interface PluginContext {
|
||||
rest: <T>(path: string, opts?: PluginRestOptions) => Promise<T>
|
||||
/** Live WebSocket to this plugin's own namespace. Returns a disposer. */
|
||||
socket: (path: string, onMessage: (data: unknown) => void) => () => void
|
||||
/** Native OS notification (Electron), attributed to this plugin. */
|
||||
notifyNative: (input: { title: string; body?: string; silent?: boolean }) => void
|
||||
/** The curated OS door: native notification, open-external, reveal-in-file-manager, clipboard. */
|
||||
os: PluginOs
|
||||
/** Plugin-scoped JSON persistence (keys live under `hermes.plugin.<id>.`). */
|
||||
storage: PluginStorage
|
||||
}
|
||||
@@ -372,7 +372,10 @@ host.state.viewport // ReadableAtom<{ width, height, narrow }>
|
||||
|
||||
host.notify({ kind, message, title?, detail?, action? }) // toast; returns id
|
||||
host.notifyError(error, fallbackMessage) // toast an error
|
||||
ctx.notifyNative({ title, body?, silent? }) // native OS notification
|
||||
ctx.os.notify({ title, body?, silent? }) // native OS notification (attributed to your plugin)
|
||||
ctx.os.openExternal(url) // OS default handler (browser, mail, spotify:) → Promise<boolean>
|
||||
ctx.os.revealPath(path) // reveal in Finder / Explorer → Promise<boolean>
|
||||
ctx.os.writeClipboard(text) // system clipboard → Promise<boolean>
|
||||
host.navigate('/route') // hash-route navigation
|
||||
host.onEvent(type, fn) // gateway event stream ('*' = all); returns disposer
|
||||
host.logs(...) // tail an app log file
|
||||
@@ -388,13 +391,17 @@ listener can't affect app dispatch. Every `host` door is async-safe: a sync thro
|
||||
from an internal helper (e.g. no desktop bridge in a plain browser) becomes a
|
||||
rejection your `.catch()` sees, never an error-boundary crash.
|
||||
|
||||
`ctx.notifyNative` (on the plugin context, so the notification is attributed to
|
||||
your plugin) posts a **native OS notification** — the same Electron pipeline the
|
||||
app's own approval/turn alerts use. It fires only while the user is away from
|
||||
Hermes (backgrounded / unfocused); use `host.notify` for the in-app toast when
|
||||
`ctx.os` is the curated OS door — every way a plugin reaches outside the app
|
||||
window, in one namespace attributed to your plugin. `ctx.os.notify` posts a
|
||||
**native OS notification** — the same Electron pipeline the app's own
|
||||
approval/turn alerts use. It fires only while the user is away from Hermes
|
||||
(backgrounded / unfocused); use `host.notify` for the in-app toast when
|
||||
they're looking at the app. Users can silence it per device under Settings ▸
|
||||
Notifications ▸ "Plugin notifications", and repeats from the same plugin are
|
||||
throttled, so treat it as a signal for genuinely notable events — not a log.
|
||||
The other doors (`openExternal`, `revealPath`, `writeClipboard`) resolve
|
||||
`false` instead of throwing when the capability isn't available (older desktop
|
||||
shell, plain browser) — branch on the result rather than sniffing the bridge.
|
||||
|
||||
## Data layer — React Query + nanostores
|
||||
|
||||
@@ -608,7 +615,7 @@ not treat this pipeline as a trust boundary.
|
||||
| Category | Exports |
|
||||
|----------|---------|
|
||||
| Host | `host` (`.state.*`, `.notify`, `.notifyError`, `.navigate`, `.onEvent`, `.logs`, `.status`, `.restartGateway`, `.request`) |
|
||||
| Plugin contract | `HermesPlugin`, `PluginContext`, `PluginContribution`, `PluginStorage`, `PluginRestOptions`, `PluginNativeNotificationInput`, `Contribution` |
|
||||
| Plugin contract | `HermesPlugin`, `PluginContext`, `PluginContribution`, `PluginStorage`, `PluginOs`, `PluginRestOptions`, `PluginNativeNotificationInput`, `Contribution` |
|
||||
| Area constants | `PANES_AREA`, `ROUTES_AREA`, `SIDEBAR_NAV_AREA`, `STATUSBAR_AREAS`, `TITLEBAR_AREAS`, `PALETTE_AREA`, `KEYBINDS_AREA`, `THEMES_AREA`, `COMPOSER_AREAS` |
|
||||
| Area payloads | `RouteContribution`, `SidebarNavContribution`, `StatusbarItem`, `TitlebarTool`, `PaletteContribution`, `KeybindContribution`, `ComposerMiddleware`, `ComposerAttachmentProvider` |
|
||||
| React / state | `useValue`, `atom`, `computed`, `useQuery`, `useMutation`, `useQueryClient`, `queryClient`, `Contribute` |
|
||||
|
||||
Reference in New Issue
Block a user