Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
43.1 KB
Raw Blame
import { BrowserWindow, WebContentsView, screen, session } from 'electron'
import path from 'node:path'
import { getActiveEnvKey } from './config.js'
import { createSandboxFindResultGate } from './sandboxFindSession.js'
import { extractSandboxUiViewRoute, normalizeSandboxUiRoute } from './sandboxUiDeepLinks.js'
import { touchSandboxUiPartition } from './sandboxUiPartitionGc.js'
import {
  applySandboxUiNavigationPolicies,
  applySandboxUiPartitionPolicies,
  isSandboxUiNavigationWithinPrefix as isNavigationWithinPrefix,
} from './sandboxUiPartitionPolicies.js'
import { wireDesktopShortcutRouting } from './shortcutRouter.js'
import type { SandboxUiReleaseReason, SandboxUiReleasedEvent, SandboxUiRoute } from './types.js'

export type { SandboxUiReleaseReason, SandboxUiReleasedEvent, SandboxUiRoute }

/**
 * Sandbox UI embed driver. Owns the lifecycle of the single active
 * `WebContentsView` that hosts a recipe's sandbox UI inside the main
 * desktop window.
 *
 * One-at-a-time embed: the driver is a singleton. Mounting recipe B while A
 * is up tears down A first; A's per-recipe Electron partition is left intact
 * so a quick A → B → A round-trip doesn't lose cookies/storage (the launch-
 * time GC pass handles eventual eviction).
 *
 * Cookie installation: the rpc-proxy session-mint runs in the main process
 * (via `RpcProxyClient.mintSandboxUiSession`). Its raw Set-Cookie value is
 * parsed and written into the partition's session BEFORE the first `view/*`
 * navigation, so the cookie is on the very first request. The proxy also
 * validates the cookie's recipeNs/recipeName claim against the URL path on
 * every hit, so a partition that ended up with a cookie minted for a
 * different recipe still gets rejected with 401 by rpc-proxy — the JWT
 * claim binding is the second line of defence.
 *
 * Hardened webPreferences:
 *   nodeIntegration:false  — no Node API exposed to embed JS
 *   contextIsolation:true  — preload runs in its own world
 *   sandbox:true           — Chromium sandbox (OS-level)
 *   webSecurity:true       — same-origin policy enforced
 *   no `remote`            — Electron's deprecated remote module never on
 */

export const SANDBOX_UI_COOKIE_NAME = 'clerum_sandbox_ui_session'
const CLIENT_ROUTE_HANDOFF_TIMEOUT_MS = 30_000

export type SandboxUiBounds = {
  x: number
  y: number
  width: number
  height: number
  dpr?: number
}

export type SandboxUiFindResult = {
  requestId: number
  activeMatchOrdinal: number
  matches: number
  finalUpdate: boolean
}

export type SandboxUiFindOperation = 'start' | 'next' | 'previous'

export type SandboxUiFindStartResult =
  | { status: 'started'; requestId: number }
  | { status: 'unavailable'; reason: 'no-active-view' | 'document-loading' | 'no-session' }

export function sandboxFindOptionsForOperation(operation: SandboxUiFindOperation): {
  forward: boolean
  findNext: boolean
} {
  return operation === 'start'
    ? { forward: true, findNext: true }
    : { forward: operation === 'next', findNext: false }
}

function toViewBounds(
  bounds: SandboxUiBounds,
  parentWindow: BrowserWindow
): { x: number; y: number; width: number; height: number } {
  // Renderer's CSS pixels and macOS points diverge when the user is on a
  // scaled display (e.g. "Larger Text" mode reports devicePixelRatio=2.4
  // to the renderer while the screen's scaleFactor stays at 2.0).
  // WebContentsView.setBounds expects points, so multiply by dpr/scaleFactor
  // — a no-op when they match (the common 1× / 2× case).
  const sf = screen.getDisplayMatching(parentWindow.getBounds()).scaleFactor
  const dpr = bounds.dpr ?? sf
  if (Math.abs(dpr - sf) < 0.01) {
    return { x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height }
  }
  const factor = dpr / sf
  return {
    x: Math.round(bounds.x * factor),
    y: Math.round(bounds.y * factor),
    width: Math.round(bounds.width * factor),
    height: Math.round(bounds.height * factor),
  }
}

export type MountSandboxUiArgs = {
  /** Names this mount in every event about the view it creates. */
  launchId: string
  recipeNs: string
  recipeName: string
  setCookie: string
  rpcProxyUrl: string
  defaultPath?: string
  parentWindow: BrowserWindow
  bounds: SandboxUiBounds
  routePath?: string
  /** Main-side cleanup for a teardown nobody asked for (crash, parent closed). */
  onClosed?: () => void
  /**
   * Fired exactly once when this mount's view is torn down, for any reason,
   * including a teardown that fails half-way. Only a mount that got as far as
   * making its view the active one fires it: a view created but not yet active
   * (a step between its construction and its activation threw) never does.
   */
  onReleased?: (event: SandboxUiReleasedEvent) => void
  /**
   * Fired when the embedded document's `<title>` changes (`page-title-updated`).
   * The driver only forwards the plugin-controlled title; the renderer decides
   * whether to surface it (its app tab title) and trims/ignores empty values.
   * Read-only: it never grants the embed any privilege.
   */
  onTitleChanged?: (title: string) => void
  /**
   * Spec §9.9 — recipe-author Connect button affordance. Fired when the
   * embed navigates to `clerum://oauth?clientId=…`. The driver's only
   * job is to forward; the AppService method this points at calls
   * rpc-proxy for the provider authorize URL and `shell.openExternal`s it.
   */
  onOauthAuthorize?: (oauthClientId: string, background: boolean) => void
  /**
   * Fired when the embed navigates to `gfs://<drive>/<resource>` — a plugin
   * rendering a link to a shared file. The driver only forwards; the host
   * resolves the URI with the USER's session and shows it in the Desktop's own
   * viewer, so a click reveals nothing to the plugin.
   */
  onGfsOpen?: (uri: string) => void
  /**
   * Fired when a main-frame navigation inside the app's `view/` prefix
   * commits with HTTP 401 — the session cookie was rejected and the page left
   * behind has no script that could ask for a refresh. Lives as long as the
   * view, unlike the one-shot client-route handoff listener.
   */
  onUnauthorizedNavigation?: (webContentsId: number) => void
  /**
   * Re-checked at every await before a session effect (cookie write, view
   * creation). False means the caller's authenticated session ended while this
   * mount was in flight, so it must not attach anything for it.
   */
  isCurrent?: () => boolean
}

