rvlib-shipkit 1.2.0 → 1.4.0

package/src/home/gui-app/ShipkitGui.swift

@@ -1,24 +1,94 @@
-// the shipkit window on macOS: its own app, so the dock and cmd-tab show the
-// house icon, never a second browser. One WKWebView per window on the home's
-// page; every `open -a <app> <url>` opens one more window, cmd-n too. A link
-// to another site opens in the default browser. Built once by `shipkit gui`
-// (home/gui-app.ts) with swiftc, no Xcode project.
+// one web app window on macOS: its own app, so the dock and cmd-tab show its
+// own icon, never a second browser. The same source is the shipkit window and
+// every per-process app (home/gui-app.ts builds both with swiftc, no Xcode
+// project): the bundle's Info.plist names the app (CFBundleName) and the url
+// a bare launch opens (ShipkitStartURL). One WKWebView per window; every
+// `open -a <app> <url>` opens one more window, cmd-n too. A link to another
+// site opens in the default browser.
 import AppKit
 import WebKit
 
-let homeFallback = "http://127.0.0.1:4799/"
+let info = Bundle.main.infoDictionary ?? [:]
+let appName = (info["CFBundleName"] as? String) ?? "shipkit"
+let startURL = URL(string: (info["ShipkitStartURL"] as? String) ?? "") ?? URL(string: "http://127.0.0.1:4799/")!
 
