@followbin/dsh-selection 0.0.0-stage → 0.2.0

package/src/worker/native-window.mjs

@@ -0,0 +1,319 @@
+// Window behaviour @webviewjs/webview does not expose: no Dock icon, clicks that do not steal focus,
+// and a level above full-screen apps. System APIs are called through koffi, so nothing is compiled.
+// The Windows branch has not been run on real hardware yet.
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * Loads koffi's platform package directly. The `koffi` meta package runs an install script that
+ * DSH's pnpm refuses by default; the platform packages carry the same native API and no script.
+ */
+function loadKoffi() {
+  const name = `@koromix/koffi-${process.platform}-${process.arch}`
+  try {
+    return require(name)
+  } catch (error) {
+    throw new Error(`${name} is missing; reinstall the plugin for this platform (${error.message})`)
+  }
+}
+
+/**
+ * Controls one overlay window. Coordinates are logical screen points with a top-left origin,
+ * matching what selection-hook reports.
+ * @typedef {object} OverlayWindow
+ * @property {(rect: { x: number, y: number, width: number, height: number }) => void} setBounds
+ * @property {() => void} showInactive Shows the window without activating the app.
+ * @property {() => void} hide
+ * @property {(keyable: boolean) => void} setKeyable Lets the window take keyboard input (the ask box) or not.
+ * @property {() => Record<string, unknown>} inspect Reads back the effective native state, for self tests.
+ */
+
+/**
+ * @typedef {object} NativeWindowTweaks
+ * @property {() => void} preventActivation Keeps this process from ever activating; call before the first event pump.
+ * @property {() => void} hideFromDock
+ * @property {(point: { x: number, y: number }) => ({ x: number, y: number, width: number, height: number } | null)} displayBoundsAt
+ * @property {(win: any) => OverlayWindow} adopt Turns a @webviewjs window into a floating overlay.
+ */
+
+/** @returns {NativeWindowTweaks | null} */
+export function createNativeWindowTweaks() {
+  if (process.platform === 'darwin') return macTweaks(loadKoffi())
+  if (process.platform === 'win32') return windowsTweaks(loadKoffi())
+  return null
+}
+
+/** Fallback without native tweaks: the window activates on show. Only for unsupported platforms. */
+export function plainOverlayWindow(win) {
+  return {
+    setBounds(rect) {
+      win.setSize(rect.width, rect.height, true)
+      win.setPosition(rect.x, rect.y, true)
+    },
+    showInactive: () => win.show(),
+    hide: () => win.hide(),
+    setKeyable: () => {},
+    inspect: () => ({}),
+  }
+}
+
+function macTweaks(koffi) {
+  const objc = koffi.load('/usr/lib/libobjc.A.dylib')
+  const coreGraphics = koffi.load('/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics')
+  const CGPoint = koffi.struct('CGPoint', { x: 'double', y: 'double' })
+  const CGSize = koffi.struct('CGSize', { width: 'double', height: 'double' })
+  const CGRect = koffi.struct('CGRect', { origin: CGPoint, size: CGSize })
+  const mainDisplay = coreGraphics.func('uint32_t CGMainDisplayID(void)')
+  const displayBounds = coreGraphics.func('CGRect CGDisplayBounds(uint32_t display)')
+  const displaysWithPoint = coreGraphics.func('int32_t CGGetDisplaysWithPoint(CGPoint point, uint32_t maxDisplays, _Out_ uint32_t *displays, _Out_ uint32_t *count)')
+
+  const getClass = objc.func('void *objc_getClass(const char *name)')
+  const selector = objc.func('void *sel_registerName(const char *name)')
+  const classOf = objc.func('void *object_getClass(void *obj)')
+  const className = objc.func('const char *class_getName(void *cls)')
+  const allocateClassPair = objc.func('void *objc_allocateClassPair(void *superclass, const char *name, size_t extraBytes)')
+  const registerClassPair = objc.func('void objc_registerClassPair(void *cls)')
+  // On arm64 objc_msgSend must be declared with the exact signature of each call; it is not variadic.
+  const send = {
+    id: objc.func('objc_msgSend', 'void *', ['void *', 'void *']),
+    idIndex: objc.func('objc_msgSend', 'void *', ['void *', 'void *', 'unsigned long']),
+    initPanel: objc.func('objc_msgSend', 'void *', ['void *', 'void *', CGRect, 'unsigned long', 'unsigned long', 'bool']),
+    bool: objc.func('objc_msgSend', 'bool', ['void *', 'void *']),
+    boolId: objc.func('objc_msgSend', 'bool', ['void *', 'void *', 'void *']),
+    boolLong: objc.func('objc_msgSend', 'bool', ['void *', 'void *', 'long']),
+    long: objc.func('objc_msgSend', 'long', ['void *', 'void *']),
+    ulong: objc.func('objc_msgSend', 'unsigned long', ['void *', 'void *']),
+    void: objc.func('objc_msgSend', 'void', ['void *', 'void *']),
+    voidId: objc.func('objc_msgSend', 'void', ['void *', 'void *', 'void *']),
+    voidLong: objc.func('objc_msgSend', 'void', ['void *', 'void *', 'long']),
+    voidUlong: objc.func('objc_msgSend', 'void', ['void *', 'void *', 'unsigned long']),
+    voidBool: objc.func('objc_msgSend', 'void', ['void *', 'void *', 'bool']),
+    voidRect: objc.func('objc_msgSend', 'void', ['void *', 'void *', CGRect]),
+    voidRectBool: objc.func('objc_msgSend', 'void', ['void *', 'void *', CGRect, 'bool']),
+    // Struct returns only go through plain objc_msgSend on arm64; x86_64 would need objc_msgSend_stret.
+    rect: process.arch === 'arm64' ? objc.func('objc_msgSend', CGRect, ['void *', 'void *']) : null,
+  }
+  const sel = (name) => selector(name)
+  const app = () => send.id(getClass('NSApplication'), sel('sharedApplication'))
+  const boolType = process.arch === 'arm64' ? 'B' : 'c'
+
+  // Method implementations installed with class_replaceMethod. AppKit calls them on the main thread
+  // while the event pump runs; the references must stay alive for the life of the process.
+  const NoArgBool = koffi.proto('bool NoArgBool(void *self, void *cmd)')
+  const EventBool = koffi.proto('bool EventBool(void *self, void *cmd, void *event)')
+  const NoArgVoid = koffi.proto('void NoArgVoid(void *self, void *cmd)')
+  const BoolArgVoid = koffi.proto('void BoolArgVoid(void *self, void *cmd, bool flag)')
+  const replace = {
+    noArgBool: objc.func('void *class_replaceMethod(void *cls, void *name, NoArgBool *imp, const char *types)'),
+    eventBool: objc.func('void *class_replaceMethod(void *cls, void *name, EventBool *imp, const char *types)'),
+    noArgVoid: objc.func('void *class_replaceMethod(void *cls, void *name, NoArgVoid *imp, const char *types)'),
+    boolArgVoid: objc.func('void *class_replaceMethod(void *cls, void *name, BoolArgVoid *imp, const char *types)'),
+  }
+  let keyable = false
+  const callbacks = {
+    canBecomeKey: koffi.register(() => keyable, koffi.pointer(NoArgBool)),
+    never: koffi.register(() => false, koffi.pointer(NoArgBool)),
+    always: koffi.register(() => true, koffi.pointer(EventBool)),
+    noop: koffi.register(() => {}, koffi.pointer(NoArgVoid)),
+    noopFlag: koffi.register(() => {}, koffi.pointer(BoolArgVoid)),
+  }
+
+  let panelClass = null
+  // Only NSPanel honours the non-activating style; AppKit rejects it on a plain NSWindow. Key status is
+  // off unless the ask box needs typing, so clicking the toolbar leaves the source app's selection alone.
+  function overlayPanelClass() {
+    if (panelClass) return panelClass
+    panelClass = allocateClassPair(getClass('NSPanel'), 'DSHSelectionPanel', 0)
+    registerClassPair(panelClass)
+    replace.noArgBool(panelClass, sel('canBecomeKeyWindow'), callbacks.canBecomeKey, `${boolType}@:`)
+    replace.noArgBool(panelClass, sel('canBecomeMainWindow'), callbacks.never, `${boolType}@:`)
+    return panelClass
+  }
+
+  function findWebView(view, depth = 0) {
+    if (send.boolId(view, sel('isKindOfClass:'), getClass('WKWebView'))) return view
+    if (depth > 4) return null
+    const subviews = send.id(view, sel('subviews'))
+    const count = Number(send.ulong(subviews, sel('count')))
+    for (let i = 0; i < count; i++) {
+      const found = findWebView(send.idIndex(subviews, sel('objectAtIndex:'), i), depth + 1)
+      if (found) return found
+    }
+    return null
+  }
+
+  // Top-left logical coordinates → Cocoa coordinates (origin at the primary display's bottom-left, y up).
+  function toCocoaFrame(rect) {
+    const primaryHeight = displayBounds(mainDisplay()).size.height
+    return { origin: { x: rect.x, y: primaryHeight - rect.y - rect.height }, size: { width: rect.width, height: rect.height } }
+  }
+
+  function fromCocoaFrame({ origin, size }) {
+    const primaryHeight = displayBounds(mainDisplay()).size.height
+    return { x: origin.x, y: primaryHeight - origin.y - size.height, width: size.width, height: size.height }
+  }
+
+  return {
+    preventActivation() {
+      // tao calls activateIgnoringOtherApps once launching finishes, which would steal focus from the
+      // app the user is selecting in. This process never needs to be the active app.
+      const appClass = classOf(app())
+      replace.boolArgVoid(appClass, sel('activateIgnoringOtherApps:'), callbacks.noopFlag, `v@:${boolType}`)
+      replace.noArgVoid(appClass, sel('activate'), callbacks.noop, 'v@:')
+    },
+    hideFromDock() {
+      send.boolLong(app(), sel('setActivationPolicy:'), 1) // NSApplicationActivationPolicyAccessory
+    },
+    displayBoundsAt(point) {
+      const ids = [0]
+      const count = [0]
+      if (displaysWithPoint({ x: point.x, y: point.y }, 1, ids, count) !== 0 || count[0] === 0) return null
+      const { origin, size } = displayBounds(ids[0])
+      return { x: origin.x, y: origin.y, width: size.width, height: size.height }
+    },
+    adopt(win) {
+      // tao's window is an NSWindow subclass under KVO, so it cannot become a panel. Build a real panel
+      // and move wry's web view into it; the tao window stays hidden and only hosts the web view's origin.
+      const contentView = win.getNativeHandle()
+      const webView = findWebView(contentView)
+      if (!webView) throw new Error('WKWebView not found in the overlay window')
+      let node = webView
+      for (let parent = send.id(node, sel('superview')); parent && parent !== contentView; parent = send.id(node, sel('superview'))) node = parent
+
+      const size = { width: 1, height: 1 }
+      const panel = send.initPanel(
+        send.id(overlayPanelClass(), sel('alloc')),
+        sel('initWithContentRect:styleMask:backing:defer:'),
+        { origin: { x: 0, y: 0 }, size },
+        1 << 7, // borderless + NSWindowStyleMaskNonactivatingPanel
+        2, // NSBackingStoreBuffered
+        false,
+      )
+      send.voidBool(panel, sel('setOpaque:'), false)
+      send.voidId(panel, sel('setBackgroundColor:'), send.id(getClass('NSColor'), sel('clearColor')))
+      send.voidBool(panel, sel('setHasShadow:'), false)
+      send.voidBool(panel, sel('setFloatingPanel:'), true)
+      send.voidBool(panel, sel('setBecomesKeyOnlyIfNeeded:'), true)
+      send.voidBool(panel, sel('setHidesOnDeactivate:'), false)
+      send.voidBool(panel, sel('setReleasedWhenClosed:'), false)
+      // kCGScreenSaverWindowLevel + 1: above full-screen apps, like Electron's setAlwaysOnTop(true, 'screen-saver', 1).
+      send.voidLong(panel, sel('setLevel:'), 1001)
+      // canJoinAllSpaces | stationary | ignoresCycle | fullScreenAuxiliary
+      send.voidUlong(panel, sel('setCollectionBehavior:'), 1 | 16 | 64 | 256)
+
+      send.id(node, sel('retain')) // keep the view alive while it moves between windows
+      send.void(node, sel('removeFromSuperview'))
+      send.voidRect(node, sel('setFrame:'), { origin: { x: 0, y: 0 }, size })
+      send.voidUlong(node, sel('setAutoresizingMask:'), 2 | 16) // follow the panel's width and height
+      send.voidId(send.id(panel, sel('contentView')), sel('addSubview:'), node)
+      // A window that is not key normally spends the first click on becoming active; take it as a real click.
+      replace.eventBool(classOf(webView), sel('acceptsFirstMouse:'), callbacks.always, `${boolType}@:@`)
+
+      return {
+        setBounds(rect) {
+          send.voidRectBool(panel, sel('setFrame:display:'), toCocoaFrame(rect), true)
+        },
+        showInactive() {
+          send.void(panel, sel('orderFrontRegardless'))
+        },
+        hide() {
+          keyable = false
+          send.voidId(panel, sel('orderOut:'), null)
+        },
+        setKeyable(value) {
+          keyable = value
+          if (value) {
+            // A non-activating panel becomes key without activating the app, so the user can type
+            // into the ask box while the app they selected in stays frontmost.
+            send.void(panel, sel('makeKeyWindow'))
+            send.boolId(panel, sel('makeFirstResponder:'), webView)
+          } else if (send.bool(panel, sel('isKeyWindow'))) {
+            send.void(panel, sel('resignKeyWindow'))
+          }
+        },
+        inspect() {
+          return {
+            windowClass: className(classOf(panel)),
+            isPanel: send.boolId(panel, sel('isKindOfClass:'), getClass('NSPanel')),
+            activationPolicy: ['regular', 'accessory', 'prohibited'][Number(send.long(app(), sel('activationPolicy')))],
+            appActive: send.bool(app(), sel('isActive')),
+            nonactivatingPanel: (BigInt(send.ulong(panel, sel('styleMask'))) & (1n << 7n)) !== 0n,
+            level: Number(send.long(panel, sel('level'))),
+            collectionBehavior: Number(send.ulong(panel, sel('collectionBehavior'))),
+            canBecomeKey: send.bool(panel, sel('canBecomeKeyWindow')),
+            isKey: send.bool(panel, sel('isKeyWindow')),
+            isVisible: send.bool(panel, sel('isVisible')),
+            webViewAcceptsFirstMouse: send.boolId(webView, sel('acceptsFirstMouse:'), null),
+            frame: send.rect ? fromCocoaFrame(send.rect(panel, sel('frame'))) : null,
+          }
+        },
+      }
+    },
+  }
+}
+
+function windowsTweaks(koffi) {
+  const user32 = koffi.load('user32.dll')
+  const getLong = user32.func('intptr_t __stdcall GetWindowLongPtrW(void *hwnd, int index)')
+  const setLong = user32.func('intptr_t __stdcall SetWindowLongPtrW(void *hwnd, int index, intptr_t value)')
+  const showWindow = user32.func('bool __stdcall ShowWindow(void *hwnd, int cmd)')
+  const setPos = user32.func('bool __stdcall SetWindowPos(void *hwnd, intptr_t after, int x, int y, int cx, int cy, uint32_t flags)')
+  const setForeground = user32.func('bool __stdcall SetForegroundWindow(void *hwnd)')
+  const getForeground = user32.func('intptr_t __stdcall GetForegroundWindow()')
+  const GWL_EXSTYLE = -20
+  const WS_EX_TOPMOST = 0x8n
+  const WS_EX_TOOLWINDOW = 0x80n
+  const WS_EX_NOACTIVATE = 0x08000000n
+  const HWND_TOPMOST = -1
+  const SWP_NOSIZE_NOMOVE_NOACTIVATE = 0x1 | 0x2 | 0x10
+  const SW_HIDE = 0
+  const SW_SHOWNOACTIVATE = 4
+
+  return {
+    preventActivation() {},
+    hideFromDock() {},
+    displayBoundsAt: () => null,
+    adopt(win) {
+      const hwnd = win.getNativeHandle()
+      const isForeground = () => {
+        try {
+          return BigInt(getForeground()) === BigInt(hwnd)
+        } catch {
+          return false
+        }
+      }
+      const base = BigInt(getLong(hwnd, GWL_EXSTYLE)) | WS_EX_TOPMOST | WS_EX_TOOLWINDOW
+      setLong(hwnd, GWL_EXSTYLE, base | WS_EX_NOACTIVATE)
+      return {
+        // The overlay converts selection-hook's physical pixels to logical ones before calling this.
+        setBounds(rect) {
+          win.setSize(rect.width, rect.height, true)
+          win.setPosition(rect.x, rect.y, true)
+        },
+        showInactive() {
+          showWindow(hwnd, SW_SHOWNOACTIVATE)
+          setPos(hwnd, HWND_TOPMOST, 0, 0, 0, 0, SWP_NOSIZE_NOMOVE_NOACTIVATE)
+        },
+        hide() {
+          setLong(hwnd, GWL_EXSTYLE, base | WS_EX_NOACTIVATE)
+          showWindow(hwnd, SW_HIDE)
+        },
+        setKeyable(value) {
+          setLong(hwnd, GWL_EXSTYLE, value ? base : base | WS_EX_NOACTIVATE)
+          if (value) setForeground(hwnd)
+        },
+        inspect() {
+          const current = BigInt(getLong(hwnd, GWL_EXSTYLE))
+          return {
+            noActivate: (current & WS_EX_NOACTIVATE) !== 0n,
+            toolWindow: (current & WS_EX_TOOLWINDOW) !== 0n,
+            topmost: (current & WS_EX_TOPMOST) !== 0n,
+            // After setKeyable(true) the panel is the foreground window and gets the keystrokes.
+            isKey: isForeground(),
+          }
+        },
+      }
+    },
+  }
+}