type ActiveView = {
  launchId: string
  view: WebContentsView
  onReleased?: (event: SandboxUiReleasedEvent) => void
  recipeNs: string
  recipeName: string
  defaultPath: string
  partition: string
  parentWindow: BrowserWindow
  rpcProxyOrigin: string
  cleanupClientRouteHandoff?: () => void
  cleanupParentClosed?: () => void
  cleanupRenderProcessGone?: () => void
  cleanupShortcutRouting?: () => void
  cleanupDocumentLifecycle?: () => void
  cleanupFindResults?: () => void
  /** The route the open asked for, as `representedSandboxUiLocation` reports it. */
  requestedRoute: SandboxUiRoute
  /**
   * False while the document cannot yet stand for the requested route: it has
   * not loaded, or the route handoff is pending or failed with no navigation
   * since. Once true it stays true: a reload keeps the committed URL.
   */
  routeSettled: boolean
  documentGeneration: number
  documentReady: boolean
  findSession?: {
    query: string
    clientRequestId: number
    documentGeneration: number
    nativeRequestId: number
    complete: boolean
  }
}

let active: ActiveView | null = null
let mountGeneration = 0

export const isSandboxUiNavigationWithinPrefix = isNavigationWithinPrefix

export function getActiveSandboxUi(): {
  launchId: string
  recipeNs: string
  recipeName: string
  appRef: string
  webContentsId: number
} | null {
  if (!active) return null
  return {
    launchId: active.launchId,
    recipeNs: active.recipeNs,
    recipeName: active.recipeName,
    appRef: `${active.recipeNs}/${active.recipeName}`,
    webContentsId: active.view.webContents.id,
  }
}

export function getActiveSandboxUiLocation(): {
  recipeNs: string
  recipeName: string
  path?: string
} | null {
  if (!active) return null
  if (active.view.webContents.isDestroyed()) return null
  const { routePath } = representedSandboxUiLocation(active)
  return {
    recipeNs: active.recipeNs,
    recipeName: active.recipeName,
    ...(routePath ? { path: routePath } : {}),
  }
}

/**
 * The single reader of the route a view stands for. Until the document can
 * represent the requested route, the live URL is empty or the default route,
 * and reporting it would overwrite the route the user is on with a wrong one.
 * Throws when the live URL is outside the app; each caller decides what that
 * means for it.
 */
function representedSandboxUiLocation(view: ActiveView): SandboxUiRoute {
  if (!view.routeSettled) return { ...view.requestedRoute }
  const routePath = resolveSandboxUiSharePath({
    currentUrl: view.view.webContents.getURL(),
    rpcProxyOrigin: view.rpcProxyOrigin,
    recipeNs: view.recipeNs,
    recipeName: view.recipeName,
    defaultPath: view.defaultPath,
  })
  return routePath ? { routePath } : {}
}

export function resolveSandboxUiSharePath(input: {
  currentUrl: string
  rpcProxyOrigin: string
  recipeNs: string
  recipeName: string
  defaultPath: string
}): string | undefined {
  if (!input.currentUrl.trim()) return undefined
  const currentPath = extractSandboxUiViewRoute(input)
  if (currentPath === null) throw new Error('Cannot read the current app route')
  return currentPath === sharedPathForDefaultPath(input.defaultPath) ? undefined : currentPath
}

export function partitionFor(envKey: string, recipeNs: string, recipeName: string): string {
  // Per-(environment, recipe) partition — Chromium isolates storage (cookies,
  // IndexedDB, localStorage, service workers) by partition. `envKey` (spec §5.2)
  // scopes it so the same recipe ns/name in two clusters never shares KasmVNC
  // cookies/storage. The launch-time GC pass walks the current env's
  // `persist:sandbox-ui-${envKey}-*` partitions and wipes the ones the user no
  // longer has ACL for; other environments' partitions are left untouched.
  return `persist:sandbox-ui-${envKey}-${recipeNs}-${recipeName}`
}

/**
 * Pull the cookie value out of a Set-Cookie header. Accepts either a
 * single value or an array (Node's `getSetCookie()` API). Returns null
 * when the named cookie is absent or the header is malformed.
 */
export function extractSandboxUiCookie(
  setCookie: string | string[],
  name: string = SANDBOX_UI_COOKIE_NAME
): string | null {
  const list = Array.isArray(setCookie) ? setCookie : [setCookie]
  const prefix = `${name}=`
  for (const header of list) {
    if (header.startsWith(prefix)) {
      const rest = header.slice(prefix.length)
      const end = rest.indexOf(';')
      return end === -1 ? rest : rest.slice(0, end)
    }
  }
  return null
}