-final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKUIDelegate, NSWindowDelegate {
+/** a url that stays in the app: the machine itself, or the host the app is for */
+func stays(_ url: URL) -> Bool {
+    url.host == "127.0.0.1" || url.host == "localhost" || url.host == startURL.host
+}
+
+/** a window's content: the web view, and the find bar above it when shown.
+ *  WKWebView is an NSTextFinderClient, so the platform find bar searches the
+ *  page; this view is the bar's container */
+final class Pane: NSView, NSTextFinderBarContainer {
+    let web: WKWebView
+    let finder = NSTextFinder()
+
+    init(web: WKWebView) {
+        self.web = web
+        super.init(frame: .zero)
+        addSubview(web)
+        finder.client = web
+        finder.findBarContainer = self
+        finder.isIncrementalSearchingEnabled = true
+        finder.incrementalSearchingShouldDimContentView = false
+    }
+
+    required init?(coder: NSCoder) { fatalError("not from a nib") }
+
+    override var isFlipped: Bool { true }
+
+    var findBarView: NSView? {
+        didSet {
+            oldValue?.removeFromSuperview()
+            if let bar = findBarView { addSubview(bar) }
+            needsLayout = true
+        }
+    }
+
+    var isFindBarVisible = false {
+        didSet {
+            findBarView?.isHidden = !isFindBarVisible
+            needsLayout = true
+        }
+    }
+
+    func findBarViewDidChangeHeight() { needsLayout = true }
+
+    func contentView() -> NSView? { web }
+
+    override func layout() {
+        super.layout()
+        var top: CGFloat = 0
+        if let bar = findBarView, isFindBarVisible {
+            let h = bar.frame.height
+            bar.frame = NSRect(x: 0, y: 0, width: bounds.width, height: h)
+            top = h
+        }
+        web.frame = NSRect(x: 0, y: top, width: bounds.width, height: max(0, bounds.height - top))
+    }
+}
+
+final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKUIDelegate, NSWindowDelegate, NSMenuItemValidation {
     var windows: [NSWindow] = []
     var opened = false
 
     func applicationDidFinishLaunching(_ note: Notification) {
         buildMenu()
+        // esc closes the find bar of the key window, and reaches the page otherwise
+        NSEvent.addLocalMonitorForEvents(matching: .keyDown) { e in
+            if e.keyCode == 53, let pane = self.keyPane(), pane.isFindBarVisible {
+                pane.finder.performAction(.hideFindInterface)
+                pane.window?.makeFirstResponder(pane.web)
+                return nil
+            }
+            return e
+        }
         // an open event may deliver the url right after launch: wait for it
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
             if !self.opened {
                 let arg = CommandLine.arguments.dropFirst().first { $0.hasPrefix("http") }
-                self.open(URL(string: arg ?? homeFallback)!)
+                self.open(arg.flatMap { URL(string: $0) } ?? startURL)
             }
         }
     }
@@ -30,26 +100,27 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
     func applicationShouldTerminateAfterLastWindowClosed(_ app: NSApplication) -> Bool { true }
 
     func applicationShouldHandleReopen(_ app: NSApplication, hasVisibleWindows: Bool) -> Bool {
-        if !hasVisibleWindows { open(URL(string: homeFallback)!) }
+        if !hasVisibleWindows { open(startURL) }
         return true
     }
 
+    func keyPane() -> Pane? { NSApp.keyWindow?.contentView as? Pane }
+
     @objc func newWindow(_ sender: Any?) {
-        let current = (NSApp.keyWindow?.contentView as? WKWebView)?.url
-        open(current ?? URL(string: homeFallback)!)
+        open(keyPane()?.web.url ?? startURL)
     }
 
     @objc func reload(_ sender: Any?) {
-        (NSApp.keyWindow?.contentView as? WKWebView)?.reload()
+        keyPane()?.web.reload()
     }
 
-    // the zoom is one value for every window, kept across restarts
+    // the zoom is one value for every window of the app, kept across restarts
     var zoom: CGFloat {
         get { let z = UserDefaults.standard.double(forKey: "pageZoom"); return z > 0 ? CGFloat(z) : 1 }
         set {
             let z = min(3, max(0.3, newValue))
             UserDefaults.standard.set(Double(z), forKey: "pageZoom")
-            for w in windows { (w.contentView as? WKWebView)?.pageZoom = z }
+            for w in windows { (w.contentView as? Pane)?.web.pageZoom = z }
         }
     }
 
@@ -57,19 +128,51 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
     @objc func zoomOut(_ sender: Any?) { zoom = zoom / 1.1 }
     @objc func zoomReset(_ sender: Any?) { zoom = 1 }
 
+    // the menu item's tag is the NSTextFinder.Action it performs
+    @objc func findAction(_ sender: NSMenuItem) {
+        guard let pane = keyPane(), let action = NSTextFinder.Action(rawValue: sender.tag) else { return }
+        pane.finder.performAction(action)
+    }
+
+    // no public api opens the inspector: `_inspector` then `show` is the
+    // WebKit call the context menu's Inspect Element makes. Where it is gone,
+    // say where the inspector still is
+    @objc func devTools(_ sender: Any?) {
+        guard let web = keyPane()?.web else { return }
+        let get = NSSelectorFromString("_inspector"), show = NSSelectorFromString("show")
+        if web.responds(to: get), let inspector = web.perform(get)?.takeUnretainedValue() as? NSObject, inspector.responds(to: show) {
+            inspector.perform(show)
+            return
+        }
+        let alert = NSAlert()
+        alert.messageText = "This WebKit has no way to open the inspector from a menu"
+        alert.informativeText = "Right click the page and pick Inspect Element."
+        alert.runModal()
+    }
+
+    func validateMenuItem(_ item: NSMenuItem) -> Bool {
+        if item.action == #selector(findAction(_:)) {
+            guard let pane = keyPane(), let action = NSTextFinder.Action(rawValue: item.tag) else { return false }
+            return pane.finder.validateAction(action)
+        }
+        if item.action == #selector(devTools(_:)) || item.action == #selector(reload(_:)) { return keyPane() != nil }
+        return true
+    }
+
     func open(_ url: URL) {
         opened = true
         let config = WKWebViewConfiguration()
         config.preferences.setValue(true, forKey: "developerExtrasEnabled")
         let web = WKWebView(frame: .zero, configuration: config)
+        if #available(macOS 13.3, *) { web.isInspectable = true }
         web.navigationDelegate = self
         web.uiDelegate = self
         web.allowsBackForwardNavigationGestures = true
         web.pageZoom = zoom
         let frame = NSRect(x: 0, y: 0, width: 1400, height: 900)
         let win = NSWindow(contentRect: frame, styleMask: [.titled, .closable, .miniaturizable, .resizable], backing: .buffered, defer: false)
-        win.contentView = web
-        win.title = "shipkit"
+        win.contentView = Pane(web: web)
+        win.title = appName
         win.delegate = self
         win.isReleasedWhenClosed = false
         win.setFrameAutosaveName("shipkit-window")
@@ -77,6 +180,7 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
         windows.append(win)
         web.load(URLRequest(url: url))
         win.makeKeyAndOrderFront(nil)
+        win.makeFirstResponder(web)
         NSApp.activate(ignoringOtherApps: true)
     }
 
