Skip to content

The agent that grows with you

feat(desktop): name what each browser-host check gates

Tekniumdb7490c3ed4e
diff --git a/apps/desktop/src/lib/host-capabilities.test.ts b/apps/desktop/src/lib/host-capabilities.test.ts
new file mode 100644
index 00000000000..e508cf2f9d5
--- /dev/null
+++ b/apps/desktop/src/lib/host-capabilities.test.ts
@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { HOST_CAPABILITIES, type HostCapability, hostHas } from './host-capabilities'
+import { isBrowserHostedDesktop } from './platform'
+
+interface HostGlobals {
+ __HERMES_AUTH_REQUIRED__?: boolean
+ __HERMES_UI_SURFACE__?: string
+ hermesDesktop?: unknown
+}
+
+const win = window as unknown as HostGlobals
+
+function reset() {
+ document.documentElement.removeAttribute('data-hermes-desktop-host')
+ delete win.__HERMES_AUTH_REQUIRED__
+ delete win.__HERMES_UI_SURFACE__
+ delete win.hermesDesktop
+}
+
+// Every way the renderer meets its host: before and after the bridge writes the marker.
+const HOST_STATES: { browser: boolean; name: string; setup: () => void }[] = [
+ { browser: true, name: 'browser marker', setup: () => (document.documentElement.dataset.hermesDesktopHost = 'browser') },
+ { browser: true, name: 'gated host before the marker', setup: () => (win.__HERMES_AUTH_REQUIRED__ = true) },
+ { browser: true, name: 'Webapp surface before the marker', setup: () => (win.__HERMES_UI_SURFACE__ = 'webapp') },
+ { browser: false, name: 'electron marker', setup: () => (document.documentElement.dataset.hermesDesktopHost = 'electron') },
+ {
+ browser: false,
+ name: 'Electron preload with a stale Webapp global',
+ setup: () => {
+ win.hermesDesktop = {}
+ win.__HERMES_UI_SURFACE__ = 'webapp'
+ }
+ },
+ { browser: false, name: 'no host signal', setup: () => undefined }
+]
+
+const CAPABILITIES = Object.keys(HOST_CAPABILITIES) as HostCapability[]
+
+afterEach(reset)
+
+describe('hostHas', () => {
+ // Parity with the predicate every call site used before: a browser capability is exactly
+ // `isBrowserHostedDesktop()`, a native one exactly its negation, in every host state.
+ for (const state of HOST_STATES) {
+ it(`matches isBrowserHostedDesktop() for every capability: ${state.name}`, () => {
+ state.setup()
+ expect(isBrowserHostedDesktop()).toBe(state.browser)
+
+ for (const capability of CAPABILITIES) {
+ const old = isBrowserHostedDesktop()
+ const expected = HOST_CAPABILITIES[capability] === 'browser' ? old : !old
+
+ expect([capability, hostHas(capability)]).toEqual([capability, expected])
+ }
+ })
+ }
+
+ it('follows the host marker written after import', () => {
+ expect(hostHas('clipboardIpc')).toBe(true)
+ document.documentElement.dataset.hermesDesktopHost = 'browser'
+ expect(hostHas('clipboardIpc')).toBe(false)
+ expect(hostHas('webappCopy')).toBe(true)
+ })
+})
diff --git a/apps/desktop/src/lib/host-capabilities.ts b/apps/desktop/src/lib/host-capabilities.ts
new file mode 100644
index 00000000000..21aca5d1670
--- /dev/null
+++ b/apps/desktop/src/lib/host-capabilities.ts
@@ -0,0 +1,76 @@
+/**
+ * What the renderer's host can do, by name.
+ *
+ * The same renderer runs in Electron (native Desktop) and in a browser tab the
+ * gateway serves (the Webapp). Call sites ask for the capability they gate,
+ * never for the host, so a reader sees why a branch exists and a later change
+ * to one capability does not ride along on every other host check.
+ *
+ * Each capability belongs to exactly one host. The host is read on every call
+ * (not once at import): the browser bridge writes the host marker after some
+ * modules have evaluated, and `isBrowserHostedDesktop` already answers both
+ * before and after it.
+ */
+
+import { isBrowserHostedDesktop } from '@/lib/platform'
+
+type Host = 'browser' | 'native'
+
+export const HOST_CAPABILITIES = Object.freeze({
+ /** Mouse back/forward buttons are the app's to handle; a browser tab keeps its own history. */
+ appMouseHistoryButtons: 'native',
+ /** The browser opens its own context menu, which the app menu must cancel or let through. */
+ browserContextMenu: 'browser',
+ /** Writes go through Electron's clipboard IPC before `navigator.clipboard`. */
+ clipboardIpc: 'native',
+ /** Gateway connection management (switch, connect, recover) lives on this host. */
+ gatewayManagement: 'native',
+ /** Links may open in the in-app browser pane instead of the OS browser. */
+ inAppLinks: 'native',
+ /** A composer press keeps editor focus (iOS blurs before submit runs). */
+ keepFocusOnPress: 'browser',
+ /** Cut, Copy, Paste and spelling rows come from Electron main. */
+ mainProcessEditVerbs: 'native',
+ /** Narrow overlays get titlebar chrome: Hide names the zone, the pane pads to the titlebar. */
+ narrowOverlayChrome: 'browser',
+ /** The default project folder is picked with the OS dialog. */
+ nativeFolderPicker: 'native',
+ /** Host files are read through the Electron bridge, not the gateway's REST routes. */
+ nativeHostFiles: 'native',
+ /** Preferences are stored per serving origin (and per profile) in this tab. */
+ originScopedPrefs: 'browser',
+ /** The profile rail shows its squares (drag, hold-to-recolor) instead of always condensing. */
+ profileRailSquares: 'native',
+ /** A failed terminal spawn arms a retry (the shell runs on the server). */
+ retryTerminalSpawn: 'browser',
+ /** The roster names profiles this one gateway does not serve. */
+ servedProfileRoster: 'browser',
+ /** The connection is the serving origin's, and its primary is the profile it launched as. */
+ servingOriginConnection: 'browser',
+ /** Code fences size to their longest line and scroll sideways inside the block. */
+ sidewaysCodeFences: 'browser',
+ /** The tab title mirrors session status. */
+ tabTitleStatus: 'browser',
+ /** The startup profile is the tab's own `?profile=`, so every pick is remembered. */
+ tabStartupProfile: 'browser',
+ /** A tap outside a revealed narrow overlay closes it. */
+ tapOutsideDismiss: 'browser',
+ /** Controls and the titlebar grow to touch size (44px). */
+ touchSizedControls: 'browser',
+ /** A session token may ride a URL (plugin socket, file download link). */
+ urlTokenAuth: 'native',
+ /** This machine can serve the Webapp (Settings → Web access). */
+ webAccessHost: 'native',
+ /** User-facing copy names the Webapp. */
+ webappCopy: 'browser',
+ /** The preview pane can mount an Electron `<webview>`; otherwise it uses an iframe. */
+ webviewPreview: 'native',
+ /** The window has a native material and opacity surface (glass, translucency). */
+ windowMaterial: 'native'
+} as const satisfies Record<string, Host>)
+
+export type HostCapability = keyof typeof HOST_CAPABILITIES
+
+export function hostHas(capability: HostCapability): boolean {
+ return (HOST_CAPABILITIES[capability] === 'browser') === isBrowserHostedDesktop()
+}