/**
 * Pull the Path attribute out of a Set-Cookie header. Falls back to
 * '/api/v1/sandbox-ui/<ns>/<name>/' if the header omits it (rpc-proxy
 * always sets it, but we never want to install a cookie at a wider path
 * than the one the server intended).
 */
export function extractSandboxUiPath(
  setCookie: string | string[],
  recipeNs: string,
  recipeName: string
): string {
  const list = Array.isArray(setCookie) ? setCookie : [setCookie]
  for (const header of list) {
    const match = /;\s*Path=([^;]+)/i.exec(header)
    const captured = match?.[1]
    if (captured) return captured.trim()
  }
  return `/api/v1/sandbox-ui/${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/`
}

/**
 * Write a session cookie into the per-recipe Electron partition. Used both
 * at mount-time (initial cookie) and at refresh-time (rotated cookie). The
 * cookie is keyed on `(name, path)` so calling this with a fresh value at
 * the same Path replaces the existing entry — the embed sees the new JWT
 * on its next request without any `view/*` reload.
 */
async function writeSandboxUiCookie(args: {
  rpcProxyOrigin: string
  recipeNs: string
  recipeName: string
  setCookie: string | string[]
  partition: string
}): Promise<void> {
  const { rpcProxyOrigin, recipeNs, recipeName, setCookie, partition } = args
  const cookieValue = extractSandboxUiCookie(setCookie)
  if (!cookieValue) {
    throw new Error(`session response did not include ${SANDBOX_UI_COOKIE_NAME} cookie`)
  }
  const cookiePath = extractSandboxUiPath(setCookie, recipeNs, recipeName)
  const ses = session.fromPartition(partition)
  await ses.cookies.set({
    url: `${rpcProxyOrigin}${cookiePath}`,
    name: SANDBOX_UI_COOKIE_NAME,
    value: cookieValue,
    path: cookiePath,
    httpOnly: true,
    sameSite: 'strict',
    // Mirror the proxy's Secure attribute when it's serving https.
    secure: rpcProxyOrigin.startsWith('https:'),
  })
}

/**
 * Undo `writeSandboxUiCookie`: removes the cookie it would set for the same
 * arguments. Removal matches by name and by the URL the cookie is sent to, so
 * it also clears an older value left at that Path by a previous mount.
 */
async function removeSandboxUiCookie(args: {
  rpcProxyOrigin: string
  recipeNs: string
  recipeName: string
  setCookie: string | string[]
  partition: string
}): Promise<void> {
  const { rpcProxyOrigin, recipeNs, recipeName, setCookie, partition } = args
  const cookiePath = extractSandboxUiPath(setCookie, recipeNs, recipeName)
  await session
    .fromPartition(partition)
    .cookies.remove(`${rpcProxyOrigin}${cookiePath}`, SANDBOX_UI_COOKIE_NAME)
}

/**
 * Refresh the active partition's session cookie. No-op when nothing is
 * mounted (refresh can race with teardown). Throws on a missing cookie
 * value or a partition write error so the caller can surface a refresh
 * failure to the user.
 */
export async function installSandboxUiCookie(setCookie: string | string[]): Promise<void> {
  if (!active) return
  const expectedPath =
    `/api/v1/sandbox-ui/${encodeURIComponent(active.recipeNs)}/` +
    `${encodeURIComponent(active.recipeName)}/`
  const cookiePath = extractSandboxUiPath(setCookie, active.recipeNs, active.recipeName)
  if (cookiePath !== expectedPath) {
    throw new Error(`sandbox-ui refresh cookie path ${cookiePath} does not match the active recipe`)
  }
  await writeSandboxUiCookie({
    rpcProxyOrigin: active.rpcProxyOrigin,
    recipeNs: active.recipeNs,
    recipeName: active.recipeName,
    setCookie,
    partition: active.partition,
  })
}

function readReleasedLocation(
  view: ActiveView,
  reason: SandboxUiReleaseReason
): SandboxUiRoute | null {
  if (reason === 'crashed') return null
  try {
    return representedSandboxUiLocation(view)
  } catch (err) {
    console.warn('[SandboxUI] could not read the route of a view being torn down:', err)
    return null
  }
}

function runTeardownStep(step: string, reason: SandboxUiReleaseReason, run: () => void): void {
  try {
    run()
  } catch (err) {
    console.error(`[SandboxUI] teardown step ${step} failed:`, err, 'reason:', reason)
  }
}

/**
 * Synchronous on purpose: the release event must leave before anything else
 * can run, so a caller that rejects after a teardown always reports the release
 * first. Every step is isolated; a failing listener unhook must not leave the
 * view attached, alive or unreported.
 */