@@ -84,35 +188,40 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
         windows.removeAll { $0 === note.object as? NSWindow }
     }
 
-    // the page title names the window, so cmd-tab and the window menu tell repos apart
+    // the page title names the window, so cmd-tab and the window menu tell pages apart
     func webView(_ web: WKWebView, didFinish nav: WKNavigation!) {
-        web.window?.title = (web.title?.isEmpty == false) ? web.title! : "shipkit"
+        web.window?.title = (web.title?.isEmpty == false) ? web.title! : appName
     }
 
-    // same host: stay in the window; anything else: the default browser
+    // the app's own host: stay in the window; anything else: the default browser
     func webView(_ web: WKWebView, decidePolicyFor action: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
         guard let url = action.request.url, action.navigationType == .linkActivated else { return decisionHandler(.allow) }
-        let local = url.host == "127.0.0.1" || url.host == "localhost"
-        if local { return decisionHandler(.allow) }
+        if stays(url) { return decisionHandler(.allow) }
         NSWorkspace.shared.open(url)
         decisionHandler(.cancel)
     }
 
-    // window.open and target=_blank: one more shipkit window for a local page
+    // window.open and target=_blank: one more window of this app for its own pages
     func webView(_ web: WKWebView, createWebViewWith config: WKWebViewConfiguration, for action: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
         if let url = action.request.url {
-            if url.host == "127.0.0.1" || url.host == "localhost" { open(url) } else { NSWorkspace.shared.open(url) }
+            if stays(url) { open(url) } else { NSWorkspace.shared.open(url) }
         }
         return nil
     }
 