package/src/worker/open-url.mjs

@@ -0,0 +1,20 @@
+// Opens a URL with the system handler. Only web links and DSH's own scheme are accepted, because the
+// URL can come from model output or from a page the user selected text in.
+import { openWithSystem } from '../shared/open-with-system.mjs'
+
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'dsh:'])
+
+/** The URL to hand to the system, or null when it must not be opened. */
+export function openableUrl(url) {
+  try {
+    const parsed = new URL(url)
+    return ALLOWED_PROTOCOLS.has(parsed.protocol) ? parsed.href : null
+  } catch {
+    return null
+  }
+}
+
+export function openUrl(url, log) {
+  const href = openableUrl(url)
+  if (href) openWithSystem(href, log)
+}

package/src/worker/overlay.mjs

@@ -0,0 +1,266 @@
+// The floating toolbar and result panel: one system web view (WKWebView / WebView2) in one overlay window.
+// Must run on the process main thread; window events are pumped from a Node timer.
+import { join } from 'node:path'
+import { Application } from '@webviewjs/webview'
+import { dataDirectory } from '../shared/paths.mjs'
+import { createNativeWindowTweaks, plainOverlayWindow } from './native-window.mjs'
+import { pageHtml } from './page.mjs'
+import { fitWindow, place, roomBelow } from './placement.mjs'
+
+const PUMP_VISIBLE_MS = 16
+const PUMP_HIDDEN_MS = 250
+const PAGE_READY_TIMEOUT_MS = 5000
+// The least height a panel gets for its answer before it scrolls: about eight lines plus the header and
+// the follow-up box. Below the selection it may grow further, down to the bottom of the screen.
+const PANEL_MIN_ROOM = 280
+
+/**
+ * Where the selection ended, in screen coordinates as selection-hook reports them.
+ * @typedef {{ x: number, y: number, top: number, precise: boolean }} Anchor
+ * `precise` means `y` is the selection's bottom edge; otherwise it is the mouse-up position.
+ * `top` is the selection's top edge, used when the overlay has to go above the selection.
+ */
+
+/**
+ * @param {{ onMessage: (message: any) => void, log: (level: string, message: string, fields?: object) => void }} options
+ */
+export async function createOverlay({ onMessage, log }) {
+  const tweaks = createNativeWindowTweaks()
+  const app = new Application()
+  // Must happen before the first pump: tao activates the app when launching finishes.
+  tweaks?.preventActivation()
+  const ready = app.whenReady({ autoRun: false })
+  let pump = null
+  const setPump = (ms) => {
+    if (pump?.ms === ms) return
+    if (pump) clearInterval(pump.timer)
+    pump = { ms, timer: setInterval(() => app.pumpEvents(), ms) }
+  }
+  setPump(PUMP_VISIBLE_MS)
+  // tao resets the activation policy when launching finishes, so set it before and after.
+  tweaks?.hideFromDock()
+  await ready
+  tweaks?.hideFromDock()
+
+  // Never shown itself: on macOS its web view moves into a native panel, on Windows the tweaks take over.
+  const win = app.createBrowserWindow({
+    title: 'DSH Selection',
+    width: 320,
+    height: 80,
+    logical: true,
+    decorations: false,
+    transparent: true,
+    resizable: false,
+    minimizable: false,
+    maximizable: false,
+    visible: false,
+    focused: false,
+    alwaysOnTop: true,
+    windowsSkipTaskbar: true,
+    // tao keeps a system shadow on undecorated windows unless told not to; on Windows it outlines the
+    // whole transparent window with a 1px border and adds hidden insets around the client area.
+    windowsUndecoratedShadow: false,
+    macosHasShadow: false,
+  })
+  // WebView2 defaults its data folder next to the executable, i.e. inside the DSH install directory.
+  const webContext = process.platform === 'win32'
+    ? app.createWebContext({ dataDirectory: join(dataDirectory(), 'webview') })
+    : undefined
+
+  // Sizes the page reports: window size plus the primary card (anchored) and every clickable card.
+  const layoutOf = {
+    bar: { width: 420, height: 72, primary: { x: 18, y: 12, width: 384, height: 40 }, hits: [] },
+    panel: { width: 456, height: 260, primary: { x: 18, y: 12, width: 420, height: 224 }, hits: [] },
+  }
+  let mode = 'hidden'
+  /** @type {Anchor | null} */
+  let anchor = null
+  let placement = null
+  let bounds = null
+  // How tall the panel was last allowed to grow, and whether to fill that at once, as told to the page.
+  let room = null
+  // Once the user drags the window it stays where they put it: later size changes keep its top-left.
+  let moved = false
+  let drag = null
+
+  let resolvePage
+  const pageReady = new Promise((resolve) => { resolvePage = resolve })
+  // The page must never leave its own document: a dropped or clicked link would otherwise load a foreign
+  // page that keeps `window.ipc` and would receive every later selection. Only the first load is allowed,
+  // and IPC is accepted only from the document that announced itself first.
+  let loaded = false
+  let pageUri = null
+  const webview = win.createWebview({
+    html: pageHtml(),
+    transparent: true,
+    webContext,
+    navigationHandler: () => !loaded,
+    newWindowHandler: () => false,
+  })
+  webview.setBackgroundColor(0, 0, 0, 0)
+  webview.onIpcMessage((message) => {
+    if (pageUri !== null && message.uri !== pageUri) return
+    let parsed
+    try {
+      parsed = JSON.parse(message.body.toString())
+    } catch {
+      return
+    }
+    if (parsed?.type === 'page-ready' && pageUri === null) {
+      pageUri = message.uri
+      loaded = true
+      resolvePage()
+      return
+    }
+    if (pageUri === null || parsed?.type === 'page-ready') return
+    if (parsed?.type === 'size') resize(parsed)
+    else if (parsed?.type === 'page-error') log('warn', 'toolbar page error', { error: String(parsed.message).slice(0, 300) })
+    else onMessage(parsed)
+  })
+  const overlayWindow = tweaks ? tweaks.adopt(win) : plainOverlayWindow(win)
+  await Promise.race([pageReady, new Promise((resolve) => setTimeout(resolve, PAGE_READY_TIMEOUT_MS))])
+
+  const call = (fn, ...args) => webview.evaluateScript(`window.bar.${fn}(${args.map((arg) => JSON.stringify(arg)).join(',')})`)
+
+  function screenAt(point) {
+    if (tweaks?.displayBoundsAt && process.platform === 'darwin') return tweaks.displayBoundsAt(point)
+    const monitor = win.getMonitorFromPoint(point.x, point.y)
+    if (!monitor) return null
+    const scale = monitor.scaleFactor || 1
+    return { x: monitor.position.x / scale, y: monitor.position.y / scale, width: monitor.size.width / scale, height: monitor.size.height / scale }
+  }
+
+  /** selection-hook reports physical pixels on Windows and points on macOS; layout works in points. */
+  function toLogical(point) {
+    if (process.platform !== 'win32') return point
+    const scale = win.getMonitorFromPoint(point.x, point.y)?.scaleFactor || 1
+    return { ...point, x: point.x / scale, y: point.y / scale, ...(point.top === undefined ? {} : { top: point.top / scale }) }
+  }
+
+  function apply() {
+    const layout = layoutOf[mode]
+    // A dragged window keeps its place; otherwise the primary card starts where the selection ends,
+    // to its right and below it.
+    const origin = moved && bounds
+      ? { x: bounds.x, y: bounds.y }
+      : { x: anchor.x - layout.primary.x, y: placement.top - layout.primary.y }
+    const screen = moved && bounds ? screenUnder(origin, layout) : screenAt(anchor)
+    const next = fitWindow({ origin, layout, screen })
+    if (bounds && Object.keys(next).every((key) => next[key] === bounds[key])) return
+    bounds = next
+    overlayWindow.setBounds(bounds)
+  }
+
+  /** The screen under a window's header; a window dragged off every screen belongs to the selection's. */
+  function screenUnder(origin, layout) {
+    const header = { x: origin.x + layout.primary.x + layout.primary.width / 2, y: origin.y + layout.primary.y + 12 }
+    return screenAt(header) ?? screenAt(anchor)
+  }
+
+  /** The panel scrolls inside instead of growing past its room, so the window never has to move. */
+  function setRoom(next, fill = false) {
+    const value = Number.isFinite(next) ? Math.floor(next) : null
+    const key = `${value}/${fill}`
+    if (mode !== 'panel' || key === room) return
+    room = key
+    call('setRoom', value, fill)
+  }
+
+  function resize(report) {
+    if (report.mode !== 'bar' && report.mode !== 'panel') return
+    layoutOf[report.mode] = { width: report.width, height: report.height, primary: report.primary, hits: report.hits ?? [] }
+    if (report.mode === mode && placement) apply()
+  }
+
+  function show(nextMode, minRoom) {
+    mode = nextMode
+    setPump(PUMP_VISIBLE_MS)
+    placement = place(anchor, minRoom, screenAt(anchor))
+    setRoom(placement.room, placement.fill)
+    apply()
+    overlayWindow.showInactive()
+  }
+
+  return {
+    /** @param {{ bar: object[], more: object[], style: 'full' | 'mini' }} toolbar Skills on the toolbar and in its menu, and how the toolbar is drawn. */
+    configure: (toolbar) => call('configure', toolbar),
+    /** @param {Anchor} point In selection-hook coordinates. */
+    showBar(point) {
+      anchor = toLogical(point)
+      moved = false
+      drag = null
+      call('showBar')
+      show('bar', layoutOf.bar.primary.height)
+    },
+    showPanel(payload) {
+      call('showPanel', payload)
+      show('panel', PANEL_MIN_ROOM)
+    },
+    /** A request started: clears the result (or opens a new turn in the ask panel). */
+    begin: (requestId, info) => call('begin', requestId, info),
+    append: (requestId, chunk) => call('append', requestId, chunk),
+    done: (requestId) => call('done', requestId),
+    fail: (requestId, failure) => call('fail', requestId, failure),
+    setSpeaking: (speaking) => call('setSpeaking', speaking),
+    /** Opens or closes the ⋯ menu (normally done by the page itself). */
+    setMenu: (open) => call('setMenu', open),
+    flash: (skillId) => call('flash', skillId),
+    setKeyable: (keyable) => overlayWindow.setKeyable(keyable),
+    /** Whether the panel has the keyboard, i.e. the user is typing into it. */
+    isKey: () => Boolean(overlayWindow.inspect().isKey),
+    /**
+     * Moves the window with the pointer. Points are the page's screen coordinates; only their
+     * difference from the start is used, so their origin does not matter.
+     * @param {'start' | 'move' | 'end'} phase
+     */
+    drag(phase, point) {
+      if (!bounds || !Number.isFinite(point?.x) || !Number.isFinite(point?.y)) return
+      if (phase === 'start') {
+        drag = { x: point.x, y: point.y, bounds: { ...bounds } }
+        moved = true
+        return
+      }
+      if (!drag) return
+      bounds = { ...bounds, x: Math.round(drag.bounds.x + point.x - drag.x), y: Math.round(drag.bounds.y + point.y - drag.y) }
+      overlayWindow.setBounds(bounds)
+      if (phase !== 'end') return
+      drag = null
+      // Dropped low, the panel still gets room for its answer and moves up as far as that needs.
+      const layout = layoutOf[mode]
+      setRoom(Math.max(PANEL_MIN_ROOM, roomBelow(bounds.y + layout.primary.y, screenUnder(bounds, layout))))
+      apply()
+    },
+    hide() {
+      if (mode === 'hidden') return
+      overlayWindow.hide()
+      mode = 'hidden'
+      placement = null
+      bounds = null
+      room = null
+      moved = false
+      drag = null
+      call('reset')
+      setPump(PUMP_HIDDEN_MS)
+    },
+    get mode() { return mode },
+    /** Where the window was placed, in the same coordinates as `contains` (self tests and diagnostics). */
+    get bounds() { return bounds },
+    /** Whether a point (selection-hook coordinates) is on one of the visible cards, not their shadow margin. */
+    contains(point) {
+      if (mode === 'hidden' || !bounds) return false
+      const { x, y } = toLogical(point)
+      const cards = layoutOf[mode].hits.length ? layoutOf[mode].hits : [layoutOf[mode].primary]
+      return cards.some((card) => x >= bounds.x + card.x && x <= bounds.x + card.x + card.width
+        && y >= bounds.y + card.y && y <= bounds.y + card.y + card.height)
+    },
+    inspect: () => overlayWindow.inspect(),
+    /** Makes the page report its layout through onMessage (self tests). */
+    probe: () => call('probe'),
+    /** Clicks an element in the page through its own click handling (self tests). */
+    click: (selector) => call('click', selector),
+    dispose() {
+      if (pump) clearInterval(pump.timer)
+      app.exit()
+    },
+  }
+}

package/src/worker/page.mjs

@@ -0,0 +1,14 @@
+// The toolbar page as one HTML string: the web view loads it with no file or network access.
+// Kept apart from overlay.mjs, which loads the native web view, so tests can load the same page.
+import { readFileSync } from 'node:fs'
+import { ICONS, brandIcon } from '../shared/icons.mjs'
+
+/** Inlines the page's stylesheet, scripts and icon table. */
+export function pageHtml() {
+  const read = (name) => readFileSync(new URL(`../../ui/${name}`, import.meta.url), 'utf8')
+  return read('toolbar.html')
+    .replace('<link rel="stylesheet" href="toolbar.css">', () => `<style>${read('toolbar.css')}</style>`)
+    .replace('<script src="icons.js"></script>', () => `<script>window.DSH_ICONS = ${JSON.stringify(ICONS)}; window.DSH_BRAND = ${JSON.stringify(brandIcon('brand', '5 5 26 26'))}</script>`)
+    .replace('<script src="markdown.js"></script>', () => `<script>${read('markdown.js')}</script>`)
+    .replace('<script src="toolbar.js"></script>', () => `<script>${read('toolbar.js')}</script>`)
+}