function teardownActive(reason: SandboxUiReleaseReason): void {
  if (!active) return
  const current = active
  active = null
  const location = readReleasedLocation(current, reason)
  const webContents = current.view.webContents
  try {
    runTeardownStep('cleanupClientRouteHandoff', reason, () =>
      current.cleanupClientRouteHandoff?.()
    )
    runTeardownStep('cleanupParentClosed', reason, () => current.cleanupParentClosed?.())
    runTeardownStep('cleanupRenderProcessGone', reason, () => current.cleanupRenderProcessGone?.())
    runTeardownStep('cleanupShortcutRouting', reason, () => current.cleanupShortcutRouting?.())
    runTeardownStep('cleanupDocumentLifecycle', reason, () => current.cleanupDocumentLifecycle?.())
    runTeardownStep('cleanupFindResults', reason, () => current.cleanupFindResults?.())
    runTeardownStep('stopFindInPage', reason, () => {
      if (!webContents.isDestroyed()) webContents.stopFindInPage('clearSelection')
    })
  } finally {
    // Every step above is guarded today; the finally keeps detach, close and
    // release unconditional if a step is ever added without its guard.
    // removeChildView both detaches the view from layout and severs the
    // parent's ownership ref.
    runTeardownStep('removeChildView', reason, () => {
      if (!current.parentWindow.isDestroyed()) {
        current.parentWindow.contentView.removeChildView(current.view)
      }
    })
    // Closing the webContents stops loading and frees the renderer process.
    runTeardownStep('closeWebContents', reason, () => {
      if (!webContents.isDestroyed()) webContents.close()
    })
    runTeardownStep('onReleased', reason, () =>
      current.onReleased?.({ launchId: current.launchId, reason, location })
    )
    runTeardownStep('verifyDetached', reason, () => {
      if (
        !current.parentWindow.isDestroyed() &&
        current.parentWindow.contentView.children.includes(current.view)
      ) {
        console.error('[SandboxUI] a torn-down view is still attached to its window')
      }
    })
  }
}

