agentix-cli 0.26.0 → 0.28.0

package/apps/mac-helper/build.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Build the native computer-use helper.
+#
+# Bundled as a .app even though it is a CLI: macOS only offers an
+# Accessibility permission prompt to a bundled, signed binary, and a bare
+# executable silently reads an empty tree instead — which looks exactly
+# like an app with no controls.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+APP="build/AgentX Helper.app"
+BIN="$APP/Contents/MacOS"
+rm -rf build && mkdir -p "$BIN"
+
+swiftc -O -o "$BIN/agentx-mac-helper" \
+  Sources/AgentXHelper/*.swift \
+  -framework AppKit -framework ApplicationServices -framework Vision \
+  -target arm64-apple-macosx14.0
+
+cat > "$APP/Contents/Info.plist" <<'PLIST'
+<?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>
+  <key>CFBundleName</key><string>AgentX Helper</string>
+  <key>CFBundleIdentifier</key><string>tn.acme.agentx.helper</string>
+  <key>CFBundleExecutable</key><string>agentx-mac-helper</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>0.1.0</string>
+  <key>LSUIElement</key><true/>
+</dict>
+PLIST
+echo "</plist>" >> "$APP/Contents/Info.plist"
+
+codesign --force --sign - --identifier tn.acme.agentx.helper "$APP" 2>/dev/null \
+  || echo "warning: codesign failed; Accessibility grants will not stick across rebuilds"
+
+echo "built: $APP"
+echo "binary: $BIN/agentx-mac-helper"

package/apps/mac-voice/Resources/Info.plist

@@ -0,0 +1,18 @@
+<?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>
+  <key>CFBundleName</key><string>AgentX Desktop</string>
+  <key>CFBundleDisplayName</key><string>AgentX Desktop</string>
+  <key>CFBundleIdentifier</key><string>tn.acme.agentx.voice</string>
+  <key>CFBundleExecutable</key><string>AgentXVoice</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>0.1.0</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>LSMinimumSystemVersion</key><string>14.0</string>
+  <!-- Accessory: floats over other apps, no Dock icon, never steals focus. -->
+  <key>LSUIElement</key><true/>
+  <key>NSMicrophoneUsageDescription</key>
+  <string>AgentX Desktop records your voice only while you hold the hotkey, so it can transcribe your instruction and send it to your agent.</string>
+</dict>
+</plist>

package/apps/mac-voice/Sources/AgentXVoice/AgentClient.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+/// Talks to the local agentx daemon's /ask endpoint.
+///
+/// /ask already does the voice-specific work server-side: it prepends a
+/// VOICE MODE instruction and returns `text` pre-flattened for TTS by
+/// toSpeakable(). So this client deliberately does no prompt shaping of
+/// its own — two places deciding how an agent should sound is how they
+/// drift apart.
+///
+/// No auth header: the daemon exempts loopback (see mesh-auth.ts), and
+/// this widget is loopback by definition. Pointing AGENTX_DAEMON_URL at a
+/// remote node would need a token, which is why it isn't the default.
+enum AgentClient {
+    struct Answer {
+        /// What to speak: short, no URLs, no markdown.
+        let text: String
+        /// What to show: the answer as written, with the links and
+        /// formatting the spoken form had to drop.
+        let written: String?
+        /// Buttons and media from the agentx:ui directive, parsed server-side.
+        let buttons: [(String, String)]
+        let imageURL: String?
+        let durationMs: Int?
+    }
+
+    /// What, if anything, to say about the step now running.
+    ///
+    /// The daemon decides, because the phrasing lives with the model that
+    /// chooses it. Returning nil is the common and correct case — most
+    /// steps are not worth interrupting for, and the pill already shows
+    /// every one of them to anyone looking.
+    ///
+    /// Never throws: a narration that fails is silence, which is exactly
+    /// what it would have been anyway.
+    static func phrase(tool: String, detail: String, elapsed: Int) async -> String? {
+        guard let url = URL(string: "\(Config.daemonURL)/voice/phrase") else { return nil }
+        var req = URLRequest(url: url)
+        req.httpMethod = "POST"
+        // Shorter than the turn it narrates: a phrase that arrives late
+        // describes work already finished.
+        req.timeoutInterval = 6
+        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        req.httpBody = try? JSONSerialization.data(withJSONObject: [
+            "tool": tool, "detail": detail, "elapsedSeconds": elapsed,
+        ])
+        guard let (data, _) = try? await URLSession.shared.data(for: req) else { return nil }
+        struct Reply: Decodable { let say: String? }
+        return (try? JSONDecoder().decode(Reply.self, from: data))?.say
+    }
+
+    static func ask(_ message: String) async throws -> Answer {
+        var req = URLRequest(url: URL(string: "\(Config.daemonURL)/ask")!)
+        req.httpMethod = "POST"
+        // An agent turn routinely takes minutes. The default 60s would cut
+        // off exactly the thoughtful answers worth waiting for.
+        req.timeoutInterval = 600
+        req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        req.httpBody = try JSONSerialization.data(withJSONObject: [
+            "message": message,
+            "agent": Config.agentID,
+        ])
+
+        let (data, response) = try await URLSession.shared.data(for: req)
+        struct UiButton: Decodable { let label: String; let url: String }
+        struct UiMedia: Decodable { let type: String; let url: String; let caption: String? }
+        struct Ui: Decodable { let buttons: [UiButton]?; let media: UiMedia? }
+        struct Reply: Decodable {
+            let text: String?
+            let full: String?
+            let ui: Ui?
+            let error: String?
+            let duration: Int?
+        }
+        let reply = try? JSONDecoder().decode(Reply.self, from: data)
+
+        // 202 means accepted-but-busy: the daemon has already written a
+        // speakable explanation into `text`. Falling through to the error
+        // path here is what made "she is still working" sound like "that
+        // didn't work".
+        if let http = response as? HTTPURLResponse, http.statusCode == 202,
+           let queuedText = reply?.text, !queuedText.isEmpty {
+            return Answer(text: queuedText, written: nil, buttons: [], imageURL: nil,
+                          durationMs: reply?.duration)
+        }
+
+        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
+            let detail = reply?.error ?? String(data: data.prefix(200), encoding: .utf8) ?? ""
+            throw VoiceError.api("daemon HTTP \(http.statusCode): \(detail)")
+        }
+        if let err = reply?.error, !err.isEmpty { throw VoiceError.api(err) }
+        guard let text = reply?.text ?? reply?.full, !text.isEmpty else {
+            throw VoiceError.api("agent returned an empty answer")
+        }
+        let buttons = (reply?.ui?.buttons ?? []).map { ($0.label, $0.url) }
+        // Only images are shown inline; a document or video is offered as a
+        // link instead, because a card that cannot play it should not
+        // pretend otherwise.
+        let media = reply?.ui?.media
+        let image = media?.type == "image" ? media?.url : nil
+        let extra: [(String, String)] = (media != nil && image == nil)
+            ? [(media!.caption ?? media!.type.capitalized, media!.url)] : []
+
+        return Answer(text: text, written: reply?.full,
+                      buttons: buttons + extra, imageURL: image,
+                      durationMs: reply?.duration)
+    }
+}

package/apps/mac-voice/Sources/AgentXVoice/Brand.swift

@@ -0,0 +1,123 @@
+import AppKit
+
+/// Acme design tokens, transcribed for AppKit.
+///
+/// Copied from the design system's `tokens/` rather than eyeballed, so the
+/// widget belongs to the same product as example.com instead of merely
+/// looking tidy. Two rules from that system shape most of what follows:
+///
+///   - Mono is UPPERCASE with 0.06–0.08em tracking, and is reserved for
+///     eyebrows, status and meta. Body stays sentence case.
+///   - No emoji, ever. Texture comes from Unicode punctuation — · → ● ✓ —
+///     and from a single accent colour, not from decoration.
+///
+/// System colours were the obvious default and the wrong one: .systemRed
+/// and .systemGreen are macOS's voice, not Acme's, and they shift under
+/// the user's accent-colour setting.
+enum Brand {
+
+    // Teal accent and deep blue primary — the two colours the whole
+    // identity rests on.
+    static let accent = NSColor(srgbRed: 0.078, green: 0.722, blue: 0.651, alpha: 1)      // #14b8a6
+    static let accentDeep = NSColor(srgbRed: 0.059, green: 0.463, blue: 0.431, alpha: 1)  // #0f766e
+    static let primary = NSColor(srgbRed: 0.118, green: 0.227, blue: 0.541, alpha: 1)     // #1e3a8a
+    static let primaryBright = NSColor(srgbRed: 0.114, green: 0.306, blue: 0.847, alpha: 1) // #1d4ed8
+
+    static let ink = NSColor(srgbRed: 0.043, green: 0.078, blue: 0.075, alpha: 1)         // #0b1413
+    static let paper = NSColor(srgbRed: 0.980, green: 0.980, blue: 0.976, alpha: 1)       // #fafaf9
+
+    /// Amber and rose for states the palette has no token for. Muted to
+    /// sit beside the teal rather than fight it.
+    static let warn = NSColor(srgbRed: 0.851, green: 0.596, blue: 0.180, alpha: 1)
+    static let alert = NSColor(srgbRed: 0.804, green: 0.400, blue: 0.376, alpha: 1)
+
+    enum Radius {
+        static let sm: CGFloat = 6
+        static let base: CGFloat = 10
+        static let md: CGFloat = 12
+        static let lg: CGFloat = 18
+        static let pill: CGFloat = 999
+    }
+
+    /// `--nq-ease` — the single easing curve the system uses everywhere.
+    static let ease = CAMediaTimingFunction(controlPoints: 0.65, 0, 0.35, 1)
+    static let durFast: CFTimeInterval = 0.15
+
+    /// Meta type: mono, uppercase, tracked. Eyebrows and status only.
+    static func meta(size: CGFloat = 10.5) -> [NSAttributedString.Key: Any] {
+        [
+            .font: NSFont.monospacedSystemFont(ofSize: size, weight: .semibold),
+            .kern: size * 0.07,
+        ]
+    }
+
+    static func metaString(_ text: String, size: CGFloat = 10.5, color: NSColor) -> NSAttributedString {
+        var attrs = meta(size: size)
+        attrs[.foregroundColor] = color
+        return NSAttributedString(string: text.uppercased(), attributes: attrs)
+    }
+
+    static func body(size: CGFloat = 13, weight: NSFont.Weight = .medium) -> NSFont {
+        NSFont.systemFont(ofSize: size, weight: weight)
+    }
+
+    /// The CSS the result card renders markdown into. Same tokens, so an
+    /// answer reads like the product it came from.
+    static let cardCSS = """
+      :root {
+        color-scheme: light dark;
+        --nq-accent: #14b8a6;
+        --nq-primary: #1e3a8a;
+        --nq-ink: #0b1413;
+        --nq-paper: #fafaf9;
+        --nq-radius-sm: 6px;
+        --nq-radius: 10px;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root { --nq-ink: #f4f4f2; --nq-primary: #93c5fd; }
+      }
+      body {
+        font: 13px/1.55 -apple-system, 'Geist', system-ui, sans-serif;
+        margin: 14px 14px 10px; color: canvastext; background: transparent;
+        word-wrap: break-word; -webkit-font-smoothing: antialiased;
+      }
+      h1, h2, h3, h4 {
+        margin: .75em 0 .3em; font-size: 1.02em; font-weight: 650;
+        letter-spacing: -0.005em;
+      }
+      h1:first-child, h2:first-child, h3:first-child { margin-top: 0; }
+      p { margin: .45em 0; }
+      ul { margin: .4em 0; padding-left: 1.15em; }
+      li { margin: .2em 0; }
+      li::marker { color: var(--nq-accent); }
+      strong { font-weight: 640; }
+      code {
+        font: 11.5px ui-monospace, 'Geist Mono', SFMono-Regular, monospace;
+        background: color-mix(in srgb, var(--nq-accent) 12%, transparent);
+        padding: 1.5px 5px; border-radius: var(--nq-radius-sm);
+      }
+      pre {
+        background: color-mix(in srgb, canvastext 7%, transparent);
+        padding: 10px 12px; border-radius: var(--nq-radius);
+        overflow-x: auto; line-height: 1.45;
+        border-left: 2px solid color-mix(in srgb, var(--nq-accent) 55%, transparent);
+      }
+      pre code { background: none; padding: 0; }
+      blockquote {
+        margin: .5em 0; padding-left: .85em;
+        border-left: 2px solid color-mix(in srgb, var(--nq-accent) 45%, transparent);
+        opacity: .85;
+      }
+      a { color: var(--nq-primary); text-underline-offset: 2px; }
+      hr {
+        border: none; margin: 1em 0;
+        border-top: 1px solid color-mix(in srgb, canvastext 14%, transparent);
+      }
+      table { border-collapse: collapse; margin: .5em 0; font-size: 12px; }
+      th, td { padding: 4px 9px; border: 1px solid color-mix(in srgb, canvastext 14%, transparent); }
+      th {
+        font: 10px ui-monospace, monospace; text-transform: uppercase;
+        letter-spacing: .07em; text-align: left; font-weight: 600;
+      }
+    """
+}

package/apps/mac-voice/Sources/AgentXVoice/Config.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+/// Everything the widget needs to find, resolved once at launch.
+///
+/// Keys are read from files first and the environment second, because a
+/// GUI app launched from Finder inherits almost nothing from a login
+/// shell — an app that only reads the environment works when you run it
+/// from a terminal and mysteriously fails when you double-click it.
+enum Config {
+    static let daemonURL = env("AGENTX_DAEMON_URL") ?? "http://127.0.0.1:18800"
+    static let agentID = env("AGENTX_VOICE_AGENT") ?? "secretary-agent"
+
+    /// ElevenLabs default voice. Override with AGENTX_VOICE_ID.
+    static let voiceID = env("AGENTX_VOICE_ID") ?? "21m00Tcm4TlvDq8ikWAM"
+    static let sttModel = env("AGENTX_STT_MODEL") ?? "scribe_v1"
+
+    /// How to invoke smart paste. Run through a login shell, so this is a
+    /// command line rather than a path.
+    ///
+    /// Environment, then a file, then a guess — the same order as the keys
+    /// below and for the same reason, with one extra: `agentx` on PATH is
+    /// very often the WRONG agentx. It is commonly a globally installed
+    /// copy of the published package rather than the local build, so it
+    /// silently lacks anything unreleased, and a login shell may resolve
+    /// `node` to a version old enough that the CLI will not start at all.
+    /// Both were true on the machine this was written on. The file is how
+    /// a machine says which build it actually means.
+    /// How to invoke `agentx notify`. Derived from pasteCommand so a
+    /// machine only has to say once where its agentx lives.
+    static var notifyCommand: String {
+        pasteCommand.replacingOccurrences(of: " paste", with: " notify")
+    }
+
+    static let pasteCommand: String = {
+        if let c = env("AGENTX_PASTE_COMMAND"), !c.isEmpty { return c }
+        if let s = try? String(contentsOfFile: "\(NSHomeDirectory())/.agentx/paste-command.txt",
+                               encoding: .utf8) {
+            let t = s.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !t.isEmpty { return t }
+        }
+        return "agentx paste"
+    }()
+    static let ttsModel = env("AGENTX_TTS_MODEL") ?? "eleven_turbo_v2_5"
+
+    static let mlxWhisper = env("AGENTX_MLX_WHISPER")
+        ?? "\(NSHomeDirectory())/.local/bin/mlx_whisper"
+    static let mlxModel = env("AGENTX_MLX_MODEL") ?? "mlx-community/whisper-large-v3-turbo"
+
+    /// nil when no key is available anywhere — the app still runs, falling
+    /// back to local STT and `say`, which is the whole point of having a
+    /// fallback rather than refusing to start.
+    static let elevenLabsKey: String? = {
+        if let k = env("ELEVENLABS_API_KEY"), !k.isEmpty { return k }
+        for path in ["\(NSHomeDirectory())/.elevenlabs/key",
+                     "\(NSHomeDirectory())/.agentx/elevenlabs-key.txt"] {
+            if let s = try? String(contentsOfFile: path, encoding: .utf8) {
+                let t = s.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !t.isEmpty { return t }
+            }
+        }
+        return nil
+    }()
+
+    private static func env(_ k: String) -> String? {
+        guard let v = ProcessInfo.processInfo.environment[k], !v.isEmpty else { return nil }
+        return v
+    }
+}

package/apps/mac-voice/Sources/AgentXVoice/Hold.swift

@@ -0,0 +1,74 @@
+import Foundation
+
+/// "Don't interrupt me" — the widget's own switch.
+///
+/// Separate from macOS Focus on purpose. System Focus is a heavy
+/// instrument: it silences every device you own and announces itself to
+/// everyone who messages you, which is far more than someone means when
+/// they only want to finish a thought. A switch on the widget is a hold
+/// you flick on for twenty minutes and forget.
+///
+/// The state lives in a file rather than in this process because the
+/// thing that HONOURS it is not this process — `agentx notify` runs in the
+/// daemon and in agents' shells, and none of them can ask a widget a
+/// question. A file is the smallest thing all of them can read.
+///
+/// Either source counts as held: agentx checks this file and the system's
+/// Focus database, and neither overrides the other. They are the same
+/// person saying the same thing by different means.
+enum Hold {
+
+    private static let path: URL = {
+        let dir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent(".agentx", isDirectory: true)
+        return dir.appendingPathComponent("focus.json")
+    }()
+
+    /// Is the widget currently holding notifications?
+    static var isOn: Bool {
+        guard let data = try? Data(contentsOf: path),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return false }
+        return (obj["active"] as? Bool) ?? false
+    }
+
+    /// Turn the hold on or off. Returns the new state.
+    @discardableResult
+    static func set(_ on: Bool) -> Bool {
+        let payload: [String: Any] = [
+            "active": on,
+            "since": ISO8601DateFormatter().string(from: Date()),
+            // Recorded so an operator reading the file knows which switch
+            // produced it — the widget's, not a stale test fixture.
+            "source": "widget",
+        ]
+        do {
+            try FileManager.default.createDirectory(
+                at: path.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let data = try JSONSerialization.data(withJSONObject: payload, options: [.prettyPrinted])
+            try data.write(to: path, options: .atomic)
+        } catch {
+            Log.warn("could not write the hold state: \(error.localizedDescription)")
+        }
+        return on
+    }
+
+    @discardableResult
+    static func toggle() -> Bool { set(!isOn) }
+
+    /// Ask agentx to deliver anything that piled up while the hold was on.
+    ///
+    /// Fire-and-forget through the same command line the widget uses for
+    /// smart paste, so there is one place that knows how to find the CLI.
+    static func flushHeld() {
+        DispatchQueue.global(qos: .utility).async {
+            let process = Process()
+            process.executableURL = URL(fileURLWithPath: "/bin/zsh")
+            process.arguments = ["-lc", Config.notifyCommand + " --flush"]
+            process.standardOutput = Pipe()
+            process.standardError = Pipe()
+            try? process.run()
+            process.waitUntilExit()
+        }
+    }
+}

package/apps/mac-voice/Sources/AgentXVoice/Hotkey.swift

@@ -0,0 +1,76 @@
+import AppKit
+import Carbon.HIToolbox
+
+/// Global push-to-talk hotkey, default ⌥Space.
+///
+/// Carbon's RegisterEventHotKey rather than an NSEvent global monitor,
+/// because the monitor route requires Accessibility permission and this
+/// slice should need nothing but the microphone. Carbon also reports key
+/// RELEASE, which is what makes hold-to-talk possible at all.
+///
+/// ⌥Space and not ⌃Space: control-space is bound to input-source switching
+/// on many Macs, and silently stealing it is a bad first impression.
+///
+/// Each instance carries its own `id` and IGNORES events for any other.
+/// That is not decoration: every installed handler is called for EVERY
+/// registered hotkey, so a second binding without this filter makes both
+/// actions fire on either key.
+final class Hotkey {
+    private var ref: EventHotKeyRef?
+    private var handler: EventHandlerRef?
+    private let onPress: () -> Void
+    private let onRelease: () -> Void
+    private let id: UInt32
+
+    init(id: UInt32 = 1, onPress: @escaping () -> Void, onRelease: @escaping () -> Void) {
+        self.id = id
+        self.onPress = onPress
+        self.onRelease = onRelease
+    }
+
+    func register(keyCode: UInt32 = UInt32(kVK_Space), modifiers: UInt32 = UInt32(optionKey)) {
+        var spec = [
+            EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: UInt32(kEventHotKeyPressed)),
+            EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: UInt32(kEventHotKeyReleased)),
+        ]
+        let context = Unmanaged.passUnretained(self).toOpaque()
+        InstallEventHandler(GetApplicationEventTarget(), { _, event, ctx in
+            guard let ctx, let event else { return noErr }
+            let me = Unmanaged<Hotkey>.fromOpaque(ctx).takeUnretainedValue()
+
+            // Whose key was it? Handlers are global, so this instance must
+            // discard anything that is not its own.
+            //
+            // Filter ONLY on a successful lookup. Ignoring the status here
+            // left `fired` zero-initialised whenever the call failed, so
+            // the guard rejected every event and BOTH hotkeys went dead —
+            // silently, because a hotkey that does nothing looks exactly
+            // like a hotkey that was never pressed.
+            //
+            // Falling through on failure is the right degradation: the
+            // worst case is the older bug where both bindings react to
+            // either key, which is visible and recoverable. Silence is
+            // neither.
+            var fired = EventHotKeyID()
+            let status = GetEventParameter(
+                event, EventParamName(kEventParamDirectObject),
+                EventParamType(typeEventHotKeyID), nil,
+                MemoryLayout<EventHotKeyID>.size, nil, &fired)
+            if status == noErr, fired.id != me.id { return noErr }
+
+            let kind = GetEventKind(event)
+            DispatchQueue.main.async {
+                if kind == UInt32(kEventHotKeyPressed) { me.onPress() } else { me.onRelease() }
+            }
+            return noErr
+        }, spec.count, &spec, context, &handler)
+
+        let hotKeyID = EventHotKeyID(signature: OSType(0x41475856), id: id) // 'AGXV'
+        RegisterEventHotKey(keyCode, modifiers, hotKeyID, GetApplicationEventTarget(), 0, &ref)
+    }
+
+    deinit {
+        if let ref { UnregisterEventHotKey(ref) }
+        if let handler { RemoveEventHandler(handler) }
+    }
+}

package/apps/mac-voice/Sources/AgentXVoice/Markdown.swift

@@ -0,0 +1,140 @@
+import Foundation
+
+/// Markdown to HTML, small and dependency-free.
+///
+/// Agents write markdown by default — headings, bullets, fenced code,
+/// tables. Rendered as plain text it is a mess of asterisks and hashes,
+/// which is worse than useless when the whole point of the card is that
+/// the written answer is more readable than the spoken one.
+///
+/// A real parser would be better and is not worth a dependency here. This
+/// handles what agents actually produce; anything it does not recognise
+/// falls through as text rather than breaking the page.
+enum Markdown {
+
+    /// Fallback styling when no design tokens are supplied.
+    static let defaultCSS = """
+      body { font: -apple-system-body; font-size: 13px; margin: 12px; line-height: 1.5;
+             color: canvastext; background: transparent; word-wrap: break-word; }
+      code { font: ui-monospace, monospace; font-size: 12px;
+             background: color-mix(in srgb, canvastext 10%, transparent);
+             padding: 1px 4px; border-radius: 4px; }
+      pre { background: color-mix(in srgb, canvastext 8%, transparent);
+            padding: 8px 10px; border-radius: 6px; overflow-x: auto; }
+      a { color: linktext; }
+    """
+
+
+    static func toHTML(_ markdown: String) -> String {
+        var html = ""
+        var inCode = false
+        var listDepth = 0
+
+        func closeList() {
+            while listDepth > 0 { html += "</ul>"; listDepth -= 1 }
+        }
+
+        for rawLine in markdown.components(separatedBy: .newlines) {
+            let line = rawLine
+
+            // Fenced code: everything inside is literal, including things
+            // that would otherwise look like markdown.
+            if line.trimmingCharacters(in: .whitespaces).hasPrefix("```") {
+                if inCode { html += "</code></pre>" } else { closeList(); html += "<pre><code>" }
+                inCode.toggle()
+                continue
+            }
+            if inCode { html += escape(line) + "\n"; continue }
+
+            let trimmed = line.trimmingCharacters(in: .whitespaces)
+            if trimmed.isEmpty { closeList(); html += "<p></p>"; continue }
+
+            // Headings
+            if let h = heading(trimmed) {
+                closeList()
+                html += "<h\(h.level)>\(inline(h.text))</h\(h.level)>"
+                continue
+            }
+
+            // Bullets and numbered items, both rendered as a list — the
+            // marker style matters far less than the indentation reading
+            // correctly.
+            if let item = listItem(trimmed) {
+                if listDepth == 0 { html += "<ul>"; listDepth = 1 }
+                html += "<li>\(inline(item))</li>"
+                continue
+            }
+
+            if trimmed.hasPrefix("> ") {
+                closeList()
+                html += "<blockquote>\(inline(String(trimmed.dropFirst(2))))</blockquote>"
+                continue
+            }
+
+            // Horizontal rule
+            if trimmed == "---" || trimmed == "***" { closeList(); html += "<hr>"; continue }
+
+            closeList()
+            html += "<p>\(inline(trimmed))</p>"
+        }
+        closeList()
+        if inCode { html += "</code></pre>" }
+        return html
+    }
+
+    private static func heading(_ line: String) -> (level: Int, text: String)? {
+        var level = 0
+        var rest = Substring(line)
+        while rest.first == "#" && level < 6 { level += 1; rest = rest.dropFirst() }
+        guard level > 0, rest.first == " " else { return nil }
+        return (level, String(rest.dropFirst()))
+    }
+
+    private static func listItem(_ line: String) -> String? {
+        for marker in ["- ", "* ", "+ "] {
+            if line.hasPrefix(marker) { return String(line.dropFirst(marker.count)) }
+        }
+        // "1. item"
+        if let dot = line.firstIndex(of: "."), line[line.startIndex..<dot].allSatisfy(\.isNumber),
+           line.index(after: dot) < line.endIndex, line[line.index(after: dot)] == " " {
+            return String(line[line.index(dot, offsetBy: 2)...])
+        }
+        return nil
+    }
+
+    /// Inline spans. Order matters: code first, so its contents are not
+    /// then treated as emphasis.
+    private static func inline(_ text: String) -> String {
+        var s = escape(text)
+        s = replace(s, #"`([^`]+)`"#, "<code>$1</code>")
+        s = replace(s, #"\*\*([^*]+)\*\*"#, "<strong>$1</strong>")
+        s = replace(s, #"(?<![\*\w])\*([^*]+)\*(?![\*\w])"#, "<em>$1</em>")
+        s = replace(s, #"\[([^\]]+)\]\(([^)\s]+)\)"#, "<a href=\"$2\">$1</a>")
+        // Bare URLs, but not ones already inside an href.
+        s = replace(s, #"(?<!["=])\b(https?://[^\s<)]+)"#, "<a href=\"$1\">$1</a>")
+        return s
+    }
+
+    private static func replace(_ s: String, _ pattern: String, _ template: String) -> String {
+        guard let re = try? NSRegularExpression(pattern: pattern) else { return s }
+        return re.stringByReplacingMatches(
+            in: s, range: NSRange(s.startIndex..., in: s), withTemplate: template)
+    }
+
+    private static func escape(_ s: String) -> String {
+        s.replacingOccurrences(of: "&", with: "&amp;")
+         .replacingOccurrences(of: "<", with: "&lt;")
+         .replacingOccurrences(of: ">", with: "&gt;")
+    }
+
+    /// Wraps rendered HTML in a page that follows the system appearance.
+    /// A card that is white while everything else is dark is worse than
+    /// plain text.
+    static func page(_ body: String, css: String? = nil) -> String {
+        """
+        <!doctype html><html><head><meta charset="utf-8">
+        <style>\(css ?? defaultCSS)</style>
+        </head><body>\(body)</body></html>
+        """
+    }
+}