+    func item(_ menu: NSMenu, _ title: String, _ action: Selector, _ key: String, _ mods: NSEvent.ModifierFlags = [.command], tag: Int = 0) {
+        let i = menu.addItem(withTitle: title, action: action, keyEquivalent: key)
+        i.keyEquivalentModifierMask = mods
+        i.tag = tag
+    }
+
     func buildMenu() {
         let main = NSMenu()
         let appItem = NSMenuItem()
         main.addItem(appItem)
         let appMenu = NSMenu()
-        appMenu.addItem(withTitle: "Hide shipkit", action: #selector(NSApplication.hide(_:)), keyEquivalent: "h")
-        appMenu.addItem(withTitle: "Quit shipkit", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+        appMenu.addItem(withTitle: "Hide \(appName)", action: #selector(NSApplication.hide(_:)), keyEquivalent: "h")
+        appMenu.addItem(withTitle: "Quit \(appName)", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
         appItem.submenu = appMenu
         let fileItem = NSMenuItem()
         main.addItem(fileItem)
@@ -130,6 +239,14 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
         edit.addItem(withTitle: "Copy", action: #selector(NSText.copy(_:)), keyEquivalent: "c")
         edit.addItem(withTitle: "Paste", action: #selector(NSText.paste(_:)), keyEquivalent: "v")
         edit.addItem(withTitle: "Select All", action: #selector(NSText.selectAll(_:)), keyEquivalent: "a")
+        edit.addItem(.separator())
+        let findItem = edit.addItem(withTitle: "Find", action: nil, keyEquivalent: "")
+        let find = NSMenu(title: "Find")
+        item(find, "Find…", #selector(findAction(_:)), "f", tag: NSTextFinder.Action.showFindInterface.rawValue)
+        item(find, "Find Next", #selector(findAction(_:)), "g", tag: NSTextFinder.Action.nextMatch.rawValue)
+        item(find, "Find Previous", #selector(findAction(_:)), "g", [.command, .shift], tag: NSTextFinder.Action.previousMatch.rawValue)
+        item(find, "Hide Find Bar", #selector(findAction(_:)), "", [], tag: NSTextFinder.Action.hideFindInterface.rawValue)
+        edit.setSubmenu(find, for: findItem)
         editItem.submenu = edit
         let viewItem = NSMenuItem()
         main.addItem(viewItem)
@@ -141,6 +258,8 @@ final class Delegate: NSObject, NSApplicationDelegate, WKNavigationDelegate, WKU
         alsoIn.isAlternate = true
         alsoIn.keyEquivalentModifierMask = [.command]
         view.addItem(withTitle: "Zoom Out", action: #selector(zoomOut(_:)), keyEquivalent: "-")
+        view.addItem(.separator())
+        item(view, "Developer Tools", #selector(devTools(_:)), "i", [.command, .option])
         viewItem.submenu = view
         let winItem = NSMenuItem()
         main.addItem(winItem)

package/src/home/gui-app.ts

@@ -1,90 +1,122 @@
-// the macOS app `shipkit gui` opens windows through: a bundle built once from
-// ShipkitGui.swift with swiftc, carrying the house repo's own icon, so the
-// dock and cmd-tab show it and never a second Chrome. Rebuilt only when the
-// source or the icon changed (a stamp in the bundle). No compiler, or not
-// macOS: the caller falls back to a Chrome app window.
+// the macOS apps shipkit opens web pages in: ONE source, ShipkitGui.swift,
+// built with swiftc into a bundle per page it serves. `shipkit gui` is that
+// app pointed at the home; each global process with a url gets its own, named
+// and iconed after it, in its repo's `.shipkit/wrapper/`. The bundle's
+// Info.plist carries what differs (name, bundle id, start url), so a fix to
+// the window (find, the inspector, zoom) lands in every app at its next
+// build. Rebuilt only when the source, the icon or the start url changed (a
+// stamp in the bundle). No compiler, or not macOS: the caller falls back.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { LAYOUT } from '../core/layout.ts'
 
 const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.url))
 
 export const BUNDLE_ID = 'dev.shipkit.gui'
 export const guiAppPath = (): string => process.env.SHIPKIT_GUI_APP ?? join(homedir(), 'Applications', 'Shipkit.app')
 
-/** the icon the app wears: the house repo's own mark, largest first. Only a
+/** the icon the app wears: the repo's own mark, largest first. Only a
  *  png can become an icns */
-export const APP_ICON_FILES = ['.shipkit/identity/icon.png', 'public/logo.png', 'public/favicon.png']
+export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
 
 export function appIconOf(root: string): string | null {
     for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
     return null
 }
 
-export function infoPlist(o: { version: string }): string {
+/** what one app bundle is: the rest comes from the shared source */
+export type AppSpec = {
+    /** CFBundleName: the dock, cmd-tab and the app menu say it */
+    name: string
+    bundleId: string
+    /** the page a launch with no url opens; null opens the home */
+    url: string | null
+    icon: string | null
+    /** where the bundle lands */
+    app: string
+    version: string
+}
+
+const xml = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/** plain http to a host that is not local needs its own ATS exception; the
+ *  local network is allowed to every app */
+function atsOf(url: string | null): string {
+    let u: URL | null = null
+    try { u = url == null ? null : new URL(url) } catch { /* not a url: the local network only */ }
+    const host = u?.protocol === 'http:' ? u.hostname : null
+    const local = host == null || host === 'localhost' || /^[\d.]+$/.test(host) || !host.includes('.') || host.endsWith('.local')
+    const exception = local ? '' : `<key>NSExceptionDomains</key><dict><key>${xml(host)}</key><dict><key>NSExceptionAllowsInsecureHTTPLoads</key><true/></dict></dict>`
+    return `<dict><key>NSAllowsLocalNetworking</key><true/>${exception}</dict>`
+}
+
+export function infoPlist(o: Omit<AppSpec, 'app' | 'icon'>): string {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-\t<key>CFBundleName</key><string>shipkit</string>
-\t<key>CFBundleDisplayName</key><string>shipkit</string>
-\t<key>CFBundleIdentifier</key><string>${BUNDLE_ID}</string>
+\t<key>CFBundleName</key><string>${xml(o.name)}</string>
+\t<key>CFBundleDisplayName</key><string>${xml(o.name)}</string>
+\t<key>CFBundleIdentifier</key><string>${xml(o.bundleId)}</string>
 \t<key>CFBundleExecutable</key><string>shipkit-gui</string>
 \t<key>CFBundleIconFile</key><string>AppIcon</string>
 \t<key>CFBundlePackageType</key><string>APPL</string>
-\t<key>CFBundleShortVersionString</key><string>${o.version}</string>
-\t<key>CFBundleVersion</key><string>${o.version}</string>
-\t<key>LSMinimumSystemVersion</key><string>12.0</string>
+\t<key>CFBundleShortVersionString</key><string>${xml(o.version)}</string>
+\t<key>CFBundleVersion</key><string>${xml(o.version)}</string>
+${o.url == null ? '' : `\t<key>ShipkitStartURL</key><string>${xml(o.url)}</string>\n`}\t<key>LSMinimumSystemVersion</key><string>12.0</string>
 \t<key>NSHighResolutionCapable</key><true/>
-\t<key>NSAppTransportSecurity</key><dict><key>NSAllowsLocalNetworking</key><true/></dict>
+\t<key>NSAppTransportSecurity</key>${atsOf(o.url)}
 </dict>
 </plist>
 `
 }
 
-type Run = (cmd: string[]) => { code: number; err: string }
+export type Run = (cmd: string[]) => { code: number; err: string }
 const runSync: Run = (cmd) => {
     const p = Bun.spawnSync(cmd, { stdout: 'ignore', stderr: 'pipe' })
     return { code: p.exitCode ?? 1, err: p.stderr.toString().trim() }
 }
 
-/** the stamp a built bundle carries: what it was built from */
-export function stampOf(source: string, icon: string | null): string {
-    const h = new Bun.CryptoHasher('sha256').update(source)
+/** the stamp a built bundle carries: what it was built from. The version is
+ *  left out, so a shipkit release rebuilds nothing */
+export function stampOf(source: string, icon: string | null, identity = ''): string {
+    const h = new Bun.CryptoHasher('sha256').update(source).update(identity)
     if (icon != null) h.update(readFileSync(icon))
     return h.digest('hex').slice(0, 16)
 }
 
-/** the app, built or rebuilt when stale. Throws with the step that failed.
+/** one app, built or rebuilt when stale. Throws with the step that failed.
  *  `rebuilt` tells the caller a running copy is now the old one */
-export function ensureGuiApp(o: { root: string; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
-    const app = o.app ?? guiAppPath()
+export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): { app: string; rebuilt: boolean } {
+    const { app, icon } = spec
     const run = o.run ?? runSync
-    const icon = appIconOf(o.root)
-    const stamp = stampOf(readFileSync(SOURCE, 'utf8'), icon)
+    const source = o.source ?? SOURCE
+    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url]))
     const stampFile = join(app, 'Contents', 'Resources', 'stamp')
     if (existsSync(stampFile) && readFileSync(stampFile, 'utf8') === stamp) return { app, rebuilt: false }
     const tmp = `${app}.building-${process.pid}`
+    const fail = (msg: string): never => { rmSync(tmp, { recursive: true, force: true }); throw new Error(msg) }
     rmSync(tmp, { recursive: true, force: true })
     const res = join(tmp, 'Contents', 'Resources')
     mkdirSync(join(tmp, 'Contents', 'MacOS'), { recursive: true })
     mkdirSync(res, { recursive: true })
-    writeFileSync(join(tmp, 'Contents', 'Info.plist'), infoPlist({ version: o.version }))
-    const built = run(['swiftc', '-O', '-o', join(tmp, 'Contents', 'MacOS', 'shipkit-gui'), SOURCE])
-    if (built.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`swiftc could not build the gui app: ${built.err.slice(0, 400)}`) }
+    writeFileSync(join(tmp, 'Contents', 'Info.plist'), infoPlist(spec))
+    const built = run(['swiftc', '-O', '-o', join(tmp, 'Contents', 'MacOS', 'shipkit-gui'), source])
+    if (built.code !== 0) fail(`swiftc could not build ${spec.name}.app: ${built.err.slice(0, 400)}`)
     if (icon != null) {
         const set = join(res, 'AppIcon.iconset')
         mkdirSync(set, { recursive: true })
         for (const n of [16, 32, 128, 256, 512]) {
             for (const [scale, px] of [['', n], ['@2x', n * 2]] as const) {
-                const r = run(['sips', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
-                if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`) }
+                const r = run(['sips', '-s', 'format', 'png', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
+                if (r.code !== 0) fail(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`)
             }
         }
         const r = run(['iconutil', '-c', 'icns', set, '-o', join(res, 'AppIcon.icns')])
         rmSync(set, { recursive: true, force: true })
-        if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`iconutil could not build the icon: ${r.err.slice(0, 200)}`) }
+        if (r.code !== 0) fail(`iconutil could not build the icon: ${r.err.slice(0, 200)}`)
     }
     writeFileSync(join(res, 'stamp'), stamp)
     mkdirSync(dirname(app), { recursive: true })
@@ -95,5 +127,36 @@ export function ensureGuiApp(o: { root: string; version: string; app?: string; r
     return { app, rebuilt: true }
 }
 
+/** the shipkit app: the shared source on the home, the house repo's icon */
+export function ensureGuiApp(o: { root: string | null; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
+    return ensureApp({ name: 'shipkit', bundleId: BUNDLE_ID, url: null, icon: o.root == null ? null : appIconOf(o.root), app: o.app ?? guiAppPath(), version: o.version }, { run: o.run })
+}
+
+/** what a global process gives its app */
+export type WrapperOf = { id: string; label: string; url: string | null; icon: string | null; root: string }
+
+/** the image icons sips reads; an emoji or an svg leaves the repo's mark */
+const RASTER = /\.(png|jpe?g|gif|webp|bmp|tiff?)$/i
+
+export const wrapperBundleId = (id: string): string => `dev.shipkit.app.${id.replace(/[^A-Za-z0-9-]+/g, '-')}`
+export const wrapperPath = (root: string, id: string): string => join(root, LAYOUT.wrapper, `${id.replace(/[^A-Za-z0-9._-]+/g, '-')}.app`)
+
+/** the spec of a process's own app: its label, its declared image icon or
+ *  else its repo's mark, in its repo's `.shipkit/wrapper/`. Throws for a
+ *  process with no url: there is no page to wrap */
+export function wrapperSpec(d: WrapperOf, version: string): AppSpec {
+    if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
+    const declared = d.icon != null && RASTER.test(d.icon) && existsSync(join(d.root, d.icon)) ? join(d.root, d.icon) : null
+    return { name: d.label, bundleId: wrapperBundleId(d.id), url: d.url, icon: declared ?? appIconOf(d.root), app: wrapperPath(d.root, d.id), version }
+}
+
+export const ensureWrapperApp = (d: WrapperOf, o: { version: string; run?: Run }): { app: string; rebuilt: boolean; bundleId: string } => {
+    const spec = wrapperSpec(d, o.version)
+    return { ...ensureApp(spec, { run: o.run }), bundleId: spec.bundleId }
+}
+
+/** quits a running copy of an app, and launches nothing when none runs */
+export const quitCmd = (bundleId: string): string[] => ['osascript', '-e', `if application id "${bundleId}" is running then quit application id "${bundleId}"`]
+
 /** true when this machine can build the app */
 export const canBuildGui = (platform = process.platform): boolean => platform === 'darwin' && Bun.which('swiftc') != null && Bun.which('iconutil') != null

package/src/home/home-launchd.ts

@@ -2,7 +2,7 @@
 // dies. macOS only; launchd is the one supervisor of the one process that must
 // always run, and pm supervises everything else (the daemon, the web, the
 // machine resources).
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { homeDir, pmLog } from './home-paths.ts'
@@ -55,7 +55,15 @@ ${args}
 `
 }
 
-type Launchctl = (args: string[]) => Promise<{ code: number; out: string }>
+/** the house repo the installed pm runs from, read back from its agent: the
+ *  one answer to "which house" that does not depend on cwd */
+export function installedHouseRoot(file = plistPath()): string | null {
+    if (!existsSync(file)) return null
+    const m = /<key>WorkingDirectory<\/key>\s*<string>([^<]*)<\/string>/.exec(readFileSync(file, 'utf8'))
+    return m == null ? null : m[1]!.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+}
+
+type Launchctl =(args: string[]) => Promise<{ code: number; out: string }>
 
 const launchctl: Launchctl = async (args) => {
     const p = Bun.spawn(['launchctl', ...args], { stdout: 'pipe', stderr: 'pipe' })

package/src/home/home-routes.ts

@@ -16,6 +16,9 @@ import { tailLines } from './supervise.ts'
 import { Hubs, type WorkerView } from './hubs.ts'
 import type { Planner, PlanRow } from '../plan/planner.ts'
 import type { Widgets, WidgetView } from './widgets.ts'
+import { ActivityCache, windowMinutes } from './activity.ts'
+import { HouseRuns } from '../serve/house-runs.ts'
+import type { HouseView } from '../ledger/house-runs.ts'
 
 /** how often the daemon looks at every repo */
 export const TICK_MS = 2_000
@@ -76,10 +79,13 @@ export const runModernize = async (repo: WiredRepo, root: string, log: string):
     }
 }
 
-/** active = an agent works in it, VS Code has it open, or it is flagged by hand */
-export function activeSet(rows: ProjectRow[], flagged: string[]): Set<string> {
+/** active = an agent works in it, VS Code has it open, or it is flagged by
+ *  hand. The house repo is active whenever any repo is: its checks serve
+ *  every repo (a login, a shared key), so they follow the machine's work */
+export function activeSet(rows: ProjectRow[], flagged: string[], house?: string): Set<string> {
     const out = new Set(flagged)
     for (const r of rows) if ((r.sessions != null && r.sessions > 0) || r.vscode === true) out.add(r.name)
+    if (house != null && out.size > 0) out.add(house)
     return out
 }
 
@@ -87,13 +93,24 @@ export function activeSet(rows: ProjectRow[], flagged: string[]): Set<string> {
 export type WidgetsAnswer = { widgets: WidgetView[]; errors: string[] }
 
 /** the planned page's data: every row of the machine's plan */
-export type PlannedAnswer = { now: number; rows: PlanRow[]; errors: { repo: string; error: string }[]; running: boolean }
+export type PlannedAnswer = {
+    now: number
+    rows: PlanRow[]
+    errors: { repo: string; error: string }[]
+    running: boolean
+    /** what holds work back, one line each (Planner.held) */
+    held: string[]
+}
 
 export function homeRoutes(d: HomeDeps) {
     let repos: WiredRepo[] = []
     let rows: ProjectRow[] = []
     const modernizing = new Map<string, ModernizeView & { log: string }>()
+    // read only while the activity page asks, never on the tick
+    const activity = new ActivityCache({ declared: (name) => d.plan?.declared(name) ?? null, titles: (name) => d.plan?.titles(name) ?? null })
     const modernizeLog = (repo: string): string => join(d.dir, 'modernize', `${repo}.log`)
+    // the dock: every loaded repo's recent runs, read only while a page asks
+    const house = new HouseRuns(() => repos)
 
     async function refresh(): Promise<void> {
         const a = await d.gutter.answer()
@@ -107,7 +124,7 @@ export function homeRoutes(d: HomeDeps) {
 
     async function tick(): Promise<void> {
         await refresh()
-        active = activeSet(rows, d.state.data.active)
+        active = activeSet(rows, d.state.data.active, rows.find((r) => r.path === d.root)?.name ?? d.name)
         // the plan's clock: one look per tick, and it starts at most one batch
         d.plan?.tick()
         // a widget render never holds the tick back
@@ -148,11 +165,22 @@ export function homeRoutes(d: HomeDeps) {
         }
         if (path === '/api/home/planned.json') {
             if (repos.length === 0) await refresh()
-            const out: PlannedAnswer = { now: Date.now(), rows: d.plan?.rows() ?? [], errors: d.plan?.errors() ?? [], running: d.plan?.busy() === true }
+            const out: PlannedAnswer = { now: Date.now(), rows: d.plan?.rows() ?? [], errors: d.plan?.errors() ?? [], running: d.plan?.busy() === true, held: d.plan?.held() ?? [] }
             return Response.json(out)
         }
+        if (path === '/api/home/activity.json') {
+            if (repos.length === 0) await refresh()
+            const q = new URL(req.url).searchParams
+            return Response.json(await activity.get(repos, windowMinutes(q.get('m')), { fresh: q.get('fresh') === '1' }))
+        }
+        if (path === '/api/house-runs.json') {
+            if (repos.length === 0) await refresh()
+            const view: HouseView = { ...house.view(), held: d.plan?.held() ?? [] }
+            return Response.json(view, { headers: { 'cache-control': 'no-store' } })
+        }
         if (path === '/api/home/widgets.json') {
-            const out: WidgetsAnswer = { widgets: d.widgets?.views() ?? [], errors: d.widgets?.errors ?? [] }
+            if (d.widgets != null && repos.length === 0) await refresh()
+            const out: WidgetsAnswer = { widgets: (await d.widgets?.look(repos.map((r) => ({ name: r.name, path: r.path })))) ?? [], errors: d.widgets?.errors ?? [] }
             return Response.json(out)
         }
         if (path === '/api/home.json') {

package/src/home/home-start.ts

@@ -6,8 +6,8 @@ import { homedir } from 'os'
 import { dirname, join, resolve } from 'path'
 import { gitRoot } from '../core/git-root.ts'
 import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
-import { BUNDLE_ID, canBuildGui, ensureGuiApp } from './gui-app.ts'
-import { LABEL, plistPath } from './home-launchd.ts'
+import { BUNDLE_ID, canBuildGui, ensureGuiApp, ensureWrapperApp, quitCmd, type WrapperOf } from './gui-app.ts'
+import { installedHouseRoot, LABEL, plistPath } from './home-launchd.ts'
 import { childLog, daemonPort, daemonUp, homeDir, homePort, homeUp, pmLog } from './home-paths.ts'
 
 /** the pm LaunchAgent is installed: on this machine no hub runs outside the home */
@@ -65,7 +65,11 @@ export function houseRootOf(cwd: string): string | null {
     return gitRoot(dirname(index))?.top ?? null
 }
 
-export const CHROME = process.env.CHROME ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+/** the house the shipkit app wears the mark of: the one cwd sits in, else the
+ *  one the installed pm runs from. Never cwd itself, which carries no mark */
+export const guiRoot = (cwd: string, plist = plistPath()): string | null => houseRootOf(cwd) ?? installedHouseRoot(plist)
+
+export const CHROME =process.env.CHROME ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
 /** the window's own Chrome profile: its own dock icon and cookies, apart from the everyday browser */
 export const guiProfile = (): string => join(homeDir(), 'gui-profile')
 const GUI_DISK_CACHE = 32 * 1024 * 1024
@@ -87,9 +91,9 @@ export function windowCmd(url: string, o: { chrome?: string; platform?: string }
 export function openWindow(url: string, o: { root?: string | null; version?: string; warn?: (l: string) => void } = {}): string[] {
     if (canBuildGui()) {
         try {
-            const { app, rebuilt } = ensureGuiApp({ root: o.root ?? houseRootOf(process.cwd()) ?? process.cwd(), version: o.version ?? '0' })
+            const { app, rebuilt } = ensureGuiApp({ root: o.root ?? guiRoot(process.cwd()),version: o.version ?? '0' })
             // a running copy is the old build: it quits, and the new one opens the window
-            if (rebuilt) Bun.spawnSync(['osascript', '-e', `quit app id "${BUNDLE_ID}"`], { stdout: 'ignore', stderr: 'ignore' })
+            if (rebuilt) Bun.spawnSync(quitCmd(BUNDLE_ID), { stdout: 'ignore', stderr: 'ignore' })
             const cmd = ['open', '-a', app, url]
             Bun.spawn(cmd, { stdio: ['ignore', 'ignore', 'ignore'] })
             return cmd
@@ -97,6 +101,30 @@ export function openWindow(url: string, o: { root?: string | null; version?: str
             o.warn?.(`WARN the shipkit app could not be built, so this window is a Chrome one: ${(e as Error).message}`)
         }
     }
+    return chromeWindow(url)
+}
+
+/** a global process's own app: built on first use in its repo's
+ *  `.shipkit/wrapper/`, then opened with no url, so a running copy comes to
+ *  the front instead of stacking windows. Where no app can be built, a
+ *  Chrome app window on its url */
+export function openProcessApp(d: WrapperOf, o: { version: string; warn?: (l: string) => void }): string[] {
+    if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
+    if (canBuildGui()) {
+        try {
+            const { app, rebuilt, bundleId } = ensureWrapperApp(d, { version: o.version })
+            if (rebuilt) Bun.spawnSync(quitCmd(bundleId), { stdout: 'ignore', stderr: 'ignore' })
+            const cmd = ['open', '-a', app]
+            Bun.spawnSync(cmd, { stdout: 'ignore', stderr: 'ignore' })
+            return cmd
+        } catch (e) {
+            o.warn?.(`WARN the app for ${d.id} could not be built, so this window is a Chrome one: ${(e as Error).message}`)
+        }
+    }
+    return chromeWindow(d.url)
+}
+
+function chromeWindow(url: string): string[] {
     mkdirSync(guiProfile(), { recursive: true })
     const cmd = windowCmd(url)
     // detached: the window outlives the command that opened it