export async function mountSandboxUiView(args: MountSandboxUiArgs): Promise<void> {
  const {
    launchId,
    recipeNs,
    recipeName,
    setCookie,
    rpcProxyUrl,
    defaultPath,
    parentWindow,
    bounds,
    routePath,
    onClosed,
    onReleased,
    onTitleChanged,
    isCurrent = () => true,
  } = args

  if (parentWindow.isDestroyed()) {
    throw new Error('parent window is destroyed')
  }
  if (!recipeNs.trim() || !recipeName.trim()) {
    throw new Error('recipeNs and recipeName are required')
  }

  // Publish intent before the first await. A newer mount or unmount invalidates
  // this operation while cookie installation is in flight, preventing an older
  // request from attaching a view after the user has moved on.
  const generation = ++mountGeneration

  // Tear down any existing view before mounting (one-at-a-time embed). The
  // per-recipe partition is left in place so storage survives a re-mount
  // within the ACL window.
  // AppService already tore down before minting; this covers callers that
  // mount through the driver without that queue.
  teardownActive('replaced')
  if (generation !== mountGeneration || !isCurrent()) return

  const partition = partitionFor(getActiveEnvKey(), recipeNs, recipeName)
  const proxyOriginUrl = new URL(rpcProxyUrl).toString().replace(/\/+$/, '')
  const viewPath = resolveSandboxUiDefaultPath(defaultPath)
  const clientRoutePath = normalizeSandboxUiRoute(routePath || '')
  const sharedViewPath = sharedPathForDefaultPath(viewPath)
  const needsClientRouteHandoff = Boolean(clientRoutePath && clientRoutePath !== sharedViewPath)
  const requestedRoute: SandboxUiRoute =
    needsClientRouteHandoff && clientRoutePath ? { routePath: clientRoutePath } : {}
  const allowedNavigationPrefix =
    `${proxyOriginUrl}/api/v1/sandbox-ui/` +
    `${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view`

  // Install the session cookie BEFORE creating the view so the very first
  // navigation request carries it. The proxy enforces the recipe binding
  // claim on every request — installing on a stale partition would still
  // fail closed at rpc-proxy.
  const cookieArgs = { rpcProxyOrigin: proxyOriginUrl, recipeNs, recipeName, setCookie, partition }
  await writeSandboxUiCookie(cookieArgs)
  if (generation !== mountGeneration) return
  if (!isCurrent()) {
    // The partition is keyed per recipe, not per user, and a session change
    // does not clear it: the cookie just written would outlive the session
    // that minted it. Only when this mount is still the newest one — a newer
    // mount may already have written its own cookie at the same Path.
    await removeSandboxUiCookie(cookieArgs).catch(err => {
      console.warn('[SandboxUI] could not remove a stale session cookie:', err)
    })
    return
  }
  if (parentWindow.isDestroyed()) {
    throw new Error('parent window is destroyed')
  }

  // Apply default-deny permission + download policy on the partition's
  // Session before the view is constructed so the very first navigation
  // already runs under those rules.
  const ses = session.fromPartition(partition)
  applySandboxUiPartitionPolicies(ses)

  const view = new WebContentsView({
    webPreferences: {
      partition,
      // The embed preload exposes `clerum.requestSessionRefresh()` so an
      // embed can recover from an SSE 401 between scheduled refreshes. The
      // handler in main process gates the call by the IPC pinning map +
      // 30 s rate-limit.
      preload: path.join(__dirname, 'sandboxUiEmbedPreload.js'),
      nodeIntegration: false,
      contextIsolation: true,
      sandbox: true,
      webSecurity: true,
      // Defence-in-depth — no spell-check / no auto form-fill is required,
      // but Electron defaults already disable those for sandboxed
      // partitions. Audit if upgrading Electron majors.
    },
  })

  view.setBounds(toViewBounds(bounds, parentWindow))

  // Pin top-level navigation to this recipe's `view/*` prefix; everything
  // else (links to other origins, target=_blank, window.open) goes to the
  // OS browser or is dropped. `clerum://oauth?clientId=…` is intercepted
  // and handed back to the AppService.
  applySandboxUiNavigationPolicies(view.webContents, allowedNavigationPrefix, {
    onOauthAuthorize: (oauthClientId, background) => {
      args.onOauthAuthorize?.(oauthClientId, background)
    },
    onGfsOpen: uri => {
      args.onGfsOpen?.(uri)
    },
  })

  // `onClosed` reports a teardown nobody asked for: the parent window closed
  // or the embed's renderer died. Solicited teardowns (`unmountSandboxUiView`,
  // a replacing mount) stay silent — the caller already ran its own cleanup.
  // The renderer learns of every teardown from `onReleased` instead.
  const onParentClosed = (): void => {
    teardownActive('parent_closed')
    onClosed?.()
  }
  parentWindow.once('closed', onParentClosed)
  const cleanupParentClosed = (): void => {
    parentWindow.removeListener('closed', onParentClosed)
  }
  // A dead renderer leaves its last frame painted over the app with nothing
  // behind it, whatever the reason. The identity check keeps a late signal
  // from a view that was already replaced from tearing down its successor.
  // `mountGeneration` is deliberately left alone: bumping it would abort an
  // unrelated mount that is in flight.
  const onRenderProcessGone = (): void => {
    if (active?.view !== view) return
    teardownActive('crashed')
    onClosed?.()
  }
  view.webContents.on('render-process-gone', onRenderProcessGone)
  const cleanupRenderProcessGone = (): void => {
    view.webContents.removeListener('render-process-gone', onRenderProcessGone)
  }

  active = {
    launchId,
    view,
    onReleased,
    recipeNs,
    recipeName,
    defaultPath: viewPath,
    partition,
    parentWindow,
    rpcProxyOrigin: proxyOriginUrl,
    cleanupParentClosed,
    cleanupRenderProcessGone,
    requestedRoute,
    routeSettled: false,
    documentGeneration: 0,
    documentReady: false,
  }

  const invalidateFindForNavigation = (requiresDocumentLoad: boolean): void => {
    if (!active || active.view !== view) return
    active.documentGeneration += 1
    if (requiresDocumentLoad) active.documentReady = false
    stopActiveSandboxUiFind()
  }
  const onDidStartNavigation = (
    _event: Electron.Event,
    _url: string,
    isInPlace: boolean,
    isMainFrame: boolean
  ): void => {
    if (isMainFrame) invalidateFindForNavigation(!isInPlace)
  }
  let documentLoaded = false
  // Cleared by the handoff when it applies the route, fails, times out or is
  // abandoned.
  let clientRouteHandoffPending = needsClientRouteHandoff
  let lastMainFrameUrl = ''
  const onDocumentReady = (): void => {
    if (active?.view !== view) return
    documentLoaded = true
    active.documentReady = true
    if (!needsClientRouteHandoff) active.routeSettled = true
  }
  // A navigation inside the loaded document is the user's (or the app's) own:
  // from then on the live URL is the route, whatever became of the handoff.
  const onDidNavigateInPage = (_event: Electron.Event, url: string, isMainFrame: boolean): void => {
    if (active?.view !== view || !isMainFrame) return
    // A router can move the URL before the first load; a later reload commits
    // that URL and must still read as a reload.
    lastMainFrameUrl = url
    if (documentLoaded) active.routeSettled = true
  }
  // Forward the embed's live `document.title` so the renderer can name its app
  // tab after it (mirrors the URL-report pattern). The title is plugin content,
  // so it stays read-only — the renderer trims/ignores empty values.
  const onPageTitleUpdated = (_event: Electron.Event, title: string): void => {
    if (active?.view === view) onTitleChanged?.(title)
  }
  // `did-navigate` only fires for the main frame.
  const onDocumentNavigated = (
    _event: Electron.Event,
    navigatedUrl: string,
    httpResponseCode: number
  ): void => {
    if (active?.view !== view) return
    const previousUrl = lastMainFrameUrl
    lastMainFrameUrl = navigatedUrl
    const withinApp = isSandboxUiNavigationWithinPrefix(navigatedUrl, allowedNavigationPrefix)
    // With no requested route there is nothing a boot rewrite could overwrite,
    // so the first document committed inside the app is already the live
    // route; waiting for the load would drop where the user goes meanwhile.
    // Otherwise, a new document the user reached after the handoff gave up (a
    // multi-page app) is the live route. A reload commits the same URL and the
    // commits a pending handoff is still waiting through are not the user's:
    // neither may replace the requested route.
    if (
      withinApp &&
      (!needsClientRouteHandoff ||
        (documentLoaded && !clientRouteHandoffPending && navigatedUrl !== previousUrl))
    ) {
      active.routeSettled = true
    }
    if (httpResponseCode !== 401 || !withinApp) return
    args.onUnauthorizedNavigation?.(view.webContents.id)
  }
  view.webContents.on('did-start-navigation', onDidStartNavigation)
  view.webContents.on('did-finish-load', onDocumentReady)
  view.webContents.on('did-navigate-in-page', onDidNavigateInPage)
  view.webContents.on('page-title-updated', onPageTitleUpdated)
  view.webContents.on('did-navigate', onDocumentNavigated)
  active.cleanupDocumentLifecycle = () => {
    view.webContents.removeListener('did-start-navigation', onDidStartNavigation)
    view.webContents.removeListener('did-finish-load', onDocumentReady)
    view.webContents.removeListener('did-navigate-in-page', onDidNavigateInPage)
    view.webContents.removeListener('page-title-updated', onPageTitleUpdated)
    view.webContents.removeListener('did-navigate', onDocumentNavigated)
  }

  active.cleanupShortcutRouting = wireDesktopShortcutRouting({
    source: 'sandbox',
    sourceWebContents: view.webContents,
    trustedRenderer: parentWindow.webContents,
    isCurrentSource: () => active?.view.webContents.id === view.webContents.id,
  })

  parentWindow.contentView.addChildView(view)
  // Re-apply bounds after attach. On macOS at fractional DPR (e.g. 2.4 on a
  // "More Space" scaled display), setBounds called pre-attach lands the view
  // in a slightly offset coordinate system; re-applying after addChildView
  // forces it into the parent's now-resolved coords.
  view.setBounds(toViewBounds(bounds, parentWindow))

  // Record the mount as the partition's most recent access so the next
  // launch's LRU GC has fresh data. Fire-and-forget; a write failure is
  // logged inside the GC module and must not block the mount.
  void touchSandboxUiPartition(`${recipeNs}/${recipeName}`).catch(err => {
    console.warn('[SandboxUI] touchSandboxUiPartition failed:', err)
  })

  const url =
    `${proxyOriginUrl}/api/v1/sandbox-ui/` +
    `${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view${encodeSandboxUiDefaultPath(
      viewPath
    )}`
  if (needsClientRouteHandoff && clientRoutePath) {
    const encodedClientRoutePath = encodeSandboxUiRoutePath(clientRoutePath)
    const clientRouteUrl =
      `${proxyOriginUrl}/api/v1/sandbox-ui/` +
      `${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/view${encodedClientRoutePath}`
    let lastNavigation = { url: '', status: 0 }
    let handoffFinished = false
    let handoffTimeout: NodeJS.Timeout | null = null
    const cleanupClientRouteHandoff = () => {
      if (handoffFinished) return
      handoffFinished = true
      clientRouteHandoffPending = false
      if (handoffTimeout) clearTimeout(handoffTimeout)
      view.webContents.removeListener('did-navigate', onDidNavigate)
      view.webContents.removeListener('did-finish-load', onDidFinishLoad)
    }
    const onDidNavigate = (
      _event: Electron.Event,
      navigatedUrl: string,
      httpResponseCode: number
    ) => {
      lastNavigation = { url: navigatedUrl, status: httpResponseCode }
    }
    const onDidFinishLoad = () => {
      if (!active || active.view !== view || view.webContents.isDestroyed()) {
        cleanupClientRouteHandoff()
        return
      }
      if (
        !canApplySandboxUiClientRoute({
          allowedNavigationPrefix,
          currentUrl: view.webContents.getURL(),
          navigatedUrl: lastNavigation.url,
          httpResponseCode: lastNavigation.status,
        })
      ) {
        if (
          lastNavigation.status >= 200 &&
          lastNavigation.status < 400 &&
          !isSandboxUiNavigationWithinPrefix(view.webContents.getURL(), allowedNavigationPrefix)
        ) {
          console.warn(
            '[SandboxUI] client route handoff abandoned after navigation left the app prefix:',
            view.webContents.getURL()
          )
          cleanupClientRouteHandoff()
        }
        return
      }
      void applySandboxUiClientRoute(view.webContents, clientRouteUrl)
        .then(applied => {
          if (applied && active?.view === view) active.routeSettled = true
          if (!applied) {
            console.warn('[SandboxUI] client route handoff did not update the app URL')
          }
          cleanupClientRouteHandoff()
        })
        .catch(err => {
          console.warn('[SandboxUI] client route handoff failed:', err)
          cleanupClientRouteHandoff()
        })
    }
    view.webContents.on('did-navigate', onDidNavigate)
    view.webContents.on('did-finish-load', onDidFinishLoad)
    handoffTimeout = setTimeout(() => {
      console.warn('[SandboxUI] client route handoff timed out before the app became ready')
      cleanupClientRouteHandoff()
    }, CLIENT_ROUTE_HANDOFF_TIMEOUT_MS)
    if (active && active.view === view) {
      active.cleanupClientRouteHandoff = cleanupClientRouteHandoff
    }
  }
  // Drop the HTTP cache on every open so a stale entry from a prior
  // broken pod can't keep painting after the recipe is healthy. The
  // partition is persistent (cookies, IndexedDB, localStorage all
  // survive), only `Cache` is wiped — clearStorageData would also
  // nuke the session cookie and break auth on the very next request.
  // Fire-and-forget; loadURL re-issues unconditional GETs once the
  // cache directory is gone.
  void session
    .fromPartition(partition)
    .clearCache()
    .catch(err => {
      console.warn('[SandboxUI] clearCache failed:', err)
    })
  // No await — the load runs concurrently with the renderer animation.
  // The view is already attached + has bounds, so the user sees the URL
  // resolve into the embed naturally.
  void view.webContents.loadURL(url)
}

export async function applySandboxUiClientRoute(
  webContents: Pick<WebContentsView['webContents'], 'executeJavaScript' | 'isDestroyed'>,
  targetUrl: string
): Promise<boolean> {
  if (webContents.isDestroyed()) return false
  const serializedTarget = JSON.stringify(targetUrl)
  return Boolean(
    await webContents.executeJavaScript(`(() => {
      const targetUrl = new URL(${serializedTarget}).href;
      const previousUrl = window.location.href;
      if (new URL(previousUrl).href === targetUrl) return true;
      window.history.replaceState(window.history.state, '', targetUrl);
      window.dispatchEvent(new PopStateEvent('popstate', { state: window.history.state }));
      return new URL(window.location.href).href === targetUrl;
    })()`)
  )
}

export function resolveSandboxUiDefaultPath(defaultPath?: string): string {
  const rawDefaultPath = String(defaultPath || '')
  if (!rawDefaultPath.trim()) return '/'
  const normalized = normalizeSandboxUiDefaultPath(rawDefaultPath)
  if (normalized) return normalized
  console.warn('[SandboxUI] Invalid recipe defaultPath; falling back to "/":', rawDefaultPath)
  return '/'
}

function encodeSandboxUiRoutePath(routePath: string): string {
  return routePath
    .split('/')
    .map((segment, index) => (index === 0 ? '' : encodeURIComponent(segment)))
    .join('/')
}

function firstDefaultPathMetaIndex(defaultPath: string): number | undefined {
  const firstQueryIndex = defaultPath.indexOf('?')
  const firstHashIndex = defaultPath.indexOf('#')
  return [firstQueryIndex, firstHashIndex].filter(index => index !== -1).sort((a, b) => a - b)[0]
}

function sharedPathForDefaultPath(defaultPath: string): string {
  const firstMetaIndex = firstDefaultPathMetaIndex(defaultPath)
  const pathname = firstMetaIndex === undefined ? defaultPath : defaultPath.slice(0, firstMetaIndex)
  return normalizeSandboxUiRoute(pathname || '/') || '/'
}

function normalizeSandboxUiDefaultMetadata(metadata: string): string | null {
  const hashIndex = metadata.indexOf('#')
  if (hashIndex === -1) return metadata
  const hashRouteStart = hashIndex + 1
  const hashRemainder = metadata.slice(hashRouteStart)
  const hashQueryIndex = hashRemainder.indexOf('?')
  const hashRoute = hashQueryIndex === -1 ? hashRemainder : hashRemainder.slice(0, hashQueryIndex)
  if (!hashRoute.startsWith('/')) return metadata
  const normalizedHashRoute = normalizeSandboxUiRoute(hashRoute)
  if (!normalizedHashRoute) return null
  return (
    metadata.slice(0, hashRouteStart) +
    normalizedHashRoute +
    (hashQueryIndex === -1 ? '' : hashRemainder.slice(hashQueryIndex))
  )
}

function encodeSandboxUiDefaultMetadata(metadata: string): string {
  const hashIndex = metadata.indexOf('#')
  if (hashIndex === -1) return metadata
  const hashRouteStart = hashIndex + 1
  const hashRemainder = metadata.slice(hashRouteStart)
  const hashQueryIndex = hashRemainder.indexOf('?')
  const hashRoute = hashQueryIndex === -1 ? hashRemainder : hashRemainder.slice(0, hashQueryIndex)
  if (!hashRoute.startsWith('/')) return metadata
  return (
    metadata.slice(0, hashRouteStart) +
    encodeSandboxUiRoutePath(hashRoute) +
    (hashQueryIndex === -1 ? '' : hashRemainder.slice(hashQueryIndex))
  )
}

function encodeSandboxUiDefaultPath(defaultPath: string): string {
  const firstMetaIndex = firstDefaultPathMetaIndex(defaultPath)
  const pathname = firstMetaIndex === undefined ? defaultPath : defaultPath.slice(0, firstMetaIndex)
  const metadata = firstMetaIndex === undefined ? '' : defaultPath.slice(firstMetaIndex)
  return `${encodeSandboxUiRoutePath(pathname || '/')}${encodeSandboxUiDefaultMetadata(metadata)}`
}

function normalizeSandboxUiDefaultPath(rawPath: string): string | null {
  const routePath = String(rawPath || '')
  if (!routePath.trim()) return '/'
  if (
    routePath.length > 4096 ||
    routePath.includes('\\') ||
    /[\u0000-\u001f\u007f\u2028\u2029]/.test(routePath)
  ) {
    return null
  }
  const firstMetaIndex = firstDefaultPathMetaIndex(routePath)
  const pathname = firstMetaIndex === undefined ? routePath : routePath.slice(0, firstMetaIndex)
  const metadata = firstMetaIndex === undefined ? '' : routePath.slice(firstMetaIndex)
  const normalizedPathname = normalizeSandboxUiRoute(pathname || '/')
  if (!normalizedPathname) return null
  const normalizedMetadata = normalizeSandboxUiDefaultMetadata(metadata)
  if (normalizedMetadata === null) return null
  return `${normalizedPathname}${normalizedMetadata}`
}

export function canApplySandboxUiClientRoute(input: {
  allowedNavigationPrefix: string
  currentUrl: string
  navigatedUrl: string
  httpResponseCode: number
}): boolean {
  return (
    isSandboxUiNavigationWithinPrefix(input.currentUrl, input.allowedNavigationPrefix) &&
    isSandboxUiNavigationWithinPrefix(input.navigatedUrl, input.allowedNavigationPrefix) &&
    input.httpResponseCode >= 200 &&
    input.httpResponseCode < 400
  )
}

/**
 * Unmount the active view (no-op if nothing is mounted). Called on user
 * "Close" / navigate-away. Leaves the per-recipe partition intact so a
 * re-mount within the ACL window is fast.
 */
export async function unmountSandboxUiView(
  reason: SandboxUiReleaseReason = 'closed'
): Promise<void> {
  mountGeneration += 1
  teardownActive(reason)
}

/**
 * Move/resize the active view. The renderer fires this on resize / scroll /
 * sidebar-collapse so the embed visually tracks its slot div.
 */
export function setSandboxUiBounds(bounds: SandboxUiBounds): void {
  if (!active) return
  active.view.setBounds(toViewBounds(bounds, active.parentWindow))
}

/**
 * Hide the native WebContentsView while renderer-owned overlays are open.
 * WebContentsView always paints above the renderer DOM regardless of CSS
 * z-index, so visibility is the reliable way to let menus and toasts win.
 */
export function setSandboxUiVisible(visible: boolean): void {
  if (!active) return
  active.view.setVisible(visible)
}

type FindableSandboxWebContents = Pick<
  WebContentsView['webContents'],
  'findInPage' | 'on' | 'removeListener'
>

export function beginSandboxUiFind(
  webContents: FindableSandboxWebContents,
  query: string,
  options: { forward: boolean; findNext: boolean },
  onResult: (result: SandboxUiFindResult) => void,
  isCurrent: () => boolean = () => true
): { requestId: number; cleanup: () => void } {
  let requestId: number | null = null
  const pendingResults: Electron.FoundInPageResult[] = []
  const deliver = (result: Electron.FoundInPageResult) => {
    if (requestId === null) {
      pendingResults.push(result)
      return
    }
    if (!isCurrent() || result.requestId !== requestId) return
    onResult({
      requestId: result.requestId,
      activeMatchOrdinal: result.activeMatchOrdinal,
      matches: result.matches,
      finalUpdate: result.finalUpdate,
    })
  }
  const listener = (_event: Electron.Event, result: Electron.FoundInPageResult) => deliver(result)
  webContents.on('found-in-page', listener)
  requestId = webContents.findInPage(query, options)
  for (const result of pendingResults.splice(0)) deliver(result)
  return {
    requestId,
    cleanup: () => webContents.removeListener('found-in-page', listener),
  }
}

export function findInActiveSandboxUi(
  query: string,
  operation: SandboxUiFindOperation,
  clientRequestId: number,
  onResult: (result: SandboxUiFindResult) => void
): SandboxUiFindStartResult {
  if (!active || active.view.webContents.isDestroyed()) {
    return { status: 'unavailable', reason: 'no-active-view' }
  }
  const current = active
  if (!current.documentReady) {
    return { status: 'unavailable', reason: 'document-loading' }
  }
  const continuing = operation !== 'start'
  if (
    continuing &&
    (!current.findSession ||
      !current.findSession.complete ||
      current.findSession.query !== query ||
      current.findSession.clientRequestId !== clientRequestId ||
      current.findSession.documentGeneration !== current.documentGeneration)
  ) {
    return { status: 'unavailable', reason: 'no-session' }
  }
  const webContents = current.view.webContents
  current.cleanupFindResults?.()
  if (operation === 'start') webContents.stopFindInPage('clearSelection')
  const options = sandboxFindOptionsForOperation(operation)
  let completedSynchronously = false
  const documentGeneration = current.documentGeneration
  const resultGate = createSandboxFindResultGate(result => {
    if (result.finalUpdate && active === current) {
      completedSynchronously = true
      if (current.findSession?.nativeRequestId === result.requestId) {
        current.findSession.complete = true
      }
    }
    onResult(result)
  })
  const session = beginSandboxUiFind(
    webContents,
    query,
    options,
    resultGate.accept,
    () =>
      active === current &&
      current.documentReady &&
      documentGeneration === current.documentGeneration
  )
  current.cleanupFindResults = () => {
    resultGate.dispose()
    session.cleanup()
  }
  current.findSession = {
    query,
    clientRequestId,
    documentGeneration,
    nativeRequestId: session.requestId,
    complete: completedSynchronously,
  }
  return { status: 'started', requestId: session.requestId }
}

export function stopActiveSandboxUiFind(): void {
  if (!active) return
  active.cleanupFindResults?.()
  active.cleanupFindResults = undefined
  active.findSession = undefined
  if (!active.view.webContents.isDestroyed()) {
    active.view.webContents.stopFindInPage('clearSelection')
  }
}

export function focusActiveSandboxUi(): boolean {
  if (!active || active.view.webContents.isDestroyed()) return false
  active.view.webContents.focus()
  return true
}

export async function captureSandboxUiPreview(): Promise<string | null> {
  if (!active) return null
  if (active.view.webContents.isDestroyed()) return null
  const image = await active.view.webContents.capturePage()
  if (image.isEmpty()) return null
  return image.toDataURL()
}

/**
 * Hard-reload an embed's webContents in place. Pure + injectable so the
 * decision (skip a torn-down view, otherwise cache-busting reload) is unit
 * tested without Electron. Returns whether a reload was actually issued.
 *
 * `reloadIgnoringCache` is the browser "hard refresh": it re-issues the
 * navigation with no-cache request headers so freshly-arrived server data
 * (e.g. a new inbox item) is fetched instead of repainting a stale
 * HTTP-cached response — the same stale-pod concern the mount path guards
 * with `clearCache()`.
 */
export function reloadSandboxUiWebContents(
  webContents: { isDestroyed(): boolean; reloadIgnoringCache(): void } | null | undefined
): boolean {
  if (!webContents || webContents.isDestroyed()) return false
  webContents.reloadIgnoringCache()
  return true
}

/**
 * Reload the active embed in place, keeping its view, session and refresh loop.
 * Used by the user-facing Refresh of a healthy view and by the session refresh
 * once it has re-minted the cookie after the document came back 401. No-op when
 * nothing is mounted or the view was already torn down.
 */
export function reloadActiveSandboxUiView(): void {
  reloadSandboxUiWebContents(active?.view.webContents)
}

export type SandboxUiOauthCompletedPayload = {
  oauthClientId: string
  provider: string
}

/**
 * Spec §9.9 — push the OAuth completion envelope into the active embed.
 * Called by `main.ts`'s `open-url` handler after the provider redirect
 * lands in the OS browser, control-api stores the grant, and the success
 * page bounces to `clerum://oauth-completed`. The embed preload exposes
 * this as `clerum.onOauthCompleted(callback)` to recipe JS.
 *
 * No-op when no embed is mounted (deep-link arrives after the user closed
 * the embed). The recipe can re-trigger Connect if it cares.
 */
export function dispatchSandboxUiOauthCompleted(payload: SandboxUiOauthCompletedPayload): void {
  if (!active) return
  if (active.view.webContents.isDestroyed()) return
  active.view.webContents.send('clerum:sandbox-ui:oauth-completed', payload)
}